What's New in v26.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:v26.1.0-alpha.1

Source tag

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

General changes

• Docker images now use UBI 10 as the base image. #153990
• The changefeed bulk delivery setting was made optional. #154870

SQL language changes

• Index acceleration is now supported for a subset of jsonb_path_exists filters used in the WHERE clause.

  Given jsonb_path_exists(json_obj, json_path_expression), inverted indexes are supported only when the json_path_expression matches one of the following patterns:

• The json_path_expression must not be in STRICT mode.

• Keychain mode: $. [key|wildcard].[key|wildcard].... In this mode, a prefix span is generated for the inverted expression.

• Filter with end value mode, using an equality check: $. [key|wildcard]? (@.[key|wildcard].[key|wildcard]... == [string|number|null|boolean]). In this mode, since the end value is fixed, a single-value span is generated.

  The following cases are not supported:

  • $
  • $[*]
  • $.a.b.c == 12, $.a.b.c > 12, or $.a.b.c < 12 (operation expressions)
  • $.a.b ? (@.a > 10) (filter with an inequality check)

  #150793

• SHOW CHANGEFEED JOBS now includes a database_name field that displays the database name for database-level changefeeds. For table-level changefeeds, this field is null. For database-level changefeeds, the full_table_names field now returns an empty list by default and displays only the total count of watched tables.

  To view the full list of watched tables (as in previous versions), use the new WITH WATCHED_TABLES option:

  SHOW CHANGEFEED JOBS WITH WATCHED_TABLES;
  

  This change improves performance when displaying database-level changefeeds that may track many tables.

  #151131

• Added a clamp for the estimated selectivity of inequality predicates that are unbounded on one or both sides (e.g., x > 5). This reduces the risk of a catastrophic underestimate that causes the optimizer to choose a poorly-constrained scan. The feature is disabled by default and can be enabled with the session setting optimizer_clamp_inequality_selectivity. #153067

• Added a clamp on row-count estimates for very large tables to ensure the optimizer assumes at least one distinct value will be scanned. This reduces the risk of a catastrophic underestimate. The feature is off by default and controlled by the optimizer_clamp_low_histogram_selectivity session setting. #153067

• The optimizer can now use table statistics that merge the latest full statistic with all newer partial statistics, including those over arbitrary constraints over a single span. #153419

• Added the sql.catalog.allow_leased_descriptors.enabled cluster setting, which is false by default. When set to true, queries that access the pg_catalog or information_schema can use cached leased descriptors to populate the data in those tables, with the tradeoff that some of the data could be stale. #154051

• Added a default-off cluster setting (sql.log.scan_row_count_misestimate.enabled) that enables logging a warning on the gateway node when optimizer estimates for scans are inaccurate. The log message includes the table and index being scanned, the estimated and actual row counts, the time since the last table stats collection, and the table's estimated staleness. #154370

• Fixed a bug where the results of ALTER SEQUENCE's increment and SELECT nextval() operations were not as expected. The value of a sequence after an ALTER SEQUENCE statement has executed on it is now consistent with a sequence created with those values. #154489

• Added changefeed setting range_distribution_strategy with values 'default' or 'balanced_simple'. This new per-changefeed setting overrides the cluster setting changefeed.default_range_distribution_strategy where both exist.

  Example:

  CREATE CHANGEFEED FOR x into 'null://' WITH
  range_distribution_strategy='balanced_simple';
  

  #154744

• Added the INSPECT command, which runs consistency validation check jobs against tables or databases and specified indexes. #154873

• Added support for collecting partial statistics when the given WHERE clause implies the predicate of a partial index with the requested column as the first key column. For example:

  CREATE TABLE t (a INT, INDEX idx_partial (a) WHERE a > 5);
  CREATE STATISTICS pstat ON a FROM t WHERE a > 7;
  

  #154892

• The row_security session variable now behaves as it does in PostgreSQL, allowing users to detect when RLS is applied. #155110

• Added the bulkio.index_backfill.vector_merge_batch_size cluster setting to control how many vectors to merge into a vector index per transaction during create operations. The setting defaults to 3. #155284

