What's New in v19.1.0

April 30, 2019

With the release of CockroachDB v19.1, we’ve made a variety of security, performance, and usability improvements. A few highlights:

Check out a comprehensive summary of the most significant user-facing changes and then upgrade to CockroachDB v19.1. You can also read more about these changes in the v19.1 blog post.


Cockroach Labs has discovered a bug relating to incremental backups, for CockroachDB v19.1.0 - v19.1.11. 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.

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

Get future release notes emailed to you:


Docker image

$ docker pull cockroachdb/cockroach:v19.1.0


This section summarizes the most significant user-facing changes in v19.1.0. For a complete list of features and changes, including bug fixes and performance improvements, see the release notes for previous testing releases.

Managed service offering

Feature Description
Managed CockroachDB Console Paid managed CockroachDB customers can now sign into their organization's account, view the connection string details, add and edit their list of allowed IPs on the management console.

Enterprise features

These features require an enterprise license. Register for a 30-day trial license here.

Feature Description
Encryption at Rest Encryption at rest provides transparent encryption of a node's data on the local disk. This feature was introduced as experimental in v2.1 and is now ready for production use.
GSSAPI with Kerberos Authentication CockroachDB now supports the Generic Security Services API (GSSAPI) with Kerberos authentication, which lets you use an external enterprise directory system that supports Kerberos, such as Active Directory.
Follower Reads This feature reduces read latencies by allowing queries to perform historical reads of the closest replica of a given piece of data rather than reading from the more distant "leaseholder" replica. To enable follower reads on a query, use the experimental_follower_read_timestamp() built-in function in conjunction with the AS OF SYSTEM TIME clause.
Prefer Closest Secondary Index Given multiple identical indexes that have different locality constraints using replication zones, the cost-based optimizer will now prefer the index that is closest to the gateway node that is planning the query. In a properly configured geo-distributed cluster, this can lead to performance improvements due to improved data locality and reduced network traffic. This feature enables scenarios where reference data such as a table of postal codes can be replicated to different regions, and queries will use the copy in the same region.
Change Data Capture CDC in v19.1 includes many improvements to production-readiness. CHANGEFEEDs delivering data to Apache Kafka/Confluent Platform are now fully supported, and a new cloud storage sink allows CHANGEFEEDs to deliver table updates as JSON files to endpoints like Google Storage or AWS S3. A new push-based internal data delivery mechanism called rangefeeds helps deliver data with increased reliability and lower latency.

Core features

These features are freely available in the core version and do not require an enterprise license.

Feature Description
Load-Based Splitting CockroachDB now automatically splits frequently accessed keys into smaller ranges to optimize your cluster’s performance.
Query Optimizer Hints The cost-based optimizer now supports hint syntax to force the use of merge, hash, or lookup joins. This let you override the cost-based optimizer's join algorithm selection in cases where you have information about your data that the cost-based optimizer does not yet have.
Correlated Subqueries Most correlated subqueries are now decorrelated and processed by the cost-based-optimizer. For those that cannot be decorrelated, CockroachDB now emits an "apply" operator that executes a sub-plan for every row in its input. This allows CockroachDB to execute a large number of additional correlated subqueries that were not able to be executed in v2.1.
Core Changefeeds CockroachDB now offers a non-enterprise version of change data capture, via the EXPERIMENTAL CHANGEFEED FOR statement, to consume table updates over a streaming Postgres connection.
Cost-Based Optimizer The cost-based optimizer now supports almost all read-only queries (except window functions) and almost all mutations (e.g., CREATE TABLE AS, INSERT, UPDATE, UPSERT, DELETE). In addition, the cost-based optimizer now reorders up to 4 joins in a query to attempt to find the most performant ordering (via the new reorder_joins_limit session variable) and takes advantage of automatically generated table statistics without impacting foreground traffic. Note that statistics are created by default on all indexed columns when a user upgrades to this version. Finally, a query plan cache now saves a portion of the planning time for frequent queries used in the cost-based optimizer.
Logical Plans in the Admin UI The Statement Details page in the Admin UI now shows the ordered steps CockroachDB will take to execute a query (i.e., the EXPLAIN output). This helps you identify bottlenecks caused by how queries are planned by our heuristic and cost-based optimizers.
Cascading Replication Zones Newly created replication zones will now inherit empty values from their parent. For example, if the replication zone for a table is not explicitly set with num_replicas, it will inherit that value from its direct parent, whether that's the .default replication zone from the entire cluster or the replication zone for the database containing the table.
Custom Savepoints CockroachDB now supports custom naming of SAVEPOINTs for compatibility with ORMs and other third-party tools.

Backward-incompatible changes

Before upgrading to CockroachDB v19.1.0, be sure to review the following backward-incompatible changes and adjust your application as necessary.

  • CockroachDB no longer supports the B'abcde' notation to express byte array literals. This notation now expresses bit array literals like in PostgreSQL. The b'...' notation remains for byte array literals.

  • The normalized results of certain timestamp + duration operations involving year or month durations have been adjusted to agree with the values returned by PostgreSQL.

  • The CHANGEFEED experimental-avro option has been renamed experimental_avro.

  • Timezone abbreviations, such as EST, are no longer allowed when parsing or converting to a date/time type. Previously, an abbreviation would be accepted if it were an alias for the session's timezone.

  • The way composite foreign key matches are evaluated has changed to match the Postgres behavior. If your schema currently uses composite keys, it may require updates, since this change may affect your foreign key constraints and cascading behavior. For more details and guidance, see this note.

  • Mutation statements like UPDATE, INSERT, and DELETE no longer attempt to guarantee mutation or output ordering when an ORDER BY clause is present. It is now an error to use ORDER BY without LIMIT with the UPDATE statement.

Known limitations

For information about limitations we've identified in CockroachDB v19.1, with suggested workarounds where applicable, see Known Limitations.


Topic Description
Geo-Partitioning Added a video and tutorial on using geo-partitioning to get very fast reads and writes in a broadly distributed cluster.
Security Added an overview of CockroachDB security, with a dedicated page on authentication, encryption, authorization, and SQL audit logging.
Troubleshooting Added much more guidance on troubleshooting cluster setup and troubleshooting SQL behavior.
Architecture Added the Life of a Distributed Transaction, which details the path that a query takes through CockroachDB's architecture, starting with a SQL client and progressing all the way to RocksDB (and then back out again). Also added Reads and Writes in CockroachDB, which explains how reads and writes are affected by the replicated and distributed nature of data in CockroachDB.
Production Guidance Expanded the Production Checklist with more current hardware recommendations and additional guidance on storage, file systems, and clock synchronization. Also added a library of common Cluster Topology Patterns.
ORMs Expanded the SQLAlchemy tutorial to provide code for transaction retries and best practices for using SQLAlchemy with CockroachDB.
YesYes NoNo