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:
- Read the v21.2 blog post.
- Join us for a live demo and Q&A session on Tuesday, December 7. Sign up for the North America session or the EMEA session. We hope to see you there.
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.
$ docker pull cockroachdb/cockroach:v21.2.0
- Get a free v21.2 cluster on CockroachDB Serverless (beta).
- Learn about recent updates to CockroachDB Cloud in the CockroachDB Cloud Release Notes.
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.
- Recovery and I/O
- Database operations
- Backward-incompatible changes
- Known limitations
|Enterprise||Multi-region observability||You can now surface region information by using the
|Enterprise||Restricted and default placement||You can now use the
|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
|Core||Privilege inheritance||CockroachDB's model for inheritance of privileges that cascade from schema objects now matches PostgreSQL. Added support for
|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
|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
|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
|Core||Contention views||You can now use pre-built contention views in
Recovery and I/O
|Enterprise||Webhook changefeed sink||You can now stream individual changefeed messages as webhook messages to a newly supported
|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
|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:
|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
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,
- The deprecated cluster setting
cloudstorage.gs.default.keyhas been removed, and the behavior of the
AUTHparameter in Google Cloud Storage
IMPORTURIs has been changed. The default behavior is now that of
AUTH=specified, which uses the credentials passed in the
CREDENTIALSparameter, and the previous default behavior of using the node's implicit access (via its machine account or role) now requires explicitly passing
- Switched types from
"char"for compatibility with PostgreSQL in the following columns:
kv.follower_read.target_multiplesettings 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_slacksetting 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.propagation_slack, which defaults to 4.2s (instead of the previous default of 4.8s).
- Because the
SELECTdatabase privilege is being deprecated, CockroachDB now additionally checks for the
CONNECTprivilege on the database to allow for backing up the database. Existing users with
SELECTon the database can still back up the database, but it is now recommended to
CONNECTon the database.
IMPORT TABLEwill be deprecated in v21.2 and removed in a future release. Users should create a table using
CREATE TABLEand then
IMPORT INTOthe newly created table.
DELETEon databases is being deprecated. The syntax is still supported, but is automatically converted to the equivalent
ALTER DEFAULT PRIVILEGES FOR ALL ROLEScommand. The user is given a notice that the privilege is incompatible and automatically being converted to an
ALTER DEFAULT PRIVILEGE FOR ALL ROLEScommand.
For information about new and unresolved limitations in CockroachDB v21.2, with suggested workarounds where applicable, see Known Limitations.
|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
|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.|