What's New in v20.2.4

Cockroach Labs will stop providing Assistance Support for this version on May 10, 2022. Prior to that date, upgrade to a more recent version to continue receiving support. For more details, see the Release Support Policy.

January 21, 2021

This page lists additions and changes in v20.2.4 since v20.2.3.


Cockroach Labs has discovered a bug relating to incremental backups, for CockroachDB v20.2.0 - v20.2.7. If a backup coincides with an in-progress index creation (backfill), RESTORE, or IMPORT, it is possible that a subsequent incremental backup will not include all of the indexed, restored or imported data.

Users are advised to upgrade to v20.2.8 or later, which includes resolutions.

For more information, including other affected versions, see Technical Advisory 63162.

Get future release notes emailed to you:


Docker image

$ docker pull cockroachdb/cockroach:v20.2.4

Security updates

  • When using a SQL proxy, in the default configuration CockroachDB only knows about the network address of the proxy. That peer address is then used for logging, authentication rules, etc. This is undesirable, as security logging and authentication rules need to operate on the actual (final) client address instead. CockroachDB can now be configured to solve this problem using the mechanism detailed below. When so configured, a SQL proxy can inform the CockroachDB server of the real address of the client via a server status parameter called crdb:remote_addr. The value must be the IP address of the client, followed by a colon, followed by the port number, using the standard Go syntax (e.g., for IPv4, [11:22::33]:4455 for IPv6). When provided, this value overrides the SQL proxy's address for logging and authentication purposes. In any case, the original peer address is also logged alongside the client address (overridden or not), via the new logging tag peer. Security considerations:
    • Enabling this feature allows the peer to spoof its address with respect to authentication and thus bypass authentication rules that would otherwise apply to its address, which can introduce a serious security vulnerability if the peer is not trusted. This is why this feature is not enabled by default, and must only be enabled when using a trusted SQL proxy.
    • This feature should only be used with SQL proxies which actively scrub a crdb:remote_addr parameter received by a remote client, and replaces it by its own. If the proxy mistakenly forwards the parameter as provided by the client, it opens the door to the aforementioned security vulnerability.
    • Care must be taken in host-based authentication (HBA) rules:
      • TLS client cert validation, if requested by a rule, is still performed using the certificate presented by the proxy, not that presented by the client. This means that this new feature is not sufficient to forward TLS client cert authn through a proxy. (If TLS client cert authn is required, it must be performed by the proxy directly.)
      • The protocol field (first column) continues to apply to the connection type between CockroachDB and the proxy, not between the proxy and the client. Only the 4th column (the CIDR pattern) is matched against the proxy-provided remote address override. Therefore, it is not possible to apply different rules to different client address when proxying TCP connections via a unix socket, because HBA rules for unix connections do not use the address column. Also when proxying client SSL connections via a non-SSL proxy connection, or proxying client non-SSL connections via a SSL proxy connection, care must be taken to configure address-based rule matching using the proper connection type. A reliable way to bypass this complexity is to only use the host connection type which applies equally to SSL and non-SSL connections. As of this implementation, the feature is enabled using the non-documented environment variable COCKROACH_TRUST_CLIENT_PROVIDED_SQL_REMOTE_ADDR. The use of an environment variable is a stop-gap so that this feature can be used in CockroachCloud SQL pods which do not have access to cluster settings. The environment variable will be eventually removed and replaced by another mechanism. #58380

SQL language changes

  • Added an overload to crdb_internal.pb_to_json to suppress populating default values in fields. #58127
  • A table can now be successfully dropped in a transaction following other schema changes to the table in the same transaction. #58255
  • The crdb_internal.cluster_id function now returns the ID of the underlying KV cluster in multi-tenant scenarios rather than the Nil UUID. #58441
  • Multi-tenant clusters will now send anonymous usage information to the central CockroachDB registration server. #58517

Command-line changes

  • Added a flag to cockroach debug decode-proto to suppress populating default values in fields. #58127
  • Some specific CLI usage situations now have dedicated exit status codes. #56724 The codes are defined as follows:
    • 0: Process terminated without error.
    • 1: An unspecified error was encountered. Explanation should be present in the stderr or logging output.
    • 2: Go runtime error, or uncaught panic. Likely a bug in CockroachDB. Explanation may be present in logging output.
    • 3: Server process interrupted gracefully with Ctrl+C / SIGINT.
    • 4: Command-line flag error.
    • 5: A logging operation to the process' stderr stream failed (e.g., stderr has been closed). Some details may be present in the file output, if enabled.
    • 6: A logging operation to file has failed (e.g., log disk full, no inodes, permission issue, etc). Some details may be present in the stderr stream.
    • 7: Server detected an internal error and triggered an emergency shutdown.
    • 8: Logging failed while processing an emergency shutdown.

DB Console changes

  • Made minor style changes to represent the new branding palette. #57978
  • Changed the default per-page value on the Transactions page to 20; made minor style updates. #57978

