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

Source tag

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

Backward-incompatible changes

• AS OF SYSTEM TIME queries can no longer use a timestamp followed by a question mark to signify a future-time value. This was an undocumented syntax. #116830

Enterprise edition changes

• ALTER CHANGEFEED no longer removes a CDC query when modifying changefeed properties. #116498
• changefeed.balance_range_distribution.enable is now deprecated. Instead, use the new cluster setting changefeed.default_range_distribution_strategy. changefeed.default_range_distribution_strategy='balanced_simple' has the same effect as setting changefeed.balance_range_distribution.enable=true. It does not require initial_scan='only', which was required by the old setting. #115166
• CDC queries now correctly handle the changefeed_creation_timestamp function. #117520
• The new syntax ALTER VIRTUAL CLUSTER virtual-cluster START REPLICATION OF virtual-cluster ON physical-cluster can now be used to reconfigure virtual clusters previously serving as sources for physical cluster replication to become standbys to a promoted standby. This reverses the direction of replication while maximizing data reuse. #117656
• BACKUPs now load range information that is used to avoid a spike in metadata lookups when backups begin. #116520
• Clusters created to run physical cluster replication no longer automatically disable the spanconfig.range_coalescing.system.enabled and spanconfig.range_coalescing.application.enabled cluster settings. Users who started using physical cluster replication on v23.1 or v23.2 may wish to manually reset these settings. #119221
• Physical cluster replication is now always enabled, and the physical_replication.enabled cluster setting has been removed. #119149

SQL language changes

• ALTER BACKUP SCHEDULE ... EXECUTE IMMEDIATELY can now be used to set the next scheduled execution of the backup schedule to the current time. #112118
• Fixed the SQL Activity update job to avoid conflicts on update, reduced the amount of data cached to just what the overview page requires, and fixed the correctess of the top queries. #112350
• Previously, user-defined composite types were not populated in two pg_catalog tables: pg_class (whose row entries pertain to the type) and pg_attribute (whose row entries pertain to the "columns" of the type). This PostgreSQL-incompatible behavior is now fixed by populating the tables with user-defined composite types. In addition, the typrelid column in the pg_type table has the proper oid for composite types. #111179
• The newly added built-in function jsonb_array_to_string_array no longer removes NULL objects. It now includes them in the resulting array. #112975
• Changed the display for RU estimates shown in EXPLAIN ANALYZE from integer to float. This will prevent small estimates from being rounded to zero, which makes the estimate less confusing for cheap queries. #111986
• The information_schema._pg_char_octet_length built-in function is now supported, which improves compatibility with PostgreSQL. #111401
• The pg_encoding_max_length built-in function is now supported, which improves compatibility with PostgreSQL. #111401
• The information_schema._pg_datetime_precision built-in function is now supported, which improves compatibility with PostgreSQL. #111401
• The information_schema._pg_interval_type built-in function is now supported, which improves compatibility with PostgreSQL. #111401
• information_schema.user_defined_types is now populated with information about user-defined types, and information_schema.attributes is now populated with information about the attributes of composite data types. #111401
• The cost-based optimizer will no longer generate a constrained scan that only uses filters from a check constraint. This prevents cases where a constrained scan actually scans the entire table because the constraints aren't selective. #114332
• Reads rolled back by savepoints are now refreshable, matching the PostgreSQL behavior and avoiding potential serializability violations. #111424
• Implemented the postgis ST_TileEnvelope built-in function. #112971
• Added support for a third argument in the array_position built-in function. If provided, it gives the index from which to begin searching in the array. #112161
• Added the bit_count built-in function for BIT and BYTES types. #115273
• Added a pg_backend_pid column to crdb_internal.node_sessions and crdb_internal.cluster_sessions. This value corresponds to the numerical ID returned from pg_backend_pid. #116673
• Column type changes now require an explicit cast when automatic casting is not possible. This aligns with PostgreSQL's behavior. Previously, certain type conversions, such as BOOL to INT, were allowed without an explicit cast. #115442
• Added a new session setting, optimizer_merge_joins_enabled that, when true, instructs the cost-based optimizer to explore query plans with merge joins. The setting defaults to true. #116410
• CockroachDB now supports parsing queries like SELECT FROM t that only produce the row count and do not output any columns. #116835
• Added the metaphone built-in function, which converts a string to its Metaphone code. #110950
• The new EXPIRATION WINDOW option for ALTER VIRTUAL CLUSTER allows the user to override the default producer job expiration window of 24 hours. For example, ALTER VIRTUAL CLUSTER appTenant SET REPLICATION EXPIRATION WINDOW ='100ms'. The producer job expiration window determines how long the producer job stays alive without a heartbeat from the consumer job. #117776
• The SKIP LOCKED clause is now allowed with SELECT ... FOR SHARE. #117560
• Added configurable cluster settings for total TCP keep alive probes (server.sql_tcp_keep_alive.count) and TCP probe intervals (server.sql_tcp_keep_alive.interval) for SQL connections. Removed the COCKROACH_SQL_TCP_KEEP_ALIVE environment variable subsuming it. #115833
• Removed the sql.trace.session_eventlog.enabled cluster setting and the associated event log tracing. The information in these traces is still available in the DEV log channel by enabling --vmodule=conn_executor=2 with cockroach start. #117928
• The array_agg aggregate function can now support arrays as the input. Note that CockroachDB does not yet fully support nested arrays, and array_agg does not support nested arrays as inputs. #117838
• An execution statistic that measures "client time" is now included in plan.txt files of statement diagnostics bundles. Client time tracks how long the query execution was blocked on the client receiving the PGWire protocol messages. Note that when obtained via EXPLAIN ANALYZE (DEBUG), client time does not make sense because in this variant the output rows are discarded and not communicated to the client. #117591
• Added the trace_id column to the response of the SHOW SESSIONS command. #118002
• Added support for the ENCODING option of COPY, as long as the encoding of 'utf8' is specified. #118010
• Added the SHOW VARIABLES FOR ROLE command, which allows the database administrator to easily view the default values for session variables applied to a given user. #117875
• The sql.txn.read_committed_isolation.enabled cluster setting is now true by default. This means that any syntax and settings that configure the READ COMMITTED isolation level will now cause the transaction to use that isolation level, rather than automatically upgrading the transaction to SERIALIZABLE. #118479
• Added a new cluster setting, sql.stats.virtual_computed_columns.enabled, which when set enables collection of table statistics on VIRTUAL computed columns. #118241
• Added the autocommit_before_ddl session variable. When set to true, any schema change statement that is sent during an explicit transaction will cause the transaction to commit before executing the schema change. #118440
• CREATE SEQUENCE is now enabled by default in the declarative schema changer. #117793
• PL/pgSQL now supports nested blocks, with the following limitations: variable shadowing is disallowed, and exception handlers cannot be used in a routine with nested blocks. #117710
• The cluster setting sql.index_recommendation.drop_unused_duration is now public. #118676
• It is now possible to hint to the cost-based optimizer that it should plan a straight join by using the syntax ... INNER STRAIGHT JOIN .... If the hint is provided, the optimizer will now fix the join order as given in the query, even if it estimates that a different plan using join reordering would have a lower cost. #116013
• Add column goroutine_id to the response of the SHOW SESSIONS command. #118644
• Introduced a new session setting, close_cursors_at_commit, which causes a cursor to remain open even after its calling transaction commits. Note that transaction rollback still closes any cursor created in that transaction. #117910
• Added the server.max_open_transactions_per_gateway cluster setting. When set to a non-negative value, non-admin users cannot execute a query if the number of transactions open on the current gateway node is already at the configured limit. #118781
• Added the setseed built-in function. It sets the seed for the random generator used by the random built-in function. #119042
• OUT and INOUT parameter classes are now supported in user-defined functions. #118610
• Out-of-process SQL servers will now start exporting a new sql.aggregated_livebytes metric. This metric gets updated once every 60 seconds by default, and its update interval can be configured via the tenant_global_metrics_exporter_interval cluster setting. #119140
• Added support for index hints with INSERT and UPSERT statements. This allows INSERT ... ON CONFLICT and UPSERT queries to use index hints in the same way they are already supported for UPDATE and DELETE statements. #119104
• Added a new ttl_disable_changefeed_replication table storage parameter that can be used to disable changefeed replication for row-level TTL on a per-table basis. #119611

