CockroachDB: Distributed SQL for Surviving Node and Datacenter Failures

What CockroachDB Is and Who Should Reach for It

CockroachDB is a distributed SQL database built on a transactional, strongly-consistent key-value store. The README makes four claims about it: it scales horizontally, it survives disk, machine, rack and even datacenter failures with minimal latency disruption and no manual intervention, it supports strongly-consistent ACID transactions, and it exposes a familiar SQL API. Those four properties are the whole pitch, and they define the audience.

The project is aimed at teams building what the README calls modern, data-intensive applications, particularly ones where a single database node failing is not an acceptable outcome. If your application can tolerate a maintenance window, or if a single PostgreSQL instance comfortably handles your write volume, the distributed machinery here is cost without benefit. The architecture only pays off when you genuinely need more than one machine to hold the same data and stay consistent.

One thing the README does not do is quantify anything. There are no latency figures, no throughput numbers, no guidance on cluster sizing. That is a documentation gap, not a flaw in the database, but it means capacity planning has to come from the linked user documentation or from your own load testing rather than from the repository.

The Mechanism: PostgreSQL Wire Protocol over a Distributed Key-Value Store

The design is layered. At the bottom is a transactional, strongly-consistent key-value store. On top of that sits the SQL layer, and on top of that sits a network interface that speaks the PostgreSQL wire protocol. The README states plainly: CockroachDB supports the PostgreSQL wire protocol, so you can use any available PostgreSQL client drivers to connect from various languages.

That single sentence explains most of the adoption story. You do not install a CockroachDB-specific driver to get started. Your existing PostgreSQL driver, and by extension your ORM, can connect. The README links to a page of recommended drivers that the project has tested and to tutorials covering supported ORMs, which is where the compatibility caveats live. Treat the wire-protocol claim as a starting point for evaluation, not a guarantee that every PostgreSQL feature behaves identically.

The repository layout reflects the layering. The top level contains pkg/, which holds the Go source, along with c-deps/ for C dependencies and build/ for the build system. The build itself uses Bazel: the top level carries BUILD.bazel, WORKSPACE, DEPS.bzl, .bazelrc and .bazelversion, with a GNUmakefile as the conventional entry point. The module is declared in go.mod as github.com/cockroachdb/cockroach and requires Go 1.26.2, so anyone building from source is committing to a recent Go toolchain.

Installing CockroachDB and Running a First Local Cluster

The README gives two installation routes: a pre-built executable, or building it from source. It links out for both rather than embedding the steps, so there are no install commands to reproduce here. Start with the pre-built executable unless you have a reason to compile; the build-from-source path is documented on a separate wiki page and, per go.mod, needs Go 1.26.2.

Once the binary is on your PATH, the README's second step is to start a local cluster and connect to it with the built-in SQL client. It links to a page titled start-a-local-cluster and to a page on using the built-in SQL client, which are the two documents to follow for the exact invocations. The README also links to demo material covering data replication, automatic rebalancing, and fault tolerance and recovery, which is the sequence to follow if you want to see the distributed behaviour rather than just a working prompt.

What you should expect at the end of that sequence is a local cluster you can query over SQL, and then, per the README's fourth step, an application connecting to it through a PostgreSQL-compatible driver or ORM. The README's fifth step is where the distributed properties become visible, because replication and rebalancing are the features a single-node PostgreSQL instance does not have.

If you would rather not run a cluster at all, the README offers a second path: CockroachCloud, described as running CockroachDB for you. The README links to a separate CockroachCloud quickstart, and that is a genuinely different product decision, not just a hosting choice.

Where CockroachDB Is the Wrong Tool

The clearest limitation is structural rather than a bug. Strong consistency across multiple nodes is achieved through coordination, and coordination costs latency on writes compared with a single-node database that never has to reach consensus with anyone. The README does not discuss this trade-off at all, which is a notable omission for a page aimed at people deciding whether to adopt.

The second limitation is operational weight. A distributed database is a system you run, not a file you point an application at. Even the local development story involves starting a node process and connecting a client to it. Teams without the appetite to operate a cluster should look hard at the CockroachCloud path the README offers, or at not using CockroachDB at all.

The third is licensing, covered in its own section below, and it is the one that can disqualify the project outright for some organisations.

Finally, there is a documentation boundary worth naming. The README does not document rollback, does not document upgrade procedures, and does not document backup or restore. It links to a troubleshooting overview for common errors, cluster setup problems and SQL query behaviour, but the operational runbooks live outside the repository. If you are evaluating CockroachDB from the repository alone, you are evaluating the wrong artefact.

CockroachDB Compared with a Single-Node PostgreSQL Deployment

The honest comparison is not CockroachDB versus some other distributed SQL system. It is CockroachDB versus the PostgreSQL instance you already run.

The difference in approach is the consensus layer. PostgreSQL on one machine gives you strong consistency for free, because there is only one copy of the data and nothing to agree with. CockroachDB keeps multiple copies and makes them agree, which is what buys survival of disk, machine, rack and datacenter failures. The README's claim of no manual intervention is the payoff: failover is a property of the system rather than a runbook someone executes at 3am.

The cost is everything that comes with replication. More nodes to monitor, more network paths that can degrade, and write latency that reflects coordination rather than local disk speed. The README links to a comparison page for how the project stacks up against other databases; read it knowing it is the vendor's account, and pair it with your own numbers.

The practical dividing line: if your availability requirement can be met by a primary with a standby and a short failover window, PostgreSQL is simpler and you already know how to run it. If a datacenter going dark must not take your write path with it, the replication is the point.

Licence Terms and the Maintenance Question

The licensing situation is the part of the README most likely to change your decision, and it is stated precisely. All versions released on or after November 18, 2024, specifically major version series v24.3 and later, plus patch fixes for v23.1.29 and above, v23.2.16 and above, v24.1.7 and above, and v24.2.5 and above, are published under the CockroachDB Software License. Source code in a given file is under that licence and copyright belongs to The Cockroach Authors unless a file or a LICENSE or README in the same or a parent directory says otherwise.

The repository's licence field does not resolve to a standard SPDX identifier, which is consistent with a custom licence. That means automated licence scanners may flag the project or fail to classify it, and your legal review cannot be replaced by a tool's output. This article cannot tell you whether the CSL is acceptable for your use; that depends on how you intend to deploy and redistribute, and it is a question for your own counsel.

On maintenance, the repository is not archived, so it has not been formally retired. No last-push date is available here, so no claim about how actively the project is developed can be made. The repository does show ongoing structure: a TEAMS.yaml file, a CONTRIBUTING.md, a CODE_OF_CONDUCT.md, a good first issue label used to tag work for new external contributors, and a public mailing list at [email protected] where engineering discussions take place. Those are signals of an organised project, not evidence of release cadence. Check the commit history and release tags yourself before you depend on a particular version.

Editorial conclusion

Adopt CockroachDB if you need strongly-consistent ACID transactions across multiple machines or datacenters and your application already speaks the PostgreSQL wire protocol, so existing drivers and ORMs can connect with little change. Do not adopt it if a single-node PostgreSQL instance meets your throughput and availability needs, because the distributed consensus layer adds operational surface you would otherwise not carry. Before committing, verify two things: which licence applies to the exact version you plan to run (the README states that v24.3 and later, plus specific patch releases of v23.1, v23.2, v24.1 and v24.2, ship under the CockroachDB Software License), and whether your deployment target is a self-managed cluster or CockroachCloud, since the README points to separate quickstarts for each.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository