What's New in v25.2

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.2.0-alpha.1

Source tag

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

Backward-incompatible changes

• The default value of the autocommit_before_ddl session variable is now true. This will cause any schema change statement that is sent during a transaction to make the current transaction commit before executing the schema change in a separate transaction. CockroachDB does not have full support for multiple schema changes in a transaction. Users who do not want the autocommit behavior can preserve the previous behavior by changing the default value of autocommit_before_ddl with: ALTER ROLE ALL SET autocommit_before_ddl = false;. #139871

Security updates

• Added the server.oidc_authentication.provider.custom_ca cluster setting to support custom root CA for verifying certificates while authenticating with the OIDC provider. #140583

General changes

• When changefeeds are created with a resolved option lower than the min_checkpoint_frequency option, an error message was displayed to inform the user. This message is now a notice and includes extra information if either option was set to its default value. #142094
• Added the logging of changefeed_canceled events to the telemetry log. #142139
• Updated the response headers of HTTP requests to include "Cache-control: no-store" instead of "Cache-control:no-cache", which means that HTTP requests to the server will no longer be cached in the client. Requests for UI assets, such as bundle.js and fonts, will still include "Cache-control:no-cache" to ensure they are cached and that the DB console loads quickly. #142277
• Added the headers_json_column_name option to the Kafka sink, allowing users to specify a column in their table(s) of type JSONB to be used as the Kafka headers for each row. #142092
• Improved S3 credential caching for STS credentials. #142434

SQL language changes

• SHOW JOBS is now based on a new mechanism for storing information about the progress and status of running jobs. #138104
• SHOW VIRTUAL CLUSTER WITH REPLICATION STATUS now displays the ingestion_job_id column after the name column. #138967
• Since v23.2 table statistics histograms have been collected for non-indexed JSON columns. Histograms are no longer collected for these columns. This reduces memory usage during table statistics collection, for both automatic and manual collection via ANALYZE and CREATE STATISTICS. This can be reverted by setting the cluster setting sql.stats.non_indexed_json_histograms.enabled to true. #139766
• optimizer_use_merged_partial_statistics is now enabled by default, meaning the optimizer will use partial stats if available to estimate more up-to-date statistics. #139925
• The optimizer_prefer_bounded_cardinality session setting has been added that instructs the optimizer to prefer query plans where every expression has a guaranteed upper-bound on the number of rows it will process. This may help the optimizer produce better query plans in some cases. This setting is disabled by default. #139985
• The optimizer_min_row_count session setting has been added that sets a lower bound on row count estimates for relational expressions during query planning. A value of 0, which is the default, indicates no lower bound. If this is set to a value greater than 0, a row count of 0 can still be estimated for expressions with a cardinality of 0, e.g., for a contradictory filter. Setting this to a value higher than 0, such as 1, may yield better query plans in some cases, such as when statistics are frequently stale and inaccurate. #140065
• Fixed a bug existing only in pre-release versions of v25.1 that could cause unexpected errors during planning for VALUES expressions containing function calls with multiple overloads. #140277
• The optimizer_check_input_min_row_count session setting has been added to control the minimum row count estimate for buffer scans of foreign key and uniqueness checks. It defaults to 0. #140735
• Added the jsonpath type, without parsing, evaluation, or table creation. Currently accepts any non-empty string. #140204
• Added the substring_index built-in function, which extracts a portion of a string based on a specified delimiter and occurrence count, which follows MySQL behavior. #141929
• Added compression support for changefeed webhook sinks. This reduces network bandwidth and storage usage, improving performance and lowering costs. Users can enable compression by setting the compression=<algorithm> option. Supported algorithms are gzip and zstd. #138872
• Holdable cursors declared using CURSOR WITH HOLD are now supported. A holdable cursor fully executes a query upon transaction commit and stores the result in a row container, which is maintained by the session. #141943
• The split_part built-in function now supports negative return_index_pos values, returning the |n|th field from the end when specified. #141944
• Added a parser for the jsonpath type. Accepts setting mode (strict/lax), key accessors (.name), and array wildcards ([*]). #142010
• Added the new option WITH IGNORE_FOREIGN_KEYS to the SHOW CREATE TABLE statement so that foreign key constraints are not included in the output schema. This option is also acceptable in SHOW CREATE VIEW, but has no influence there. It cannot be combined with the existing WITH REDACT option. #142151
• CREATE TABLE AS SELECT ... FROM ... AS OF SYSTEM TIME x is now supported. It cannot be executed within an explicit transaction. #142147
• Invocations of stored procedures via CALL statements will now be counted toward the newly added sql.call_stored_proc.count.started and sql.call_stored_proc.count metrics. Previously, they were counted against the sql.misc.count.started and sql.misc.count metrics. #142249
• Statements such as REFRESH MATERIALIZED VIEW and CREATE MATERIALIZED VIEW can now be executed with an AS OF SYSTEM TIME clause. These statements can still not be used in an explicit transaction. #142259
• Added support for the following in the jsonpath parser:
  • Double-quoted key accessors within jsonpath (SELECT '$."1key"."key2"'::JSONPATH;).
  • Array integer indexing (ex. $.a[1]).
  • Array ranges (ex. $.a[1 to 3]).
  • Array unions (ex $.a[1, 2 to 4, 7, 8]). #142241