• Updated the scan misestimate logging, which is controlled by the sql.log.scan_row_count_misestimate.enabled cluster setting, to use structured logging. The logs now include the scanned table and index, the estimated and actual row counts, the time since the last table statistics collection, and the table's estimated staleness. #155454

• The EXPERIMENTAL SCRUB command is deprecated. Use the INSPECT command for data consistency validation. #155485

• INSPECT supports a DETACHED option to run the operation without waiting for it. #155774

• ALTER TABLE ... DROP STORED statements are now executed internally by the declarative schema changer. #155778

• Added a sql.statements.rows_read.count metric that counts the number of index rows read by SQL statements. #155820

• Added the EXPLAIN (FINGERPRINT) statement, which returns normalized statement fingerprints with constants replaced by underscores. For example, EXPLAIN (FINGERPRINT) SELECT * FROM t WHERE a = 123 returns SELECT * FROM t WHERE a = _. #156152

• Introduced two new settings to control the use of canary statistics in query planning:

  • Cluster setting sql.stats.canary_fraction (float, range [0, 1], default: 0): Controls what fraction of queries use "canary statistics" (newly collected stats within their canary window) versus "stable statistics" (previously proven stats). For example, a value of 0.2 means 20% of queries will use canary stats while 80% use stable stats. The selection is atomic per query: if a query is chosen for canary evaluation, it uses canary statistics for all tables it references (where available). A query never uses a mix of canary and stable statistics.
  • Session variable canary_stats_mode (enum: {auto, off, on}, default: auto):
    • on: All queries in the session use canary stats for planning.
    • off: All queries in the session use stable stats for planning.
    • auto: The system decides based on sql.stats.canary_fraction for each query execution. #156307

• Introduced a new table storage parameter, sql_stats_canary_window, to enable gradual rollout of newly collected table statistics. It takes a duration string as the value. When set with a positive duration, the new statistics remain in a "canary" state for the specified duration before being promoted to stable. This allows for controlled exposure and intervention opportunities before statistics are fully deployed across all queries. #156307

• Introduced SHOW FINGERPRINTS FOR TABLE, which produces an FNV hash for each index in a table. FNV is used for performance reasons and is sensitive to changes in the underlying data, including NULLs. #156600

• The optimizer_clamp_low_histogram_selectivity and optimizer_clamp_inequality_selectivity settings are now on by default. This causes the optimizer to assume that at least one distinct value "passes" each filter in a query, and that open-ended inequality filters select at least 1/10000 rows from the table. This reduces the chances of a catastrophic row count underestimate when stats are inaccurate. #156610

• The ALTER TABLE ... SET/ADD GENERATED AS IDENTITY statement is supported by the declarative schema changer in v26.1 and later. #157144

• EXPLAIN and EXPLAIN ANALYZE will now display the number of hints from system.statement_hints applied to the executed statement. #157160

• The Plan Details in the Statement Activity page of the DB Console now show whether any hints from system.statement_hints were applied to the statement execution. #157160

Operational changes