Operational changes

• The internal versions that are reported during cluster upgrades have been renamed for clarity. For example, 23.2-8 is now named 23.2-upgrading-to-24.1-step-008. #115223
• Introduced a new cluster setting, server.jwt_authentication.jwks_auto_fetch.enabled, enabling automatic fetching of JSON Web Key Sets (JWKS) from an issuer's remote endpoint. This prevents an administrator's need to update the JWKS specified in server.jwt_authentication.jwks - whether manually or by custom script - when the identity provider's keys rotate. That direct specification of JWKS remains the default, as the new cluster setting defaults to false. #117054
• Updated the error message logged in the case of stalled disks to use the appropriate term "disk stall", matching the term used in metrics and dashboards. This was previously "file write stall". #114746
• Introduced the changefeed.emitted_batch_sizes histogram metric that measures the batch sizes used when emitting data to sinks. This metric supports metrics labels. #115537
• Introduced metrics log_fluent_sink_conn_attempts, log_fluent_sink_write_attempts, and log_fluent_sink_write_errors to enable more precise tracking of connection and write operations when logging to Fluentd-compatible network collectors. #116699
• The cluster setting sql.contention.record_serialization_conflicts.enabled is now on by default. This means any 40001 errors that are returned containing conflicting transaction information will be recorded by the contention registry. #116664
• Removed the kv.rangefeed.scheduler.enabled cluster setting because the rangefeed scheduler is now unconditionally enabled. #114410
• Removed the kv.rangefeed.catchup_scan_concurrency cluster setting. Catchup scans are throttled via kv.rangefeed.concurrent_catchup_iterators on a per-node basis. #114408
• Removed the changefeed.mux_rangefeed.enabled cluster setting because the functionality is enabled by default. #114408
• The gossip status Advanced Debug page now includes information about the server's high water timestamps for every other node it knows about in the gossip cluster. #117011
• Removed the cockroach_rangefeed_rpc_initial_window_size environment variable. The rangefeed connection now uses the same window size as other RPC connections. #117545
• Events for cluster setting changes are now emitted to the OPS channel rather than the DEV channel. #117923
• The new environment variable cockroach_rpc_use_default_connection_class enables operators to switch back to the prior default behavior of sending most network/RPC workloads, except system traffic, through a single RPC/TCP connection, in case the environment does not tolerate multiple TCP connections. v24.1 defaults to using multiple connections, each dedicated to a particular types of traffic, specifically for Raft or rangefeed data. For more information, see additional release notes that reference this variable name. #117810
• In unredacted debug zips, the crdb_internal.transaction_contention_events table file has two new columns:
  • waiting_stmt_query: the query of the waiting statement.
  • blocking_txn_queries_unordered: the unordered list of the blocking transaction's queries. #118478
• Transaction replay protection state is now passed between the outgoing and incoming leaseholder for a range during a lease transfer. This avoids cases where lease transfers can cause transactions to throw TransactionAbortedError(ABORT_REASON_NEW_LEASE_PREVENTS_TXN) errors. #118300
• CockroachDB will now automatically generate CPU profiles if there is an increase in CPU utilization. This can help inform investigations into possible issues. #118850
• Expanded the --include-range-info flag to include problem ranges. This flag still defaults to true. #119205

Command-line changes