• Fixed a regression due to join-elimination rules that left a Project operator below a JOIN, preventing optimizer rules from applying. #142252
• Added ALTER VIRTUAL CLUSTER .. SET REPLICATION SOURCE so users can configure the producer jobs on the source cluster for physical cluster replication (PCR). Currently, they can only configure the EXPIRATION WINDOW. This patch also removes the EXPIRATION WINDOW option from the consumer side of the statement, ALTER VIRTUAL CLUSTER SET REPLICATION. #142501
• Added the jsonb_path_query function, which takes in a JSON object and a jsonpath query, and returns the resulting JSON object. #142336
• Updated the CREATE TRIGGER statement only implemented in the declarative schema changer error message to include a helpful suggestion and link to relevant docs. #141738

Operational changes

• Removed the storage.queue.store-failures metric. #139150
• Customers must provide URIs as external connections to create logical data replication (LDR) statements. #139383
• The following cluster settings have been deprecated:
  • sql.metrics.statement_details.plan_collection.enabled
  • sql.metrics.statement_details.plan_collection.period #138042
• Reduced noise when using dynamically provisioned logging sinks. #139565
• Added metrics for monitoring changefeed span-level checkpoint creation:
  • changefeed.checkpoint.create_nanos, which measures the time it takes to create a changefeed checkpoint.
  • changefeed.checkpoint.total_bytes, which measures the total size of a changefeed checkpoint in bytes.
  • changefeed.checkpoint.span_count, which measures the number of spans in a changefeed checkpoint. #139375
• The following schema changes are now allowlisted to run during LDR.
  • ALTER INDEX RENAME.
  • ALTER INDEX .. NOT VISIBLE.
  • ALTER TABLE .. ALTER COLUMN .. SET DEFAULT.
  • ALTER TABLE .. ALTER COLUMN .. DROP DEFAULT.
  • ALTER TABLE .. ALTER COLUMN SET VISIBLE. #141858
• Added sql.statement_timeout.count to track the number of SQL statements that fail due to exceeding the statement timeout. #142078
• Added the sql.transaction_timeout.count metric to track the number of SQL statements that fail due to exceeding the transaction timeout. #142105
• Added the jobs.row_level_ttl.num_delete_batch_retries metric to track the number of times the TTL job had to reduce the batch size and try again. #141953
• To create a logical data replication (LDR) stream, users require the REPLICATIONDEST privilege, instead of the REPLICATION privilege. #142345
• To create a physical cluster replication (PCR) stream, users require the REPLICATIONDEST privilege, in addition to the already required MANAGEVIRTUALCLUSTER privilege. #142345
• Removed the kv.snapshot_receiver.excise.enable cluster setting. Excise is now enabled unconditionally. #142651
• Introduced the cluster setting server.child_metrics.include_aggregate.enabled, which modifies the behavior of Prometheus metric reporting (/_status/vars). By default, it is set to true, which maintains the existing behavior. It can be sert to false to stop the reporting of the aggregate time series that prevents issues with double counting when querying metrics. #141601
• When configuring the sql.ttl.default_delete_rate_limit cluster setting, a notice is displayed informing that the TTL rate limit is per leaseholder per node with a link to the docs. #142061
• Added a new envelope type enriched for changefeeds. #140112
• Added support for the enriched envelope type to Avro format changefeeds. #140525
• The cluster setting changefeed.new_webhook_sink_enabled/changefeed.new_webhook_sink.enabled is no longer supported. The new webhook sink has been enabled by default since v23.2, and the first version webhook sink has been removed. #141940
• The cluster setting changefeed.new_pubsub_sink_enabled/changefeed.new_pubsub_sink.enabled is no longer supported. The new Google Cloud Pub/Sub sink has been enabled by default since v23.2, and the first version Pub/Sub sink has been removed. #141948
• DROP INDEX can now only be run when sql_safe_updates is set to false. #139456