• The metrics sql.select.started.count, sql.insert.started.count, sql.update.started.count, and sql.delete.started.count are now emitted with labels under the common metric name sql.started.count, using a query_type label to distinguish each operation. #151946
• Added the cluster setting storage.unhealthy_write_duration (defaults to 20s), which is used to indicate to the allocator that a store's disk is unhealthy. The cluster setting kv.allocator.disk_unhealthy_io_overload_score controls the overload score assigned to a store with an unhealthy disk, where a higher score results in preventing lease or replica transfers to the store, or shedding of leases by the store. The default value of that setting is 0, so the allocator behavior is unaffected. #153364
• Added two new changefeed metrics for tracking the max skew between a changefeed's slowest and fastest span/table. The metrics are gauge metrics with the names changefeed.progress_skew.{span} and changefeed.progress_skew.{table}. #153975
• Added the cluster setting storage.snapshot.recreate_iter_duration (default 20s), which controls how frequently a long-lived storage engine iterator, backed by an engine snapshot, will be closed and recreated. Currently, it is only used for iterators used in rangefeed catchup scans. #154412
• Added cluster setting sql.schema.approx_max_object_count (default: 20,000) to prevent creation of new schema objects when the limit is exceeded. The check uses cached table statistics for performance and is approximate - it may not be immediately accurate until table statistics are updated by the background statistics refreshing job. Clusters that have been running stably with a larger object count should raise the limit or disable the limit by setting the value to 0. In future releases, the default value for this setting will be raised as more CockroachDB features support larger object counts. #154495
• Cleaned up redundant and misleading metrics. #154545
• Fixed the changefeed.parallel_io_pending_rows metric's y-axis label to match the metric's definition. #154552
• Added a metric called changefeed.parallel_io_workers to track the number of workers in ParallelIO. #154552
• Events related to changefeed operations are now routed to the CHANGEFEED channel, while sampled queries and transactions, along with certain SQL performance events, are logged to SQL_EXEC. To continue using the previous logging channels, set log.channel_compatibility_mode.enabled to true. #154670
• Successfully completed automatic SQL stats collecton jobs are now automatically purged rather than being retained for the full default job retention period. #155848
• The cluster setting storage.snapshot.recreate_iter_duration (default 20s) controls how frequently a long-lived engine iterator, backed by an engine snapshot, will be closed and recreated. Currently, it is only used for iterators used in rangefeed catchup scans. #156303
• Add support for CREATE LOGICAL REPLICATION STREAM in situations where the source table has a column with a sequence expression. #156975

Command-line changes

• cockroach workload <name> run commands now offer a --with-changefeed flag to additionally run a changefeed that watches for writes to the workload's tables. #155516

DB Console changes

• The SQL dashboard has been enhanced with additional insights.
  • The Transaction Restarts dashboard now displays txn.restarts.txnpush and txn.restarts.unknown metrics. - A new Failed SQL Connections graph shows failed SQL connection attempts. A new SQL Queries Within Routines Per Second dashboard reports on SELECT, UPDATE, INSERT, and DELETE operations executed within routines.
  • A new Table Statistics Collections dashboard provides information on auto, auto partial, and manual statistics collections.

#155203

• The background (elastic) store graphs for exhausted duration, and the wait duration histogram, have been separated from the foreground (regular) graphs. #156801

Bug fixes

