What's New in v25.3

Docker image

Multi-platform images include support for both Intel and ARM. Multi-platform images do not take up additional space on your Docker host.

Within the multi-platform image, both Intel and ARM images are generally available for production use.

To download the Docker image:

docker pull cockroachdb/cockroach-unstable:v25.3.0-alpha.1

Source tag

To view or download the source code for CockroachDB v25.3.0-alpha.1 on Github, visit v25.3.0-alpha.1 source tag.

Security updates

• The client for the SQL connection will now receive an error along with an error in the OPS channel if trying to connect with an unsupported cipher. #146522

General changes

• Enhanced the /status/v2/hotranges endpoint by adding two new filtering options:
  • per_node_limit (int32): Specifies the maximum number of hot ranges to return per node. Defaults to 128 if not set.
  • stats_only (bool): When set to true, returns only the statistics for hot ranges without fetching descriptor information, such as databases, tables, and indexes. #144091
• Changefeeds now round down the progress of each range to 1 second, in order to cover more ranges in fine-grained checkpointing. #146979
• Reduced the maximum backoff for changefeed retries from 10 minutes to 1 minute, which results in faster recovery from transient errors. #146448
• The secret keys in Azure cloud storage URIs are now redacted. #147022

SQL language changes

• Added a new session variable create_table_with_schema_locked, which can be used to ensure all tables created by a session have the storage parameter schema_locked set. #143892

• The following syntax is now supported:

  • GRANT ... ON ALL ROUTINES IN SCHEMA ...
  • REVOKE ... ON ALL ROUTINES IN SCHEMA ...
  • ALTER DEFAULT PRIVILEGES GRANT ... ON ROUTINES ...
  • ALTER DEFAULT PRIVILEGES REVOKE ... ON ROUTINES ...

  The ROUTINES keyword makes the command apply to both functions and stored procedures. Note that ALTER DEFAULT PRIVILEGES ... ON FUNCTIONS already applied to stored procedures (which aligns with the PostgreSQL behavior), and that is not changing. #144189

• The variable arguments of polymorphic built-in functions (e.g., concat, num_nulls, format, concat_ws) no longer need to have the same type, matching PostgreSQL behavior. As a result, CockroachDB's type inference engine will no longer be able to infer argument types in some cases where it previously could, and there is a possibility that CockroachDB applications will encounter new errors. The new session variable use_pre_25_2_variadic_builtins restores the previous behavior (and limitations). #144522

• Added new cluster settings: sql.metrics.application_name.enabled and sql.metrics.database_name.enabled. These settings default to false and can be set to true to display the application name and database name, respectively, on supported metrics. #144610

• Added support for query tagging, which allows users to add query tags to their SQL statements via comments. These query tags are included in:

  • All log entries generated during the execution of a SQL statement and are prefixed by querytag-.
  • Traces and are prefixed by querytag-.
  • In the crdb_internal.cluster_execution_insights and crdb_internal.node_execution_insights virtual tables in a new query_tags JSONB column. This feature is disabled by default and can be enabled using the sql.sqlcommenter.enabled cluster setting. Comments must follow the SQLCommenter specification. #145435

• ~~* and !~~* are now supported aliases for ILIKE and NOT ILIKE. #146764

• The information_schema.triggers table is now populated with trigger metadata. Users can query this table to see all triggers defined in their database, including the trigger name, timing (BEFORE/AFTER), event type (INSERT/UPDATE/DELETE), and associated function. Each trigger event appears as a separate row in the table. #147237

• The pg_catalog.pg_trigger table now returns metadata about database triggers. #147248

• Deterministic collations are now supported with LIKE. A deterministic collation considers strings to be equal only if they consist of the same byte sequence. #147045

• Assigning to an element of a composite-typed variable in a PL/pgSQL routine now respects case-sensitivity rules. For example, a field named "FOO_Bar" can be assigned like NEW."FOO_Bar" = 100. #143579