• Debug zips no longer include redundant hex_ columns for system table BYTES columns. #112033
• Added the --follower-read-percent flag, which determines the percent (0-100) of read operations that are follower reads, to the cockroach workload kv run command. #113094
• The workload schemachange now writes a .otlp.ndjson.gz archive containing OTLP trace bundles for debugging purposes. #114770
• cockroach debug tsdump creates a tsdump.yaml file. The tsdump raw format automatically creates the YAML file in the default location /tmp/tsdump.yaml. Added a new flag --yaml that allows users to specify the path to create tsdump.yaml instead of using the default location. For example, cockroach debug tsdump --host <host>:<port> \ --format raw --yaml=/some_path/tsdump.yaml > /some_path/tsdump.gob. #114046
• Removed the cockroach connect command functionality. This was deprecated in CockroachDB v23.2. #113893
• Changed the SQL shell help URL to point to cockroach-sql. #118960
• Added a new encode-uri utility to make generating connection strings for use with Physical Cluster Replication easier. #119528

DB Console changes

• Store initialization now logs progress every 10 seconds showing the current and total number of replicas initialized. #115760
• Introduced a new Lease Preferences graph on the Replication dashboard. The Lease Preferences graph will indicate when the current leaseholder is not the first lease preference and where the current leaseholder satisfies no applied lease preference. #116709
• Updated the Statement Details page to always show the entire selected period, instead of just the period that had data. #118680
• Error messages displayed upon failure to load DB Console views now include information about the HTTP response status code, if one is present. #118782
• The Full Table/Index Scans chart in the SQL Metrics dashboard now shows the non-negative derivative of the number of full scans tracked. #118787
• The Overload dashboard now includes two additional graphs:
  • Elastic CPU Utilization: displays the CPU utilization by elastic work, compared to the limit set for elastic work.
  • Elastic CPU Exhausted Duration Per Second: displays the duration of CPU exhaustion by elastic work, in microseconds. #118763
• The txn.restarts.writetooold metric in the Transaction Restarts graph under the SQL Dashboard now includes all restarts previously categorized as txn.restarts.writetoooldmulti. The former is a now a superset of the latter. The txn.restarts.writetoooldmulti metric will be removed in a future release. #119411

Bug fixes