Bug fixes

  • Fixed a bug where cockroach demo --global was crashing with "didn't get expected magic bytes header". #58626
  • Fixed a bug in RESTORE where some unusual range boundaries in interleaved tables caused an error. #58259
  • Fixed a bug that was introduced in the v20.2.0 release where we mistakenly permitted users with the admin role to drop tables in the system database. This commit revokes that privilege. #57642
  • Fix a bug where the ST_MakeLine and ST_Collect functions did not respect ordering when used over a window clause. #57750
  • Fix a bug that could cause IMPORT to incorrectly read files stored on Google Cloud if uploaded using its compression option (gsutil -Z). #57748
  • Fixed a bug where schema change jobs to add foreign keysto existing tables, via ALTER TABLE, could sometimes not be successfully reverted (either due to being canceled or having failed). #57809
  • Fixes a bug where concurrent addition of a foreign key constraint and drop of a unique index could cause the foreign key constraint to be added with no unique constraint on the referenced columns. #57809
  • Fixed an assertion error caused by some DDL statements used in conjunction with common table expressions (WITH). #57951
  • Fixed a bug where canceled queries reading from virtual tables could cause a crashing panic. #57884
  • Fixed a bug where tables in schemas other than "public" would not be displayed when running SHOW TABLES FROM <db>. #57814
  • Fixed a bug that caused temp tables to not be cleaned up after the associated session was closed. #57922
  • Fixed a bug which caused type information to be omitted when decoding descriptors using either crdb_internal.pb_to_json or cockroach debug decode-proto. #58127
  • Fixed a bug where CockroachDB could return non-deterministic output when querying the information_schema.statistics virtual table (internally used by SHOW INDEXES command). Specifically, the implicit columns of the secondary indexes could be in arbitrary order. The columns will now be in the same order as they are in the primary index. #58214
  • Fixed a crash with the message "column family 0 not found" caused by EXPLAINing or gathering statement diagnostics on certain queries involving virtual tables. #58243
  • Fixed a potential "nil pointer dereference" panic when collecting diagnostics on certain queries. #58210
  • Added a safeguard against crashes while running SHOW STATISTICS USING JSON, which is used internally for statement diagnostics and EXPLAIN ANALYZE (DEBUG). #58263
  • Fixed a bug where prior schema changes on a table that failed and could not be fully reverted could prevent the table from being dropped. #58255
  • Fixed a bug introduced in 20.1 where CockroachDB could crash when performing a DELETE operation after an alteration of the primary key in some cases. #58266
  • Fixed a memory leak in the optimizer. The leak could have caused unbounded growth of memory usage for a session when planning queries on tables with partial indexes. #58308
  • Fixed a bug which could cause incremental backups to a backup in a collection (i.e., BACKUP INTO ... IN ...) on some cloud storage providers to ignore existing incremental backups previously appended to that destination, and instead backup incrementally from the base backup in that destination. #58331
  • Fixed a storage layer bug that could cause deleted system.jobs rows to remain on-disk indefinitely. The bloated system.jobs table could make jobs completely unavailable and prevent DDL statements from executing. This bug can be detected by examining the system.jobs table size from the DB Console. This change fixes the bug for Pebble only and the bug still persists on RocksDB. #58304
  • Fixed a bug where prepared statements that included enums and used the binary format could result in an error. #58044
  • Fixed a internal panic when using the SHOW STATISTICS USING JSON statement on a table containing ENUM types. #58413
  • Fixed a bug where SHOW GRANTS ON DATABASE did not include privileges that were granted on a database. The output includes database_name, schema_name, grantee, and privilege_type. The schema_name is always "public" since these grants are not per-schema. #58096
  • Fixed a bug where the information_schema.schema_privileges table did not includes the correct schema-level privileges for non-user-defined schemas. #58096
  • The has_schema_privilege builtin function now works on user-defined schemas when checking for the USAGE privilege. #58096
  • Fixed a bug which caused errors when querying a table with a disjunctive filter (an OR expression) that is the same or similar to the predicate of one of the table's partial indexes. #58437
  • Fixed a bug where a CREATE TABLE statement with indexes with duplicate names resulted in an assertion failure. This bug was present since version 20.2. #58447
  • Fixed a bug where the has_${OBJECT}_privilege built-in functions such as has_schema_privilege did not check whether roles the user is a direct or indirect member of also have privileges on the object. Previously only one user was checked which was incorrect. This bug has been present since version 2.0 but became more prominent as of v20.2 when role-based access control was included in CockroachDB Core. #58512
  • Fixed a bug where CockroachDB would return an internal error when attempting to execute a hash join on a JSON column via the vectorized engine. Now a more user-friendly error is returned. #58709
  • Fixed a panic in protobuf decoding. #58720

Performance improvements

  • Fixed a performance regression where the user authentication flow was performing extraneous name lookups. This regression was present since v20.2. #58739
  • Previously, when performing an unordered DISTINCT operation via the vectorized execution engine, CockroachDB would buffer up all tuples from the input, which is a suboptimal behavior when the query has a LIMIT clause. This behavior was introduced in v20.1, and has now been fixed. Note that the old row-by-row engine doesn't have this issue. #57643
  • Partial indexes with IS NOT NULL predicates can be used in cases where JOIN filters implicitly imply the predicate. This results in more efficient query plans for JOINs and foreign key checks. #58272
  • SQL statistics collection has been made more efficient by avoiding an accidental heap allocation per row for some schemas. #58197


  • Correctly export schedules_BACKUP_* metrics as well as a backup RPO metric. #57512


This release includes 58 merged PRs by 27 authors.

YesYes NoNo