Key takeaway
- CockroachDB explained: its five-layer architecture, ranges and Raft replication, how it scales and survives failure, and how its licensing has changed.
CockroachDB is a distributed SQL database that stores data as a sorted key-value map, splits that map into ranges, and keeps each range consistent across several nodes using the Raft consensus protocol. Applications talk to it in SQL, and any node can accept the request.
This guide is for architects, database engineers and platform teams comparing distributed SQL options. It explains how CockroachDB is built, how it scales and survives failure, what changed in its licensing, how it fits with other types of databases, and what to test first. Version numbers and install commands change often, so it points to the current documentation for them.
What is CockroachDB?
According to the CockroachDB architecture overview, CockroachDB converts clients' SQL statements into key-value data, and all user data and most system data sits in one sorted key-value map. The keyspace is divided into contiguous chunks called ranges, so every key is found in exactly one range, and when a range grows large enough it splits in two. Nodes behave symmetrically: you can send SQL requests to any node, and if a node cannot serve a request directly it forwards it to the node that can. That symmetry is why it is straightforward to place a load balancer in front of a cluster.
How is CockroachDB built?
The same page describes five layers, each treating the layers below it as a black box.
| Layer | Job | Why it matters |
|---|---|---|
| SQL | Translates client SQL into key-value operations | Applications keep a SQL interface |
| Transactional | Makes changes to multiple key-value entries atomic | Multi-row changes succeed or fail together |
| Distribution | Presents replicated key-value ranges as a single entity | Data spread across nodes looks like one store |
| Replication | Copies ranges across nodes with a consensus algorithm, which also enables consistent reads | Copies agree before a write is acknowledged |
| Storage | Reads and writes key-value data on disk | Persistent, local data on each node |
How does CockroachDB replicate data and survive failure?
The overview says each range is replicated, by default, to at least three nodes. Raft is the consensus protocol: a write is committed only after a quorum of the nodes holding replicas of the range acknowledge it. If consensus cannot be reached, progress stops so the data stays consistent. One replica of each range, the leaseholder, coordinates reads and writes for that range, and the Raft leader is normally the same replica.
The practical reading is that a cluster keeps working when a minority of a range's replicas are unavailable, because a majority can still agree. Where you place replicas decides what failure you can tolerate: different servers cover a server failure, different racks cover a rack failure, and different data centres cover a site outage. Placing replicas far apart adds network delay to every write that needs agreement, so round-trip latency between locations affects performance.
How does CockroachDB scale?
Scaling works by adding nodes and letting ranges spread. As data grows, ranges split, and the cluster moves replicas to nodes that have capacity. Because every node can accept SQL requests, new nodes add both storage and capacity to handle traffic. Treat the exact range size and rebalancing settings as configuration to read from the documentation for your version, rather than as fixed numbers.
Is CockroachDB open source?
Older guides describe it as open source. The CockroachDB licensing FAQs now say releases from 24.3.0 onward, plus patch releases of 23.1 through 24.2 from that date, are made available under the CockroachDB Software License. The page mentions an earlier licence called CockroachDB Core and does not call the current licence open source, so read the terms before you plan around them.
| Licence point | What the documentation says |
|---|---|
| Current releases | Under the CockroachDB Software License from 24.3.0 onward |
| Enterprise Free | Free of charge for businesses with less than $10M in annual revenue, renewed annually |
| Enterprise | Allows usage of all CockroachDB features |
| Single node | Clusters started with the single-node or demo commands need no licence key |
Check the page for conditions such as telemetry and affiliate revenue before you rely on a free tier.
How do you get started and test it?
Early guides to CockroachDB showed a binary download for version 2.0.6, an insecure local three-node cluster and a manual stop test. That release is long out of date, since the vendor documentation now covers version 25.3, so use the current installation and local cluster pages. The shape of the exercise still holds: start a small cluster, create a table, write through one node, read through another, stop one node and confirm the data stays available. Add the database testing and performance tracing practices you already use, and compare the result with a graph database if your data is heavily connected.
How do AI agents change database choices?
Agents read and write operational data at machine speed, and an agent that acts on stale or inconsistent data can repeat a mistake many times. Consistent reads and atomic multi-row changes matter more when a system, not a person, is the client. Governed context sits above the database: ElixirData, XenonStack's Context OS, is where the meaning, policy and lineage of that data can be managed. For analytics workloads on top of operational data, see the big data and predictive analytics solution guide.
What should you do first?
- Write down the failure you must survive: node, rack or whole site.
- Check the current licence terms against your company size and use.
- Stand up a small local cluster using the current documentation.
- Test a write on one node and a read on another, then stop a node.
- Measure latency with replicas placed where you intend to run them.
To map one decision your agents make, and the data and policy it depends on, book a Context Workshop. See what happens in the workshop.
Frequently asked questions
What is CockroachDB used for?
It is a distributed SQL database. It stores data across several nodes and keeps copies consistent, so applications can use SQL against a cluster rather than a single server.
How many copies of the data does CockroachDB keep?
The architecture overview says each range is replicated to at least three nodes by default.
What is Raft in CockroachDB?
Raft is the consensus protocol. A write is committed only after a quorum of the nodes holding replicas of the range acknowledge it.
Can I send queries to any node?
Yes. The documentation says you can send SQL requests to any node, and a node that cannot serve a request directly forwards it to the node that can.
Is CockroachDB still open source?
The licensing FAQs say releases from 24.3.0 onward are made available under the CockroachDB Software License. Read the current terms before you plan around them.
Ready to put AI agents to work? See an ElixirClaw demo: the agentic OS to build, orchestrate and govern AI agents across your enterprise systems.
Explore the XenonStack platform family: ElixirData · ElixirClaw · ElixirHub · NexaStack · MetaSecure · Neural AI · AgentGRC · AgentSRE · AgentAnalyst · AgentInstruct · AgentRAI · AgentScrum · AgentSearch · AgentForce · AI Aviator · SAIF Aviator · CohortIQ · XenonStack AI · XenonStack UAE