• Fixed a bug that could cause an internal error during distributed execution for an expression like CASE that requires its inputs to be the same type with all NULL inputs. #108892
• Fixed NULL input handling for the geospatial built-ins st_pointfromgeohash and st_geomfromgeohash. #113781
• The geospatial st_makeenvelope built-in now correctly supports xmin or ymin to be greater than xmax or ymax, respectively. #113781
• Fixed a bug that could cause v23.1 nodes in clusters that had not finalized the v23.1 version upgrade to use excessive CPU retrying expected errors related to the incomplete upgrade state. #113864
• Debug zip now does not fail on corrupted log files. #113722
• Placeholder arguments can now be used in SET TRANSACTION statements. #113689
• Previously, when the session variable use_declarative_schema_changer was set to off, ALTER PRIMARY KEY would delete any comments associated with the old primary index and old primary key constraint. This is inconsistent with the behavior of use_declarative_schema_changer=on, which is the default setting, where those comments would be carried over to the new primary index. Furthermore, the old behavior also caused a bug that could prevent command SHOW CREATE t from working. #114354
• Previously, when the session variable was set to use_declarative_schema_changer=off and there was an attempt to ALTER PRIMARY KEY on a table that has unique secondary indexes on new primary key columns, the unique secondary index would still incorrectly have old primary key columns as its keySuffixColumn after the ALTER PRIMARY KEY. This was problematic because a subsequent dropping of the old primary key columns would unexpectedly drop those unique secondary indexes as well, even without CASCADE. #114622
• ALTER BACKUP SCHEDULE can now be used to set updates_cluster_last_backup_time_metric without providing an explicit value, matching the behavior of the option when specified during CREATE SCHEDULE FOR BACKUP. #113523
• Previously, if a table had secondary indexes that stored certain columns (col) using the STORING clause, followed by an ALTER PRIMARY KEY to col, an incorrect secondary index would persist. The secondary index would continue to have the STORING clause, despite the column being part of the primary key and the fact that CockroachDB does not permit secondary indexes to store any primary key columns. Now, after the ALTER PRIMARY KEY, the STORING clause is dropped on those secondary indexes. #115214
• Fixed a bug that caused uploads to object-locked buckets to fail because of the absence of an MD5 hash. #115713
• ALTER PRIMARY KEY now preserves the name of the original primary index when the session variable is use_declarative_schema_changer=off. #115338
• Fixed a bug where the unique-without-index-not-valid constraint added to a table would cause the create_statement from SHOW CREATE t to not be executable and error with unique constraint cannot be NOT VALID. #115354
• Fixed a bug where an empty full backup followed by non-empty incremental backups taken inside an application tenant might not allow a restore due to the use of an incorrect SQL codec. #116316
• Fixed a bug in the row-level TTL job that would cause it to skip expired rows if the primary key of the table included columns of the collated STRING or DECIMAL type. #116988
• Incorrectly labeled PL/pgSQL blocks now return an expected syntax error. #117608
• CREATE EXTERNAL CONNECTION IF NOT EXISTS no longer returns an error if the connection already exists. #117312
• CockroachDB now correctly uses the histograms on columns of collated STRING type. The bug has been present since before v22.1. #117714
• Improved an interaction during range lease transfers that could cause RETRY_ASYNC_WRITE_FAILURE errors to be returned to clients. #117840
• Backfilling tables for CREATE TABLE AS or CREATE MATERIALIZED VIEW could get into a retry loop if data was deleted and those jobs took longer than the GC TTL. #117877
• Decommissioning replicas that are part of a mis-replicated range will no longer get stuck on a rebalance operation that was falsely determined to be unsafe. #117900
• A memory leak within the insights system was found to occur when sql.metrics.transaction_details.enabled was disabled, while leaving sql.metrics.statement_details.enabled enabled. This patch fixes the memory leak by preventing the collection of further statement and transaction insights when sql.metrics.transaction_details.enabled is disabled. #117709
• Fixed a rare panic that could happen during a pg_dump import that contains a function that has a subquery in one of its arguments, like SELECT addgeometrycolumn(...). Now, attempting to import a pg_dump with such a function results in an expected error. #118569
• AUTO CREATE STATS jobs could previously lead to growth in an internal system table resulting in slower job-system related queries. #118589
• Fixed an issue in CockroachDB where, if operating on a Linux system outside of a CPU cgroup, the system would repeatedly log the error unable to get CPU capacity at 10-second intervals. #118657
• Fixed a bug where casts of floats to integers simply truncated the decimal portion. These casts now match the PostgreSQL behavior of rounding to the nearest integer, and in cases of a value halfway between two integers, rounding to the nearest even number. This aligns with the "round half to even" rule or "bankers' rounding", offering greater overall precision across a group of such cast operations. #117798
• Fixed a bug where statements like ADD COLUMN j INT, ADD UNIQUE WITHOUT INDEX (j), which add new columns with unique constraints without creating associated indexes, would fail with an internal error. #118291
• Previously, altering from a REGIONAL BY ROW table to a REGIONAL BY TABLE table could cause leaseholders to never move to the database's primary region. This is now fixed. #118001
• Users with the VIEWACTIVITY privilege can now request statement bundles using crdb_internal.request_statement_bundle or through the DB Console SQL Activity page. #118760
• Fixed an internal error with a message like: LeafTxn ... incompatible with locking request that occurs when performing an update under READ COMMITTED isolation which cascades to a table with multiple other foreign keys. #118722
• Fixed a bug where ALTER PRIMARY KEY could fail with an error non-nullable column <x> with no value! Index scanned .. when validating recreated secondary indexes. #118843
• Fixed a bug where a sequence name allocated by SERIAL that conflicted with an existing type name would cause an error. #118861
• Fixed a bug where COMMENT ON statements could fail with an "unexpected value" error if multiple COMMENT statements were running concurrently. #119007
• Previously, in certain cases, using virtual tables such as crdb_internal.system_jobs could result in the internal error attempting to append refresh spans after the tracked timestamp has moved forward. This is now fixed. The bug was introduced in CockroachDB v23.1. #119176
• Fixed a bug where operations on the crdb_internal.leases table could cause a node to become unavailable due to a deadlock in the leasing subsystem. #119305
• If an individual replica's circuit breaker had tripped but the range was otherwise functional, for example, because the replica was partially partitioned away from the leaseholder, it was possible for a gateway to persistently error when contacting this replica instead of retrying against a functional leaseholder elsewhere. The gateway will now retry such errors against other replicas once. #118737
• Fixed a bug in changefeed webhook sinks where the HTTP request body may not be initialized on retries, resulting in the error http: ContentLength=... with Body length 0. #119326
• Fixed a bug where rangefeed resolved timestamps could get stuck, continually emitting the log message pushing old intents failed: range barrier failed, range split, typically following a range merge. #119512
• Fixed a condition where some files were not closed when inspecting backup metadata during BACKUP and RESTORE. Epic: none. #119625
• Fixed a bug where some backup metadata files opened during RESTORE were not closed. #119625
• Fixed a bug that caused internal errors when executing an EXPORT statement where the query involved sorting by columns not explicitly included in the output, due to hidden columns in the input expression. #119538
• Fixed a bug where a warning about the need to refresh data would remain displayed on the Active Executions view of the Statements and Transactions pages despite enabling Auto Refresh. #118675

