What's New in v25.1

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

Source tag

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

Backward-incompatible changes

• The old BACKUP TO, RESTORE FROM <collectionURI>, and SHOW BACKUP IN <collectionURI> syntaxes are now fully deprecated and no longer usable. #133610

Security updates

• Added support for partial roles from LDAP synced group to be mapped to CockroachDB roles and ensure appropriate erroring for undesired behavior. #135552

General changes

• To improve the granularity of changefeed pipeline metrics, the changefeed metrics changefeed.admit_latency and changefeed.commit_latency now have histogram buckets from 5ms to 60m (previously 500ms to 5m). The following changefeed metrics now have histogram buckets from 5ms to 10m (previously 500ms to 5m):
  • changefeed.parallel_io_queue_nanos
  • changefeed.parallel_io_result_queue_nanos
  • changefeed.sink_batch_hist_nanos
  • changefeed.flush_hist_nanos
  • changefeed.kafka_throttling_hist_nanos #136265
• Added support for multiple seed brokers in the new Kafka sink. #136632
• Added the new metric distsender.rangefeed.catchup_ranges_waiting_client_side that counts how many rangefeeds are waiting on the client-side limiter to start performing catchup scans. #136741
• Added system.users to the list of system tables that changefeeds protect with protected timestamps. This table is required for change data capture queries. #133568
• Added the AWS_USE_PATH_STYLE parameter to S3 URI parsing. #136715

SQL language changes

• Two new builtin functions, crdb_internal.{lease_holder, range_stats}_with_errors, include errors encountered while fetching leaseholder and range stats. These new builtins are used by the crdb_internal.ranges table, which includes a new column, errors, that combines the errors from the builtins. #131232
• The cluster setting sql.stats.automatic_partial_collection.enabled is now enabled by default, which enables automatic collection of partial table stats. Partial table stats (i.e., those created with CREATE STATISTICS ... USING EXTREMES) scan the lower and upper ends of indexes to collect statistics outside the range covered by the previous full statistics collection. #133988
• When triggers fire one another cyclically, the new recursion_depth_limit session variable now limits the depth of the recursion. By default, the limit is 1000 nested trigger executions. #134498
• The names of BEFORE triggers fired by a mutation now show up in the EXPLAIN output. The trigger-function invocations are visible in the output of verbose EXPLAIN. #135556
• AFTER triggers will now show up in the output of EXPLAIN, as well as EXPLAIN ANALYZE. #135556
• Added support for SHOW TRIGGERS, which displays the names of all triggers on a table, as well as whether each trigger is enabled. The user must have any privilege on the table, or be its owner. #135778
• Added support for SHOW CREATE TRIGGER, which displays the CREATE statement for a trigger. The user must have any privilege on the table, or be its owner. #135778
• Added an informational notice to the result of CREATE TABLE ... AS statements that describes that indexes and constraints are not copied to the new table. #135845
• Altering a column’s type no longer requires enabling the enable_experimental_alter_column_type_general session variable. This change makes the feature generally available. #135936
• Added support for COLLATE expressions on arrays of strings to match PostgreSQL more closely. #133751
• Added the column readable_high_water_timestamp to the output of SHOW CHANGEFEED JOBS. This human-readable form will be easier to consume. high_water_timestamp still exists and is in epoch nanoseconds. #135623
• The sql_safe_updates session variable must be disabled to perform ALTER COLUMN TYPE operations that require a column rewrite. #136110
• Added the CREATE LOGICALLY REPLICATED syntax that will direct logical data replication jobs to create the destination table(s) using a copy of the source table(s). #136841
• It is now possible to execute queries with correlated joins with sub-queries or common table expressions in both the INNER and OUTER context. Errors with the following message: unimplemented: apply joins with subqueries in the "inner" and "outer" contexts are not supported will no longer occur. #136506
• It is now possible to include a common table expression within the body of a user-defined function or stored procedure. #136506
• Updated the column name targets to tables in the SHOW LOGICAL REPLICATION JOBS responses. #134339

Operational changes