• Previously, CockroachDB would omit execution statistics in EXPLAIN ANALYZE output for mutation nodes when a RETURNING clause was used. The bug was present since before v21.1 and is now fixed. #145934
• Fixed a bug where CockroachDB could encounter a vector encoder doesn't support ForcePut yet error when executing COPY commands concurrently with certain schema changes. The bug had existed since before v23.2. #148549
• Fixed a bug causing a READ COMMITTED or SNAPSHOT isolation transaction to be committed despite returning a non-ambiguous error. #152010
• Fixed a bug in type-checking placeholders with UNKNOWN types. It could cause incorrect results in some cases. #152882
• Fixed a bug where EXPORT CSV and EXPORT PARQUET could cause a node crash when their result rows were used as input to a mutation, such as an INSERT, within the same SQL statement. This bug had been present since before v22.1. #153951
• Idle latency on the Transaction Details page in the DB Console is now reported more accurately. Previously, transactions that used prepared statements (e.g., with placeholders) overcounted idle time, while those that included observer statements (common in the SQL CLI) undercounted it. #154028
• Fixed a bug that caused panics when executing COPY into a table with hidden columns and expression indexes. The panic only occurred when the session setting expect_and_ignore_not_visible_columns_in_copy was enabled. This bug was introduced with expect_and_ignore_not_visible_columns_in_copy in v22.1.0. #154162
• Vector index backfill jobs now correctly report progress in the SHOW JOBS output. #154209
• Fixed a bug where RESTORE of a database with a SECONDARY REGION did not apply the lease preferences for that region. #154522
• Fixed a bug where a changefeed could perform many unnecessary job progress saves during an initial scan. #154598
• Fixed a bug where CockroachDB would not log events for TxnRowsRead and TxnRowsWritten guardrails for internal queries into the SQL_INTERNAL_PERF logging channel. The bug was present since v21.2. #154670
• Fixed a bug that caused internal errors for INSERT .. ON CONFLICT .. DO UPDATE statements when the target table had both a computed column and a BEFORE trigger. This bug was present since triggers were introduced in v24.3.0. #154789
• Fixed a bug where a changefeed targeting only a subset of a table's column families could become stuck. #154802
• Fixed a bug where CockroachDB would hit an internal error when performing an inverted join using an inverted index in which the first prefix column had DESC direction. The bug was present since v21.1. #154914
• Fixed a bug where the kvflowcontrol.send_queue.scheduled.force_flush metric was missing a decrement, resulting in a value of greater than 0 even when there was no ongoing force flush. #154960
• Fixed a bug that would cause WITH READ VIRTUAL CLUSTER to be ignored if any other options were passed when running CREATE VIRTUAL CLUSTER FROM REPLICATION. #154963
• Internal assertions that verify NumRange = 0 in the first histogram bucket, used to catch malformed statistics, now run only in test builds to avoid crashing production queries. #155035
• Fixed a bug in which range counts in table statistics histograms were not handled correctly after a user-defined ENUM type was modified. #155035
• Fixed a bug in the cockroach node drain command where draining a node using virtual clusters (such as clusters running Physical Cluster Replication (PCR)) could return before the drain was complete, possibly resulting in shutting down the node while it still had active SQL clients and range leases. #155063
• Fixed a bug where a race condition in range splits could result in a regressed Raft state on a post-split range. This condition was extremely rare, and only observed during internal testing. #155143
• Corrected a potential deadlock during vector index creation. #155192
• Fixed a bug that would result in a node crash if a PCR or LDR URI used sslinline=true with sslmode=disable. #155232
• Fixed a bug where CockroachDB could corrupt the first bucket of table statistic histograms in certain cases, causing underestimates for range counts near the lower end of the domain. #155242
• Added proper dependency handling when adding a constraint with NOT VALID that references a user-defined function (UDF). #155404
• Fixed a bug that prevented the optimizer from recognizing correlated filters when one of the filtered columns had a single distinct value across all rows. This could lead to suboptimal query plans in some cases. #155407
• The username remapping functionality specified by the server.identity_map.configuration cluster setting now matches identities and usernames with a case-insensitive comparison. #155531
• Previously, the forecasted statistics shown in SHOW STATISTICS ... WITH FORECAST could be inconsistent with those in the stats cache, depending on whether WITH MERGE was specified. Forecasted statistics are now displayed consistently, regardless of the WITH MERGE clause. #155615
• Fixed a bug where CockroachDB could crash when executing EXPLAIN ANALYZE statements using the pausable portal model. This would occur when the query was executed via the extended PGWire protocol (Parse, Bind, Execute) with the multiple_active_portals_enabled session variable set. The bug was present since v23.2. #155655
• INSPECT can now be run on tables with indexes that store REFCURSOR-typed columns. #155772
• Fixes a bug where DROP SCHEMA CASCADE could run into an error with complex references from triggers. #155777
• Fixed a bug where the job responsible for compacting stats for the SQL activity state could enter an unschedulable state. Fixes: #155165 #155809
• Fixed a bug where reads and writes performed by routines (user-defined functions and stored procedures) and apply joins were not included in bytes read, rows read, and rows written statement execution statistics. This bug had been present since before v23.2. #155824
• INSPECT now correctly checks index consistency at the historical timestamp when using AS OF SYSTEM TIME, even for spans with no current data. #155837
• The INSPECT statement now detects dangling secondary index entries even when the primary index spans contain no data. #155844
• Fixed an internal error that could occur when replacing a user-defined function or stored procedure using CREATE OR REPLACE, if the existing signature included multiple DEFAULT expressions. This bug was introduced in v24.2, when support for DEFAULT expressions was added. #155867
• INSPECT no longer fails when checking index consistency on indexes with virtual key columns. Such indexes will now be skipped. #155956
• Fixed a bug where DML statements on regional by row tables with unique indexes that do not reference the region could sometimes fail under READ COMMITTED isolation. #156105
• Fixed a bug where Zone Config Extensions incorrectly prevented users from removing non-voting read replicas from multi-region databases. Users can now set num_replicas equal to num_voters to remove read replicas while maintaining the required number of voting replicas for their database's survival goal. This allows reducing storage costs without compromising availability guarantees. #156228
• Fixed a bug in the ltree2text built-in function where the returned TEXT value was incorrectly wrapped in single quotes. This bug had been present since the ltree2text function was introduced in v25.4.0. #156485
• Fixed a bug that caused incorrect results for queries that filter indexed LTREE columns with the <@ (contained-by) operator. This bug was present since v25.4.0. #156573
• Fixed a bug where the "atomic" COPY command (controlled via the copy_from_atomic_enabled session setting, true by default) could encounter RETRY_COMMIT_DEADLINE_EXCEEDED transaction errors if the whole command took 1 minute or more. This bug occurred only when the vectorized engine was used for COPY. #156584
• Fixed a bug that caused transactions to fail with the error message: failed indeterminate commit recovery: programming error: timestamp change by implicitly committed transaction. #156722
• Fixed a bug in JSONPath index acceleration where queries using jsonb_path_exists with a root key (e.g., $.b) incorrectly returned no results when the queried JSON was an array. This fix enables unwrapping a single array layer at the root, allowing the path to be evaluated against each element. Only v25.4 releases were affected. #156828
• Fixed a bug that prevents large TRUNCATE operations from completing due to command is too large errors. #156867
• Fixed a bug that caused incorrect gossip.callbacks.pending_duration metric values to be recorded. #156939
• Fixed a bug where transactions running concurrently with a GRANT or REVOKE on virtual tables or via external connections could observe modifications incorrectly. #156949
• Fixed a bug where CockroachDB could encounter an internal error when evaluating a COPY FROM command in a transaction after it was rolled back to a savepoint. The bug was present since before v23.2. #156959
• Fixed a bug that could cause internal errors for queries using generic query plans with NULL placeholder values. #156962
• Fixed a bug that could cause a schema change to be stuck in the reverting state if the infer_rbr_region_col_using_constraint storage parameter was being set at the same time as adding a constraint that had a foreign key violation. #157834