Performance improvements

• Follower reads for multi-region tables now default to prioritizing replicas in the same locality, when available, with node latency as a tie breaker. Previously, latency was the primary criteria. This can improve the performance and predictability of follower reads. #112993
• During node startup, stores are now loaded in parallel by default, reducing start times for nodes with many stores. #115285
• Improved the efficiency and performance of encryption at rest. #115454
• Rangefeeds, the infrastructure used for changefeeds, now use a more efficient engine that reduces the number of goroutines and the associated Go scheduler pressure and latency. #114410
• Rangefeeds, the infrastructure used for changefeeds, now use a more efficient multiplexing protocol. #114408
• The cost-based optimizer now generates constrained scans on indexes containing boolean, computed expressions. #114798
• A separate RPC connection class is now used for most Raft traffic. This improves isolation and reduces interference with foreground SQL traffic, which reduces chances of head-of-line blocking caused by unrelated traffic under high-load conditions. The new COCKROACH_RAFT_USE_DEFAULT_CONNECTION_CLASS environment variable can be set to use the default connection class instead (the previous behavior). #117385
• Rangefeed traffic (typically for changefeeds) is now separated into its own RPC connection class. This improves isolation and reduces interference with the foreground SQL traffic, which reduces chances of head-of-line blocking caused by unrelated traffic. The new COCKROACH_RANGEFEED_USE_DEFAULT_CONNECTION_CLASS environment variable can be set to use the default connection class, the previous default choice for rangefeeds. #117730
• The initial scan traffic for changefeeds, which can be significant, now uses a different RPC/TCP connection than the foreground SQL/KV traffic. This reduces interference between workloads, and reduces chances of head-of-line blocking issues. #117810
• kafka_sink_config now supports specifying different client IDs for each changefeed, enabling users to define distinct Kafka quota configurations for each. For example, CREATE CHANGEFEED FOR ... WITH kafka_sink_config='{"ClientID": "clientID1"}' #118643
• Added the changefeed.kafka_throttling_hist_nanos metric, enhancing visibility into throttling times when CockroachDB operations exceed Kafka's quota limits. #117693
• The cost-based optimizer now generates more efficient query plans for queries with comparisons of timestamp and interval columns, for example, timestamp_col - '1 day'::INTERVAL > now(). #118307
• Statements from internal executors (use of SQL queries by the cluster itself) now correctly display when filtering by application name $ internal on the Statements page in SQL Activity. Such statements are hidden when $ internal is not specified. #114498