What's New in v21.2.0

November 16, 2021

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

To learn more:


During an upgrade of a CockroachDB cluster from v21.1.x → v21.2.0, backups will fail until the upgrade is finalized. After the upgrade is complete and finalized, backups will continue as normal.

This issue will only occur if the upgrade coincides with a backup. For small clusters, where the upgrade is quick, there may be no overlap, and you will not experience this issue.

For more information, including mitigation, see Technical Advisory 72389.


The CockroachDB executable for Windows is experimental and not suitable for production deployments. Windows 8 or higher is required.

Docker image

$ docker pull cockroachdb/cockroach:v21.2.0

CockroachDB Cloud

Feature summary

This section summarizes the most significant user-facing changes in v21.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 v21.2 in our docs.


"Core" features are freely available in the core version of CockroachDB and do not require an enterprise license. "Enterprise" features require an enterprise license. CockroachDB Cloud clusters include all enterprise features. You can also use cockroach demo to test enterprise features in a local, temporary cluster.


Version Feature Description
Enterprise Multi-region observability You can now surface region information by using the EXPLAIN ANALYZE statements. This information is also now available in the DB Console.
Enterprise Restricted and default placement You can now use the ALTER DATABASE ... PLACEMENT RESTRICTED statement to constrain the replica placement for a multi-region database's regional tables to the home regions associated with those tables.
Enterprise Bounded staleness reads Bounded staleness reads are now available in CockroachDB. These use a dynamic, system-determined timestamp to minimize staleness while being more tolerant to replication lag than exact staleness reads. This dynamic timestamp is returned by the with_min_timestamp() or with_max_staleness() functions. In addition, bounded staleness reads provide the ability to serve reads from local replicas even in the presence of network partitions or other failures.
Core Privilege inheritance CockroachDB's model for inheritance of privileges that cascade from schema objects now matches PostgreSQL. Added support for ALTER DEFAULT PRIVILEGES and SHOW DEFAULT PRIVILEGES.
Core ON UPDATE expressions An ON UPDATE expression can now be added to a column to update column values when an UPDATE or UPSERT statement modifies a different column value in the same row, or when an ON UPDATE CASCADE expression on a different column modifies an existing value in the same row.
Core More granular controls for session variables There are now more ways to control CockroachDB's behavior through session variables. You can now set user or role-level defaults by using the ALTER ROLE statement. CockroachDB also now supports setting session variables for the duration of a single transaction, using the LOCAL keyword.
Core Transaction guardrails Transaction guardrails have been added to CockroachDB to improve production stability. These can help prevent cluster unavailability and protect the cluster against multiple developer workloads with problematic SQL statements.
Core Expression indexes Indexes on expressions can now be created. These indexes speed up queries that filter on the result of that expression, and are especially useful for indexing only a specific field of a JSON object.
Core Correlated CTEs Correlated common table expressions (CTEs) are now supported in CockroachDB. A correlated CTE is a common table expression that is contained in a subquery and references columns defined outside of the subquery.
Core Admission control A new admission control system has been added. CockroachDB implements this optional admission control system to maintain cluster performance and availability when some nodes experience high load. Admission control is disabled by default.

Additionally, an Overload dashboard has been added to the DB Console. Use this dashboard to monitor the performance of the parts of your cluster relevant to the cluster's admission control system. This includes CPU usage, the runnable goroutines waiting per CPU, the health of the persistent stores, and the performance of admission control system when it is enabled.
Core Persistent statement and transaction statistics Statistics information on the Statements and Transactions pages within the DB Console can now be persisted for longer than one hour.
Core Index usage statistics Index usage statistics are now supported for CockroachDB to help identify unused indexes causing unnecessary performance overhead for your workload. Index read statistics are available in the crdb_internal schema for programmatic access using SQL.
Core Third-party tool support Sequelize, a Javascript object-relational mapper (ORM), and Alembic, a schema migration tool for SQLAlchemy users, are now fully supported. We have also improved testing for PgBouncer, an external connection pooler for PostgreSQL.
Core Contention views You can now use pre-built contention views in crdb_internal to quickly identify the top contending indexes. These views can be used to understand where and avoid contention happening in your workload.

Recovery and I/O

Version Feature Description
Enterprise BACKUP / RESTORE scalability BACKUP and RESTORE performance has been improved for larger data volumes, more frequent backups, and clusters with more or larger nodes.
Enterprise Webhook changefeed sink You can now stream individual changefeed messages as webhook messages to a newly supported webhook-https sink. The webhook sink is a flexible, general-purpose sink solution that does not require managing a Kafka cluster or cloud storage sink.
Enterprise Multi-region bulk operations improvements The following bulk operations are now supported:
Enterprise Changefeeds for regional by row tables Changefeeds are now supported on regional by row tables.
Enterprise Changefeed observability You can now display specific fields related to changefeed jobs by running SHOW CHANGEFEED JOBS.

Database operations

