Skip to main content
XenonStack

Enterprise Digital Platform

XenonStack Insights CockroachDB Explained: Architecture and Licensing

| Published | Updated

CockroachDB explained: key-value storage, ranges across nodes, Raft replication, consistent distributed SQL

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.

Two-column diagram. Top layers: SQL, transactional, distribution, any node. Bottom layers: replication, Raft quorum, leaseholder, storage.
LayerJobWhy it matters
SQLTranslates client SQL into key-value operationsApplications keep a SQL interface
TransactionalMakes changes to multiple key-value entries atomicMulti-row changes succeed or fail together
DistributionPresents replicated key-value ranges as a single entityData spread across nodes looks like one store
ReplicationCopies ranges across nodes with a consensus algorithm, which also enables consistent readsCopies agree before a write is acknowledged
StorageReads and writes key-value data on diskPersistent, 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 pointWhat the documentation says
Current releasesUnder the CockroachDB Software License from 24.3.0 onward
Enterprise FreeFree of charge for businesses with less than $10M in annual revenue, renewed annually
EnterpriseAllows usage of all CockroachDB features
Single nodeClusters 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?

  1. Write down the failure you must survive: node, rack or whole site.
  2. Check the current licence terms against your company size and use.
  3. Stand up a small local cluster using the current documentation.
  4. Test a write on one node and a read on another, then stop a node.
  5. 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.

Table of Contents

navdeep-singh-gill

Navdeep Singh Gill

Global CEO and Founder of XenonStack

LinkedIn profile

Navdeep Singh Gill is serving as Chief Executive Officer and Product Architect at XenonStack. He holds expertise in building SaaS Platform for Decentralised Big Data management and Governance, AI Marketplace for Operationalising and Scaling. His incredible experience in AI Technologies and Big Data Engineering thrills him to write about different use cases and its approach to solutions.

Get the latest articles in your inbox

Subscribe Now

Interested in solving your challenges with the XenonStack team?
Get Started

Tell us about you and your priorities so we can prepare the right conversation. It takes about 2 minutes.

Please Select your Industry
Banking
Fintech
Payment Providers
Wealth Management
Discrete Manufacturing
Semiconductor
Machinery Manufacturing / Automation
Appliances / Electrical / Electronics
Elevator Manufacturing
Defense & Space Manufacturing
Computers & Electronics / Industrial Machinery
Motor Vehicle Manufacturing
Food and Beverages
Distillery & Wines
Beverages
Shipping
Logistics
Mobility (EV / Public Transport)
Energy & Utilities
Hospitality
Digital Gaming Platforms
SportsTech with AI
Public Safety - Explosives
Public Safety - Firefighting
Public Safety - Surveillance
Public Safety - Others
Media Platforms
City Operations
Airlines & Aviation
Defense Warfare & Drones
Robotics Engineering
Drones Manufacturing
AI Labs for Colleges
AI MSP / Quantum / AGI Institutes
Retail Apparel and Fashion

Continue