Operational changes

• Prometheus metrics are now also available at the /metrics endpoint, in addition to the existing /_status/vars endpoint. The new /metrics endpoint emits statically labeled metrics and will evolve more rapidly as CockroachDB migrates metrics to use labels instead of defining different metric names. For compatibility, users can continue to use /_status/vars, where metric names will remain stable. #143536
• Added the new latency metrics: sql.service.latency.historical, sql.service.latency.consistent, sql.exec.latency.historical, and sql.exec.latency.consistent for easier query optimizations. #142826
• Partial index schema changes are supported in replicating tables when logical_replication.consumer.immediate_mode_writer is not set to legacy-kv. #144508
• The cluster setting server.client_cert_expiration_cache.capacity has been deprecated. The client certificate cache now evicts client certificates based on expiration time. #144181
• Logs for hot ranges (hot_ranges_stats events) have been moved to the HEALTH logging channel. #144567
• Added a new metric, kv.loadsplitter.cleardirection, which increments when the load-based splitter observes that more than 80% of replica access samples are moving in a single direction (either left/descending or right/ascending). #143927
• When the server.telemetry.hot_ranges_stats.enabled cluster setting is enabled, nodes check for hot ranges every minute instead of every 4 hours. A node logs its hot ranges when any single replica exceeds 250 ms of CPU time per second. In multi-tenant deployments, the check runs every 5 minutes and logs hot ranges for the entire cluster. #144414
• Added the metric changefeed.checkpoint.timestamp_count that measures the number of unique timestamps in a changefeed span-level checkpoint. It may be useful to monitor this metric to determine if quantization settings should be changed. #145117
• In a physical cluster replication (PCR) deployment, it is not possible for the standby system virtual cluster, or the reader virtual cluster to upgrade the reader virtual cluster by setting the version cluster setting. It is necessary to:
  1. Upgrade the standby system virtual cluster.
  2. Upgrade the primary system virtual cluster.
  3. Upgrade the primary virtual cluster.
  4. Wait for the replicated time to advance past the time the primary virtual cluster upgraded.
  5. Shut down the reader virtual cluster.
  6. Upgrade the destination host cluster.
  7. Re-initialize the reader virtual cluster with ALTER VIRTUAL CLUSTER SET REPLICATION READ VIRTUAL CLUSTER. #146127
• Added job tracing support to changefeeds. #144412

Command-line changes

• Node attributes (attrs) will now appear in the node status CLI command. #143421
• Updated the \d <table name> command to show policy and Row Level Security information similar to what is shown in the output of SHOW CREATE TABLE. #146215
• Added the --validate-zip-file flag to the cockroach debug zip command. This flag performs a quick validation check to ensure that the generated zip file is not corrupted. The flag is enabled by default. #146192
• The SQL shell now supports the compact output mode when auto_trace is enabled. #146432

DB Console changes

• Schema insights that recommend replacing an index were previously a two-statement command consisting of a CREATE INDEX and a DROP INDEX statement. When these two DDL statements were run as a single batched command, it was possible for one statement to succeed and one to fail. This is because DDL statements do not have the same atomicity guarantees as other SQL statements in CockroachDB. Index-replacement insights are now a single CREATE INDEX statement followed by a comment with additional DDL statements to be run manually: an ALTER INDEX ... NOT VISIBLE statement, which makes the old index invisible to the optimizer, followed by a DROP INDEX statement that should only be run after making the old index invisible and verifying that workload performance is satisfactory. #144101
• Updated the titles of the disk throughput graphs on the Metrics page Hardware dashboard to display only "Bytes/s" instead of including a specific magnitude, "MiB/s". The titles of the graphs are now “"Disk Read Bytes/s" and "Disk Write Bytes/s". #147462

Bug fixes

