What's New in v20.2.0

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.

November 10, 2020

With the release of CockroachDB v20.2, we've made a variety of productivity, management, and performance improvements. Check out a summary of the most significant user-facing changes and then upgrade to CockroachDB v20.2.

To learn more, read the v20.2 blog post.


A denial-of-service (DoS) vulnerability is present in CockroachDB v20.2.0 - v20.2.3 due to a bug in protobuf. This is resolved in CockroachDB v20.2.4 and later releases. When upgrading is not an option, users should audit their network configuration to verify that the CockroachDB HTTP port is not available to untrusted clients. We recommend blocking the HTTP port behind a firewall.

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


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.


Docker image

$ docker pull cockroachdb/cockroach:v20.2.0


Get a free v20.2 cluster on CockroachCloud

Recent CockroachCloud improvements:

Feature summary

This section summarizes the most significant user-facing changes in v20.2.0. For a complete list of features and changes, including bug fixes and performance improvements, see the release notes for previous testing releases. You can also search for what's new in v20.2 in our docs.


"Core" features are freely available in the core version and do not require an enterprise license. "Enterprise" features require an enterprise license. CockroachCloud clusters include all enterprise features.


Version Feature Description
Core Third-Party Tool Support CockroachDB now fully supports several additional third-party database tools, including Spring Boot, Hibernate, and ActiveRecord.
Core Spatial Support CockroachDB now supports spatial data types, spatial indexes, and spatial functions, as well as the ability to migrate spatial data from various formats such as Shapefiles, GeoJSON, GeoPackages, and OpenStreetMap.
Core User-Defined Schemas You can now create user-defined logical schemas, as well alter user-defined schemas, drop user-defined schemas, and convert databases to user-defined schemas.
Core Partial Indexes You can now use partial indexes to specify a subset of rows and columns in a table that evaluate to true on a WHERE filter defined at index creation.
Core ENUM data types CockroachDB now supports the creation and management of user-defined ENUM data types consisting of sets of enumerated, static values.
Core Materialized Views CockroachDB now supports materialized views, or views that store their selection query results on-disk.
Core View Replacement CockroachDB now supports replacing an existing view with the CREATE OR REPLACE VIEW syntax.
Core Foreign Key Performance and Compatibility When adding the FOREIGN KEY constraint, it is no longer required to have an index on the referencing columns.
Core EXPLAIN Improvements The response of the EXPLAIN statement now includes the estimated number of rows scanned by the query as well as other usability improvements.
Core Disallowing Full Table Scans You can use the new disallow_full_table_scans session variable to disallow full table and secondary index scans.
Core Altering Column Data Types You can now alter the data type of table column. Note that this feature is experimental and is subject to change.

Recovery and I/O

Version Feature Description
Core Backup/Restore in Core Version The core version of CockroachDB now lets you perform full cluster backups, all restore options, as well as bulk exports. Incremental backups, locality-aware backups, and other advanced backup functionality continue to require an enterprise license.
Core Backup Scheduling You can now create schedules for CockroachDB backups, as well as view, pause, resume, and drop backup schedules. Once a scheduled backup is created, you can use SHOW SCHEDULE to inspect the schedule status and any errors and then use SHOW BACKUPS IN and SHOW BACKUP to inspect the details of individual backups. Note that incremental backups, locality-aware backups, and other advanced backup functionality require an enterprise license.
Core Import with User-Scoped Storage In addition to supporting bulk imports from cloud storage, CockroachDB now lets you upload CSV files from your local machine to user-scoped file storage in your cluster. Once uploaded, a userfile can be reference by the IMPORT command to import data into a table. Userfiles can also be listed and deleted via CLI commands.
Core Import with Default Expressions You can now use IMPORT INTO to import supported DEFAULT expressions as well as computed columns.
Enterprise KMS Support for Encrypted Backups You can now use AWS Key Management Service (KMS) to encrypt the files that full or incremental backups generate.

Deployment and Operations

Version Feature Description
Core Kubernetes Operator The CockroachDB Kubernetes Operator eases deployment of secure CockroachDB clusters on Kubernetes. The Operator can be used to create StatefulSets, authenticate pods, scale CockroachDB clusters, and perform rolling upgrades. The Operator is in beta and is not yet production-ready.
Core Log Redaction When gathering log files via the cockroach debug zip or cockroach debug merge-logs command, you can use the new --redact-logs flag to redact sensitive data. Note that this flag removes sensitive information only from the log files; other items collected by the debug zip command may still contain sensitive information.
Core Certificate Revocation with OCSP CockroachDB now supports certificate revocation for custom CA certificate setups running an OCSP server.
Enterprise SSO in the DB Console The DB Console now supports single sign-on (SSO) via OpenID Connect (OIDC), an authentication layer built on top of OAuth 2.0. When SSO is configured and enabled, the DB Console login page displays an OAuth login button in addition to the password access option. Note that this feature is experimental and is subject to change.
Core Permission-Based Object Ownership All database objects now have owners. By default, the user who created an object is the owner of the object and has all privileges on the object. Any roles that are members of the owner role have all privileges on the objects the role owns. The admin is the default owner for all non-system objects without owners. System objects without owners have node as their owner.
Core Fine-Grained SQL Privileges CockroachDB now allows you to grant users administrative abilities without giving them full admin access.


Version Feature Description
Core Transaction Details The new Transactions page of the DB Console shows you details about all client-initiated transactions in the cluster that help you identify and troubleshoot frequently retried and high-latency transactions.
Core Sessions Details The new Sessions page of the DB Console shows you details about all active and idle sessions in the cluster, with session age, memory usage, SQL statement, and other details available for active sessions.

Backward-incompatible changes