• Retired the cluster setting kv.rangefeed.scheduler.enabled. The rangefeed scheduler is now unconditionally enabled. #132825
• Added the cluster setting ui.database_locality_metadata.enabled that allows operators to disable loading extended database and table region information in the DB Console Database and Table pages. This information can cause significant CPU load on large clusters with many ranges. Versions of this page from v24.3 and later do not have this problem. If customers require this data, they can use the SHOW RANGES FROM {DATABASE| TABLE} query via SQL to compute on-demand. #133075
• The metrics scrape HTTP endpoint at / _status/vars will now truncate HELP text at the first sentence, reducing the metadata for metrics with large descriptions. Descriptions are still accessible in the documentation. #134724
• The row-level TTL job will now periodically update the progress meter in the jobs introspection interfaces, including SHOW JOBS and the Jobs page in the DB console. #135142
• The kv.bulk_io_write.min_capacity_remaining_fraction cluster setting can be be set between 0.04 and 0.3. #135779
• Added two new metrics, sql.distsql.select.distributed_exec.count and sql.distsql.select.distributed_exec.count.internal. These metrics count the number of SELECT statements that actually execute with full or partial distribution. These metrics differ from sql.distsql.select.count and sql.distsql.select.count.internal in that the latter count the number of SELECT statements that are planned with full or partial distribution, but might not necessarily execute with full or partial distribution, depending on the location of data. #135236
• Added the new metric sql.distsql.distributed_exec.count that counts the number of invocations of the execution engine with full or partial distribution. (This is in contrast to sql.distsql.queries.total, which counts the total number of invocations of the execution engine.) #135236
• Added some clarification that the following metrics count invocations of the execution engine and not SQL queries (which could each result in multiple invocations of the execution engine):
  
  • sql.distsql.queries.active
  • sql.distsql.queries.total
  • sql.distsql.distributed_exec.count #135236
• The default value for the cluster setting trace.span_registry.enabled has been changed from true to false. #135682
• Removed the sql.auth.resolve_membership_single_scan.enabled cluster setting. This was added in case it was necessary to revert back to the previous behavior for looking up role memberships, but this cluster setting has not been needed in practice since this was added in v23.1. #135852
• Telemetry delivery is now considered successful even in cases where CockroachDB experiences a network timeout. This will prevent throttling in cases outside an operator's control. #136219
• When a schema change job is completed, rolls back, or encounters a failure, the time taken since the job began is now logged in a structured log in the SQL_SCHEMA log channel. #136899

DB Console changes

• As of v25.1 the legacy Database page, which was previously available through the Advanced Debug page, is no longer available. #134005
• When activating statement diagnostics in the DB Console, users now have the option to produce a redacted bundle as output. This bundle will omit sensitive data. #134723
• Fixed a list of UI bugs on the DB Console Overview and Node Overview pages. #135293
• Removed the link for the legacy table page on the Plan Details page. #136311
• Changed the table and index contents of the Hot Ranges page in DB console. #134106

Bug fixes