Command-line changes

• Improved the performance of the debug zip query that collects transaction_contention_events data, reducing the chances of memory budget exceeded or query execution canceled due to statement timeout errors. #139735
• Removed the deprecated --storage-engine parameter from the CLI. #139744

DB Console changes

• The /_admin/v1/settings API (and therefore cluster settings console page) now returns cluster settings using the same redaction logic as querying SHOW CLUSTER SETTINGS and crdb_internal.cluster_settings. This means that only settings flagged as "sensitive" will be redacted, all other settings will be visible. The same authorization is required for this endpoint, meaning the user must be an admin, have MODIFYCLUSTERSETTINGS, or VIEWCLUSTERSETTINGS roles to use this API. The exception is that if the user has VIEWACTIVITY or VIEWACTIVITYREDACTED, they will see console-only settings. #138688
• The Overload dashboard in the DB Console now shows only the v2 replication admission control metrics, where previously it displayed both v1 and v2 metrics. Additionally, the aggregate size of queued replication entries is now shown. #139066
• Jobs can now choose to emit messages that are shown on the Jobs Details page in v25.1 and later. #139246
• An event is posted when a store is getting close to full capacity. #139199
• Percentile latencies are no longer available for SQL Activity. The implementation of these percentiles was error-prone and difficult to understand because it was computed differently from the other SQL statistics collected. Customers interested in viewing percentile latencies per statement fingerprint are encouraged to use the experimental per-fingerprint histograms that can be enabled with the sql.stats.detailed_latency_metrics.enabled cluster setting. This will enable externalized histogram metrics via the Prometheus scrape endpoint. #139500
• Surfaced commit latency on the Transactions pages #139946
• Removed the Paused Follower graph from the Replication dashboard in the DB Console as followers are no longer paused by default from v25.1. #141427
• DB console's index.html page now includes a Content-Security-Policy (CSP) header to help prevent malicious XSS attacks. #142282

Bug fixes