• Fixed a bug where using values changefeed.aggregator.flush_jitter, min_checkpoint_frequency such that changefeed.aggregator.flush_jitter * min_checkpoint_frequency < 1 would cause a panic. Jitter will now be disabled in this case. #144304
• Fixed a bug that could cause queries that perform work in parallel to ignore the requested quality-of-service level. Affected operations include lookup joins, DistSQL execution, and foreign-key checks. #144427
• Improved the performance of SHOW CREATE TABLE on multi-region databases with large numbers of objects. #144900
• Fixed a bug where running DROP INDEX on a hash-sharded index did not properly detect dependencies from functions and procedures on the shard column. This caused the DROP INDEX statement to fail with an internal validation error. Now the statement returns a correct error message, and using DROP INDEX ... CASCADE works as expected by dropping the dependent functions and procedures. #145107
• Fixed a bug that prevented variable references using ordinal syntax (like $1) from reflecting updates to the variable. Referencing variables declared in PL/pgSQL blocks (instead of parameters) via ordinal syntax is now disallowed. The bug had existed since v24.1. #144347
• Fixed a bug that caused index expression elements of primary keys to be shown incorrectly in the output of SHOW CREATE TABLE. #144716
• Fixed a bug that could lead to schema changes hanging after a cluster recovered from availability issues. #145462
• Previously, on a table with multiple column families, CockroachDB could encounter a Non-nullable column "‹×›:‹×›" with no value error in rare cases during table statistics collection. The bug was present since v19.2 and is now fixed. #145481
• Fixed a bug that could cause a row-level TTL job to fail with the error "comparison of two different versions of enum" if an ENUM type referenced by the table experienced a schema change. #145374
• Fixed a bug where the physical cluster replication (PCR) reader catalog job could hit validation errors when schema objects had dependencies between them (for example, when a sequence's default expression was being removed). #145972
• Creating a vector index on a table that contains a NULL vector value will no longer cause an internal error. #145983
• Fixed an internal assertion failure that could occur during operations like ALTER TYPE or ALTER DATABASE ... ADD REGION when temporary tables were present. #145551
• Row-level security (RLS) SELECT policies during UPDATE operations are now only applied when referenced columns appear in the SET or WHERE clauses, matching the behavior of PostgreSQL. This improves compatibility. #145344
• Fixed an issue where using inline log configuration could cause internal errors on the DB Console's Logs page for a node at #/node/{nodeID}/logs. #145329
• Fixed an integer overflow in the split_part function when using extremely negative field positions like Go's math.MinInt64. #146271
• Fixed incorrect application of SELECT policies to RETURNING clauses in INSERT and UPDATE when no table columns were referenced. #145890
• Fixed a bug that prevented TRUNCATE from succeeding if any indexes on the table had back-reference dependencies, such as from a view or function referencing the index. #146287
• Fixed a bug where ALTER TABLE operations with multiple commands could generate invalid zone configurations. #146369
• Fixed a bug where an invalid comment in the system.comment table for a schema object could make it inaccessible. #146213
• Fixed a bug where a CockroachDB node could crash when executing DO statements that contain currently unsupported DDL statements like CREATE TYPE in a non-default configuration (additional logging needed to be enabled, e.g., via the sql.log.all_statements.enabled cluster setting). This bug was introduced in v25.1. #146406
• Prevent use of future timestamps when using AS OF SYSTEM TIME with CREATE TABLE ... AS and materialized views. Previously, such timestamps could cause errors, delays, or hangs. #146446
• Fixed an internal error that could be hit when ADD COLUMN UNIQUE and ALTER PRIMARY KEY were executed within the same transaction. #146567
• Fixed a bug that prevented temporary views and sequences from being created if the pg_temp schema was explicitly specified in the qualified name of the object being created. #146586
• Fixed a bug where CockroachDB would not use the vectorized fast path for COPY when it was supported. The bug was only present in previous v25.2 releases. #146696
• Errors triggered by DB Console activity no longer cause the node to crash. #145563
• Fixed a bug to prevent HTTP connections from stopping server shutdown. #146744
• The MVCC timestamp is now emitted correctly when the mvcc_timestamp is used with CDC queries. #146836
• Fixed a bug in v25.2.0 where a vector search operator could drop user-supplied filters if the same vector column was indexed twice and a vector index with no prefix columns was defined after a vector index with prefix columns. #146259
• Fixed a bug that could cause the cockroach process to segfault when collecting runtime execution traces (typically collected via the Advanced Debug page in the Console). #146883
• Fixed a data race in the cloudstorage sink. #146297
• Fixed a bug where the kv.rangefeed.closed_timestamp.slow_ranges would not be incremented when a rangefeed closed timestamp was slower than the target threshold. #146949
• Fixed a bug that could cause an AFTER trigger to fail with client already committed or rolled back the transaction if the query also contained foreign-key cascades. The bug had existed since AFTER triggers were introduced in v24.3. #146890
• Prevent dropping columns or indexes that are still referenced by triggers. Previously, these operations could succeed silently, potentially breaking trigger functionality. #146683
• Fixed a bug where searching a vector with a query vector that doesn't match the dimensions of the vector column in the table would cause a node to crash. #146848
• Specifying types for a subset of columns in a generator function's column definition list now results in a syntax error instead of an internal error. #145492
• Fixed a bug that caused the SQL Activity > Statement Fingerprint page to fail to load details for statements run with application names containing a # character. #147021
• CockroachDB could previously incorrectly evaluate to_regclass, to_regnamespace, to_regproc, to_regprocedure, to_regrole, and to_regtype builtin functions when the query using them happened to be evaluated in distributed fashion. The bug has been present since the introduction of these builtins in v23.1 and is now fixed. #147362
• Fixed a bug that caused the optimizer to ignore index hints when optimizing some forms of prepared statements. This could result in one of two unexpected behaviors: a query errors with the message index cannot be used for this query when the index can actually be used; or a query uses an index that does not adhere to the hint. The hints relevant to this bug are regular index hints, e.g., SELECT * FROM tab@index, FORCE_INVERTED_INDEX, and FORCE_ZIGZAG. #147368
• Fixed a bug where the pg_catalog.pg_policy table could contain duplicate OID values when multiple tables had policies with the same policy ID. All rows in pg_policy now have unique OIDs as required. #147373
• Fixed a bug where the rolbypassrls column in pg_roles and pg_authid tables always returned false, even for roles with the BYPASSRLS option. #147357
• Fixed a bug that could cause stable expressions to be folded in cached query plans. The bug could cause stable expressions like current_setting to return the wrong result if used in a prepared statement. The bug was introduced in point releases v23.2.22, v24.1.14, v24.3.9, and v25.1.2, and the v25.2 alpha. #147187
• Fixed an issue where updating child metrics and reinitializing metrics at the same time could cause scrape errors. #147486
• Fixed a runtime panic in the substring_index function that occurred when the count argument was the minimum 64-bit integer value. #147546
• Fixed a memory leak in index backfill jobs where completed spans were duplicated in memory on each progress update after resuming from a checkpoint. This could cause out-of-memory (OOM) errors when backfilling indexes on large tables with many ranges. This bug affected release version v25.2.0 and pre-release versions v25.2.0-alpha.3 through v25.2.0-rc.1. #147511
• Fixed a bug where prepared statements on schema changes could fail with runtime errors. #147658
• Fixed an issue with logical data replication (LDR) where the presence of a unique index may cause spurious dead letter queue (DLQ) entries if the unique index has a smaller index ID than the primary key index. #147117
• Scheduled backups now prevent multiple compaction jobs from running in parallel on its backups. #145930
• Removal of triggers during a restore now accounts for back references that existed because of triggers. #147306

Performance improvements

• Prepared statements are now more efficiently cached. #144021
• TTL jobs now respond to cluster topology changes by restarting and rebalancing across available nodes. #145214