• Fixed a bug that prevented the CREATE statement for a routine from being shown in a statement bundle. This happened when the routine was created on a schema other than public. The bug has existed since v23.1. #132147
• Reduced the duration of partitions in the gossip network when a node crashes in order to eliminate false positives in the ranges.unavailable metric. #133300
• Fixed a bug that caused incorrect evaluation of some binary expressions involving CHAR(N) values and untyped string literals with trailing whitespace characters. For example, the expression 'f'::CHAR = 'f ' now correctly evaluates to true. #133037
• Fixed a race condition in Sarama when Kafka throttling is enabled. #133563
• Fixed a metrics bug in rangefeed restarts introduced in v23.2. #133947
• Fixed a bug that could result in incorrect metrics related to retryable rangefeed errors. #133991
• Fixed a bug that could cause DELETE triggers not to fire on cascading DELETE, and which could cause INSERT triggers to match incorrectly in the same scenario. #134759
• Non-admin users that run DROP ROLE IF EXISTS on a user that does not exist will no longer receive an error message. #134850
• Fixed a bug where CockroachDB would encounter an internal error when evaluating FETCH ABSOLUTE 0 statements. The bug had been present since v22.1. #134919
• Fixed a bug that could cause incorrect query results when the optimizer planned a lookup join on an index containing a column of type CHAR(N), VARCHAR(N), BIT(N), VARBIT(N), or DECIMAL(M, N), and the query held that column constant to a single value (e.g., with an equality filter). #134891
• Fixed a bug that prevented restoring cluster backups taken in a multi-region cluster that had configured the system database with a region configuration into a non-multi-region cluster. #134604
• Fixed an unhandled error that would occur if DROP SCHEMA was executed on the public schema of the system database, or on an internal schema like pg_catalog or information_schema. #135149
• ALTER DATABASE operations no longer hang when the operation modifies the zone config if an invalid zone config already exists. #135168
• CockroachDB now correctly evaluates percentile_cont and percentile_disc aggregates over FLOAT4 values. #135130
• The schema changer's backfill process now includes a retry mechanism that reduces the batch size when memory issues occur. This improves the likelihood of operation success without requiring manual adjustment of the bulko.index_backfill.batch_size cluster setting. #135563
• CREATE SCHEMA now returns the correct error if a the schema name is missing. #135910
• Fixed an issue where corrupted table statistics could cause the cockroach process to crash. #135944
• Table statistics collection in CockroachDB could previously run into no bytes in account to release errors in some edge cases (when the SQL memory budget, configured via --max-sql-memory flag, was close to being exhausted). The bug has been present since v21.2 and is now fixed. #135970
• security.certificate.* metrics will now be updated if a node loads new certificates while running. #135596
• A table that is participating in logical data replication can no longer be dropped. Previously, this was allowed, which would cause all the replicated rows to end up in the dead-letter queue. #136172
• ALTER COLUMN SET NOT NULL was not enforced consistently when the table was created in the same transaction. #136298
• CREATE relation / type could leave dangling namespace entries if the schema was concurrently being dropped. #136325
• The idle_in_session_timeout session variable now excludes the time spent waiting for schema changer jobs to complete, preventing unintended session termination during schema change operations. #136463
• Fixed a bug that causes the optimizer to use stale table statistics after altering an ENUM type used in the table. #136538
• CockroachDB now better respects the statement_timeout limit on queries involving the top K sort and merge join operations. #136631
• Fixed a bug that would cause the make_timestamp and make_timestamptz builtin functions to incorrectly extract the seconds argument if the value was less than 1. #136804
• Fixed possible index corruption caused by triggers that could occur when the following conditions were satisfied:
  1. A query calls a user-defined function or stored procedure, and also performs a mutation on a table.
  2. The user-defined function or storage procedure contains a statement that either fires an AFTER trigger, or fires a CASCADE that itself fires a trigger.
  3. The trigger modifies the same row as the outer statement.
  4. Either the outer or inner mutation is something other than an INSERT without an ON CONFLICT clause. #136076
• Fixed an issue where license enforcement was not consistently disabled for single-node clusters started with cockroach start-single-node, ensuring proper behavior on cluster restarts. #136926
• Fixed a bug that caused an incorrect filesystem to be logged as part of the store information. #137024

Performance improvements

• The /_status/nodes_ui API no longer returns unnecessary metrics in its response. This decreases the payload size of the API and improves the load time of various DB Console pages and components. #135186
• Performance for some PL/pgSQL loops is now significantly improved, by as much as 3–4 times. This is due to applying tail-call optimization in more cases to the recursive sub-routines that implement loops. #135145
• Improved the internal caching logic for role membership information. This reduces the latency impact of commands such as DROP ROLE, CREATE ROLE, and GRANT role TO user, which cause the role membership cache to be invalidated. #135852
• The session variable plan_cache_mode now defaults to auto, enabling generic query plans for some queries. #135668
  • This change is reverted in v25.1.0-rc.1, so this note can be disregarded when running the latest testing release and v25.1 production releases, unless otherwise noted.
• GRPC streams are now pooled across unary intra-cluster RPCs, allowing for reuse of gRPC resources to reduce the cost of remote key-value layer access. This pooling can be disabled using the rpc.batch_stream_pool.enabled cluster setting. #136648
  • This information was updated in the v25.1.0-beta.2 release notes.

Multi-tenancy

• The nodes endpoint should work for shared secondary tenants. Since nodes are common to all the tenants, this API endpoint behaves similarly to the system tenant's endpoint. #131644