• Previously, storage parameters with the same key would lead to ambiguity. This has now been fixed and an error surfaced if duplicate storage parameters are specified. #139172
• Fixed a bug where the error batch timestamp T must be after replica GC threshold could occur during a schema change backfill operation, causing the schema change job to retry infinitely. Now, this error is treated as permanent, and will cause the job to enter the failed state. #139203
• Previously, whenever CockroachDB collected a statement bundle when plan-gist-based matching was used, the plan.txt file would be incomplete. This bug is now fixed—it had been present since the introduction of the plan-gist-based matching feature in v23.1, but was partially addressed in the v24.2 release. #127604
• Previously, EXPLAIN ANALYZE of mutation statements would always get actual row count: 1 execution statistic for the corresponding mutation node in the plan, regardless of how many rows were actually modified. The bug has been present since before v22.2 and is now fixed. #139278
• Fixed a bug where sometimes activating diagnostics for SQL activity appeared unresponsive, with no state or status update upon activating. Now, the status should always reflect that diagnostics are active or that a statement bundle is downloadable. #139342
• The to_regclass, to_regtype, to_regrole, and related functions now return NULL for any numerical input argument. #139777
• Fixed a rare bug in which a query might fail with the error could not find computed column expression for column in table while dropping a virtual computed column from the table. This bug was introduced in v23.2.4. #139388
• The optimizer could produce incorrect query plans for queries using trigram similarity filters (e.g., col % 'val') when pg_trgm.similarity_threshold was set to 0. This bug was introduced in v22.2.0 and is now fixed. Note that this issue does not affect v24.2.0 and later releases when the optimizer_use_trigram_similarity_optimization session variable (introduced in v24.2.0) is set to its default value true, as it would skip this behavior. #139265
• Fixed a bug that could cause SHOW TABLES and other introspection operations to encounter a batch timestamp must be after replica GC threshold error. #139532
• Fixed a bug that existed only in pre-release versions of v25.1. The bug could cause creation of a PL/pgSQL routine with a common table expression (CTE) to fail with an error like the following: unexpected root expression: with. #140083
• Configuring replication controls on a partition name of an index that is not unique across all indexes will correctly impact only that partition. #140167
• The Data distribution page in Advanced Debug will no longer crash if there are NULL values for raw_sql_config in crdb_internal.zones. #140066
• Fixed a bug where dropping a table with a trigger using the legacy schema changer could leave an orphaned reference in the descriptor. This occurred when two tables were dependent on each other via a trigger, and the table containing the trigger was dropped. #140995
• Addressed a bug that could cause concurrent DML operations to prevent primary key changes from succeeding. #141189
• Fixed a bug that prevented transaction retry errors encountered during implicit transactions from being automatically retried internally if the autocommit_before_ddl session variable was enabled and the statement was a schema change. #141369
• A step in the v25.1 upgrade finalization process that required backfilling jobs now uses locks to ensure it makes progress even when there is contention on the jobs table, which will prevent the possibility of becoming stuck under heavy load. #141420
• Fixed a bug that could prevent SHOW CREATE TABLE from working if a database was offline (e.g., due to a RESTORE on that database). #141195
• Fixed a bug that prevented starting multi-table logical data replication (LDR) streams on tables that used user-defined types. #141634
• Fixed a bug that could cause nil pointer dereference errors when executing statements with UDFs. The error could also occur when executing statements with some built-in functions, like obj_description. #141596
• Fixed a bug where a node that was drained as part of decommissioning may have interrupted SQL connections that were still active during drain (and for which drain would have been expected to wait). #141411
• Fixed a bug where the fraction completed and internal checkpoints during an index backfill operation would stop getting written if any of the periodic fraction/checkpoint write operations failed. Additional logging was added so that progress is logged in addition to being written to the job record. This bug affected schema change operations, such as creating an index or adding a non-nullable column to a table. #141714
• Fixed a bug that could cause gateway nodes to panic when performing an UPSERT on a table with a BOOL primary key column and a partial index with the primary key column as the predicate expression. #141728
• Fixed a bug where CockroachDB could incorrectly evaluate casts to some OID types (like REGCLASS) in some cases. The bug has been present since at least v22.1. #141946
• Transactions that enter the aborted state now release locks they are holding immediately, provided there is no SAVEPOINT active in the transaction. #140160
• Fixed a bug when running with autocommit_before_ddl that could cause a runtime error when binding a previously prepared DDL statement. #142034
• Fixed a bug where orphaned leases were not properly cleaned up. #141429
• Previously, the CREATE LOGICALLY REPLICATED syntax would always create the destination side table with the source side name, instead of the user-provided name. This change ensures the user-provided name is used. #142235
• Fixed a bug that would prevent CREATE TRIGGER and DROP TRIGGER statements from working if the autocommit_before_ddl setting was enabled, and if the statement was either sent as a prepared statement or as part of a batch of multiple statements. #142202
• Fixed a bug that could cause the upgrade to v25.1 to crash if a job was missing from the virtual table, for example, if a malformed job had no payload information. #142284
• The TTL deletion job now includes a retry mechanism that progressively reduces the batch size when encountering contention. This improves the chances of successful deletion without requiring manual adjustments to TTL job settings. #141953
• Fixed an issue where removed nodes could leave persistent entries in crdb_internal.gossip_alerts. #142385
• Invalid default expressions could cause backfilling schema changes to retry forever. #142490
• Fast failback could succeed even if the destination cluster's protected timestamp had been removed, causing the reverse stream to enter a crashing loop. This fix ensures the failback command fast fails. #142231
• Fixed an issue where dropping a database with triggers could fail due to an undropped back reference to a trigger function. #142670
• Fixed a bug where replication controls on indexes and partitions would not get properly updated during an index backfill (in the declarative schema changer) to its new ID; effectively discarding the replication controls set on it before the backfill. #141800
• Addressed a bug where CREATE SEQUENCE could succeed under with a DROP SCHEMA or DROP DATABASE in progress. #142696
• Fixed a bug in client certificate expiration metrics. #142682
• Physical cluster replication (PCR) reader catalogs could have orphan rows in system.namespace after an object is renamed. #142829
• Fixed a bug where during validation of a table-level zone configuration, inherited values were incorrectly populated from the default range instead of from the parent database. #142760
• Fixed a bug that would send a replica outside of a tenant known region, when SURVIVE REGION FAILURE was set and exactly 3 regions were configured. #142838

Performance improvements

• Improved directory traversal performance by switching from filepath.Walk to filepath.WalkDir. #139108
• Removed a potential storage read from the Raft commit pipeline. This reduces the worst-case KV write latency. #139609
• The optimizer_check_input_min_row_count session setting now defaults to 1, resulting in better query plans for foreign key and uniqueness checks. #140735
• This change restores the changefeed checkpoint immediately to the change frontier. This potentially reduces duplicate messages in the event that the frontier writes a checkpoint before it receives updates and covers the previous checkpoint from the aggregators, overwriting the checkpoint with less information. #139969

Build changes

• Upgraded to Go v1.23.6. #140626
• Enabled the use of profile-guided optimization in the cockroach binary. #142697
• Upgraded to Go v1.23.7. #142698

Was this helpful?