Performance improvements

• The cost of generic query plans is now calculated based on worst-case selectivities for placeholder equalities (e.g., x = $1). This reduces the chance of suboptimal generic query plans being chosen when plan_cache_mode=auto. #151409
• TTL jobs now checkpoint their progress, allowing them to resume without reprocessing already completed spans after a restart. #152618
• Queries with filters in the form a LIKE b ESCAPE '\' are now index-accelerated in certain cases where they were not before. #155064
• The optimizer will no longer choose a generic query plan with unbounded cardinality over a custom query plan with bounded cardinality, regardless of optimizer_prefer_bounded_cardinality, better optimizing such queries. #155163
• Optimized validation queries during ALTER PRIMARY KEY to avoid counting the primary key multiple times. #156889
• The optimizer now splits disjunctions on the same column into unions when there are multiple partial indexes with different predicates referencing that column. #157083

Build changes

• Upgraded to Go version 1.25.3 #156000

Miscellaneous

• Added initial and catchup scan metrics to Physical Cluster Replication (PCR) under physical_replication.scanning_ranges and physical_replication.catchup_ranges. #153893
• Added a retry policy for Azure Blob Storage with a default of 60 seconds to mitigate occasional stuck operations. The retry policy is configurable with the cloudstorage.azure.try.timeout setting. #154149
• Logical Data Replication (LDR) now updates the logical_replication.scanning_ranges and logical_replication.catchup_ranges metrics during fast initial scan. #155274
• Added the jobs.registry.max_adoptions_per_loop cluster setting to configure the maximum number of jobs a node can adopt per adoption loop. #155385
• Fixed a bug that prevented admin users from having full access to external connections created by other users. #155657
• LDR no longer requires the database name to be specified in the external connection URI when setting up a bidirectional stream. #155729
• Span config reconciliation jobs no longer fail on the destination after failover from a PCR stream of a system virtual cluster. #156003
• Added support of partial indexes to Logical Data Replication, tolerant of mismatched column IDs in the source and destination tables. #156935
• Display whether build is FIPS-enabled in cockroach version #157223