Version Feature Description
Enterprise Kubernetes Operator on Amazon EKS The Kubernetes Operator is now supported on Amazon EKS (Elastic Kubernetes Service).
Enterprise Extend the Kubernetes Operator API The Kubernetes Operator API has been extended to a state where it can support the various types of single-region deployments the Helm chart currently supports. This includes:
  • Node affinity
  • Pod affinity and anti-affinity
  • Taints and tolerations
  • Custom labels and annotations
    Enterprise Multi-region in the DB Console The DB Console now surfaces multi-region information to provide observability into global databases and their workloads. You can view multi-region details on the Databases, Statements, and Transactions pages.
    Core Automatic ballast files CockroachDB now automatically creates an emergency ballast file at startup time. The cockroach debug ballast command is still available but deprecated. For more information about how automatic ballast file creation works, see automatic ballast files.

    Backward-incompatible changes

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

    • Interleaved tables and interleaved indexes have been removed. Before upgrading to v21.2, convert interleaved tables and replace interleaved indexes. Clusters with interleaved tables and indexes cannot finalize the v21.2 upgrade.
    • Previously, CockroachDB only supported the YMD format for parsing timestamps from strings. It now also supports the MDY format to better align with PostgreSQL. A timestamp such as 1-1-18, which was previously interpreted as 2001-01-18, will now be interpreted as 2018-01-01. To continue interpreting the timestamp in the YMD format, the first number can be represented with 4 digits, 2001-1-18.
    • The deprecated cluster setting cloudstorage.gs.default.key has been removed, and the behavior of the AUTH parameter in Google Cloud Storage BACKUP and IMPORT URIs has been changed. The default behavior is now that of AUTH=specified, which uses the credentials passed in the CREDENTIALS parameter, and the previous default behavior of using the node's implicit access (via its machine account or role) now requires explicitly passing AUTH=implicit.
    • Switched types from TEXT to "char" for compatibility with PostgreSQL in the following columns: pg_constraint (confdeltype, confmatchtype, confudptype, contype) pg_operator (oprkind), pg_prog (proargmodes), pg_rewrite (ev_enabled, ev_type), and pg_trigger (tgenabled).


    • The kv.closed_timestamp.closed_fraction and kv.follower_read.target_multiple settings are now deprecated and turned into no-ops. They had already stopped controlling the closing of timestamps in v21.1, but were still influencing the follower_read_timestamp() computation for a timestamp that is likely to be closed on all followers. To replace them, a simpler kv.closed_timestamp.propagation_slack setting is introduced, modeling the delay between when a leaseholder closes a timestamp and when all the followers become aware of it (defaults conservatively to 1s). follower_read_timestamp() is now computed as kv.closed_timestamp.target_duration + kv.closed_timestamp.side_transport_interval + kv.closed_timestamp.propagation_slack, which defaults to 4.2s (instead of the previous default of 4.8s).
    • Because the SELECT database privilege is being deprecated, CockroachDB now additionally checks for the CONNECT privilege on the database to allow for backing up the database. Existing users with SELECT on the database can still back up the database, but it is now recommended to GRANT CONNECT on the database.
    • IMPORT TABLE will be deprecated in v21.2 and removed in a future release. Users should create a table using CREATE TABLE and then IMPORT INTO the newly created table.
    • Granting SELECT, UPDATE, INSERT, and DELETE on databases is being deprecated. The syntax is still supported, but is automatically converted to the equivalent ALTER DEFAULT PRIVILEGES FOR ALL ROLES command. The user is given a notice that the privilege is incompatible and automatically being converted to an ALTER DEFAULT PRIVILEGE FOR ALL ROLES command.

    Known limitations

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


    Area Topic Description
    Cockroach University New Serverless course Introduction to Serverless Databases and CockroachDB Serverless teaches you the core concepts behind serverless databases and gives you the tools you need to get started with CockroachDB Serverless.
    Cockroach University New Schema Design Course Foundations of Schema Design in CockroachDB teaches you CockroachDB's rich data types and the best practices and anti-patterns to consider when designing schema for CockroachDB.
    Cockroach University New Node.js Course Fundamentals of CockroachDB for Node.js Developers walks you through building a full-stack vehicle-sharing app in Typescript using Node.js with TypeORM and a CockroachCloud Free cluster as the backend.
    Docs CockroachDB Cloud Guidance Added Node.js, Go, Python, and Java sample app code and connection guidance to the CockroachDB Serverless Quickstart, as well as docs explaining the CockroachDB Serverless Architecture, important concepts for planning/managing a Serverless cluster (e.g., request units, cluster scaling), and how to run bulk operations on CockroachDB Dedicated and Serverless clusters.
    Docs Multi-Region Guidance Added docs on transitioning to the new multi-region SQL abstractions from the legacy zone-configuration-based workflows, and on data domiciling in multi-region clusters.
    Docs Performance Tuning Recipes Added solutions for common performance issues.
    Docs New Developer Tutorials Added tutorials on using Google Cloud Run to deploy a containerized Django application and using the Alembic schema migration module with a simple Python application.
    Docs Changefeed Tuning Guidance Added guidance on tuning changefeeds for high-durability delivery, high throughput, and Kafka sinks.
    Docs Sample App Specifications Added a README with specifications for future sample apps built by external partners or contributors.
    Docs Disk Stall Troubleshooting Added docs explaining the symptoms, causes, and mitigations for disk stalls.
    Docs Network Logging with Fluentd Added an example configuration for network logging with Fluentd.
    YesYes NoNo