Before upgrading to CockroachDB v20.2, be sure to review the following backward-incompatible changes and adjust your deployment as necessary.

  • A CockroachDB node started with cockroach start without the --join flag no longer automatically initializes the cluster. The cockroach init command is now mandatory. The auto-initialization behavior had been deprecated in version 19.2.
  • CockroachDB v20.1 introduced a new rule for the --join flag to cockroach start, causing it to prefer SRV records, if present in DNS, to look up the peer nodes to join. This feature is experimental, and has been found to cause disruption in in certain deployments. To reduce this disruption and the resulting UX surprise, the feature is now gated behind a new command-line flag --experimental-dns-srv which must now be explicitly passed to cockroach start to enable it.
  • The --socket flag of cockroach start was deprecated in v20.1 and has been removed in v20.2. Use --socket-dir instead.
  • The textual error and warning messages displayed by cockroach quit under various circumstances have been updated. Meanwhile, the message "ok" remains as an indicator that the operation has likely succeeded.
  • cockroach quit now prints out progress details on its standard error stream, even when --logtostderr is not specified. Previously, nothing was printed on standard error. Scripts that wish to ignore this output can redirect the stderr stream.
  • Previously, the phase of server shutdown responsible for range lease transfers to other nodes would give up after 10000 attempts of transferring replica leases away, regardless of the value of server.shutdown.lease_transfer_wait. The limit of 10000 attempts has been removed, so that now only the maximum duration server.shutdown.lease_transfer_wait applies.
  • Previously, issuing a SIGTERM signal twice or after another signal initiated a hard shutdown for a node. Now the first SIGTERM signal initiates a graceful shutdown and further occurrences of SIGTERM are ignored. To initiate a hard shutdown, issue SIGINT two times (or issue a SIGINT signal once after a SIGTERM signal).
  • Clusters running alphas of 20.2 that use ENUM types will not be able to upgrade to betas or major releases of 20.2 due to internal representation changes.
  • Specifying the same option multiple times in the WITH clause of the BACKUP or RESTORE statement now results in an error message. Additionally, quoted option names are no longer allowed.
  • The copy of system and crdb_internal tables extracted by cockroach debug zip is now written using the TSV format (inside the zip file), instead of an ASCII-art table as previously.
  • The SHOW RANGE FOR ROW statement now takes a tuple of the row's index columns instead of the full column set of the row.
  • For expression typing involving only operations on constant literals, each constant literal is now assigned a type before calculation. Previously, a type was assigned only to the final result.
  • The file names for heap profile dumps now use the naming scheme memprof.<date-and-time>.<heapsize>. Previously, they were named memprof.<heapsize>.<date-and-time>.
  • The Docker image is now based on RedHat's UBI instead of Debian.
  • cockroach node decommission --wait=live is no longer supported. It was deprecated in an earlier release.


  • The cockroach quit command is now deprecated. For decommissioning, use the cockroach node decommission command. To terminate the cockroach process, use signals.
  • The cockroach dump command is now deprecated. Instead, back up your data in a full backup, export your data in plain text format, or view table schema in plaintext with SHOW CREATE TABLE.
  • The --log-dir-max-size command-line flag is now deprecated and has been replaced with a new flag named --log-group-max-size. The flags limit the combined size of all files generated by one logging group inside CockroachDB.
  • CockroachDB built-in SQL shell (cockroach sql and/or cockroach demo) no longer prompts for more lines of input after the user enters BEGIN before sending the input to the server. Instead, full lines of input are always sent to the server immediately. The corresponding client-side option smart_prompt is thus ineffective and deprecated. It will be removed in a later version.
  • Cross-database references are deprecated in v20.2 (see tracking issue). In v20.2, creating cross-database references is disabled for foreign keys, views, and sequence ownership with the sql.cross_db_fks.enabled, sql.cross_db_views.enabled, and sql.cross_db_sequence_owners.enabled cluster settings set to false by default. Note that any cross-database references that were created prior to a v20.2 upgrade are still allowed and are unaffected by these cluster settings.

    After upgrading to v20.2, we recommend removing all cross-database references, and, if necessary, creating object references across user-defined schemas instead. For details on migrating a cluster that does not use user-defined schemas in its naming hierarchy, see Migrating namespaces from previous versions of CockroachDB.

  • Interleaved tables are deprecated in CockroachDB v20.2, and will be permanently disabled in a future release (see tracking issue).

    After upgrading to v20.2, we recommend that you convert any existing interleaved tables to non-interleaved tables and replace any existing interleaved secondary indexes with non-interleaved indexes. For instructions, see INTERLEAVE IN PARENT Deprecation.

Known limitations

For information about new and unresolved limitations in CockroachDB v20.2, with suggested workarounds where applicable, see Known Limitations.


Area Topic Description
Training Online Course for Python Developers Launched a new self-paced course on Cockroach University, CockroachDB for Python Developers. This course walks you through building a full-stack vehicle-sharing app in Python using the popular SQLAlchemy ORM and a free CockroachCloud cluster as the back-end.
Docs Interactive In-Browser Tutorials Added tutorials that can be completed entirely in your browser, without downloads or installations, from Learning CockroachDB SQL to Building a Python App on CockroachDB to Storing and Querying JSON.
Docs Transaction Retry Error Reference Documented the various errors that developers encounter around transaction retries in CockroachDB, explaining why each error happens and what to do about it.
Docs Disaster Recovery Documented how to plan for and recover from various types of disasters, from hardware failure, to data failure, to compromised security keys.
Docs Batch Deletes Added guidance on performing large deletes across various scenarios.
Docs Multi-Region Kubernetes on EKS Added a tutorial on orchestrating a secure CockroachDB multi-region deployment on Amazon EKS.
YesYes NoNo