Glossary

This page defines terms that you will encounter throughout the documentation.

Database terms

Consistency

The requirement that a transaction must change affected data only in allowed ways. CockroachDB uses "consistency" in both the sense of ACID semantics and the CAP theorem, albeit less formally than either definition.

Isolation

The degree to which a transaction may be affected by other transactions running at the same time. CockroachDB provides the SERIALIZABLE isolation level, which is the highest possible and guarantees that every committed transaction has the same result as if each transaction were run one at a time.

Consensus

The process of reaching agreement on whether a transaction is committed or aborted. CockroachDB uses the Raft consensus protocol. In CockroachDB, when a range receives a write, a quorum of nodes containing replicas of the range acknowledge the write. This means your data is safely stored and a majority of nodes agree on the database's current state, even if some of the nodes are offline.

When a write does not achieve consensus, forward progress halts to maintain consistency within the cluster.

Replication

The process of creating and distributing copies of data, as well as ensuring that those copies remain consistent. CockroachDB requires all writes to propagate to a quorum of copies of the data before being considered committed. This ensures the consistency of your data.

Transaction

A set of operations performed on a database that satisfy the requirements of ACID semantics. This is a crucial feature for a consistent system to ensure developers can trust the data in their database. For more information about how transactions work in CockroachDB, see Transaction Layer.

Contention

A state of conflict that occurs when a transaction is unable to complete due to another concurrent or recent transaction attempting to write to the same data. When CockroachDB experiences transaction contention, it will automatically attempt to retry the failed transaction without involving the client (i.e., silently). If the automatic retry is not possible or fails, a transaction retry error is emitted to the client. The client application can be configured to retry the transaction after receiving such an error, and to minimize transaction retry errors in the first place where possible.

Multi-active availability

A consensus-based notion of high availability that lets each node in the cluster handle reads and writes for a subset of the stored data (on a per-range basis). This is in contrast to active-passive replication, in which the active node receives 100% of request traffic, and active-active replication, in which all nodes accept requests but typically cannot guarantee that reads are both up-to-date and fast.

User

A SQL user is an identity capable of executing SQL statements and performing other cluster actions against CockroachDB clusters. SQL users must authenticate with an option permitted on the cluster (username/password, single sign-on (SSO), or certificate). Note that a SQL/cluster user is distinct from a CockroachDB Cloud organization user.

CockroachDB architecture terms

Cluster

A group of interconnected CockroachDB nodes that function as a single distributed SQL database server. Nodes collaboratively organize transactions, and rebalance workload and data storage to optimize performance and fault-tolerance.

Each cluster has its own authorization hierarchy, meaning that users and roles must be defined on that specific cluster.

A CockroachDB cluster can be run in CockroachDB Cloud, within a customer Organization, or can be self-hosted.

Node

An individual instance of CockroachDB. One or more nodes form a cluster.

Range

CockroachDB stores all user data (tables, indexes, etc.) and almost all system data in a sorted map of key-value pairs. This keyspace is divided into contiguous chunks called ranges, such that every key is found in one range.

From a SQL perspective, a table and its secondary indexes initially map to a single range, where each key-value pair in the range represents a single row in the table (also called the primary index because the table is sorted by the primary key) or a single row in a secondary index. As soon as the size of a range reaches the default range size, it is split into two ranges. This process continues for these new ranges as the table and its indexes continue growing.

Replica

A copy of a range stored on a node. By default, there are three replicas of each range on different nodes.

Leaseholder

The replica that holds the "range lease." This replica receives and coordinates all read and write requests for the range.

For most types of tables and queries, the leaseholder is the only replica that can serve consistent reads (reads that return "the latest" data).

Raft protocol

The consensus protocol employed in CockroachDB that ensures that your data is safely stored on multiple nodes and that those nodes agree on the current state even if some of them are temporarily disconnected.

Raft leader

For each range, the replica that is the "leader" for write requests. The leader uses the Raft protocol to ensure that a majority of replicas (the leader and enough followers) agree, based on their Raft logs, before committing the write. The Raft leader is almost always the same replica as the leaseholder.

Raft log

A time-ordered log of writes to a range that its replicas have agreed on. This log exists on-disk with each replica and is the range's source of truth for consistent replication.

For more information on CockroachDB architecture, see Architecture Overview.

CockroachDB deployment terms

Single-tenant

A type of CockroachDB deployment where a single customer uses the database cluster.

multi-tenant

A type of CockroachDB deployment where multiple customers share a single storage cluster. Each customer sees a virtual CockroachDB cluster. Data in each virtual cluster is isolated and is invisible to other customers.

Region

A logical identification of how nodes and data are clustered around geographical locations. A cluster region is the set of locations where cluster nodes are running. A database region is the subset of cluster regions database data should be restricted to.

Availability zone

A part of a data center that is considered to form a unit with regards to failures and fault tolerance. There can be multiple nodes in a single availability zone, however Cockroach Labs recommends that you to place different replicas of your data in different availability zones.

CockroachDB Serverless

A fully managed, multi-tenant CockroachDB deployment, in a single region and cloud (AWS or GCP). Delivers an instant, autoscaling database and offers a generous free tier and consumption based billing once free limits are exceeded. Billed and scaled according to the resources consumed.

CockroachDB Dedicated

A fully managed, single tenant CockroachDB deployment in a single region or multi-region cloud (AWS or GCP), billed according to the resources provisioned for the cluster. This service tier offers advanced security features.

CockroachDB Self-Hosted

A full featured, self-managed CockroachDB deployment.

For more information on deployment options and guidelines on how to choose a deployment option, see How to Choose a Deployment Option.

CockroachDB Cloud terms

Organization

In CockroachDB Cloud, an organization corresponds to an authorization hierarchy rooted linked to a billing account. The admins of the organization can add or invite other users to it.

To learn more, refer to Overview of the CockroachDB Cloud two-level authorization model.

User

A CockroachDB Cloud user can belong to one or more organizations.

CockroachDB Serverless cluster

A CockroachDB Cloud cluster deployed on request for a specific customer in shared network and compute infrastructure.

CockroachDB Dedicated cluster

A CockroachDB Cloud cluster deployed on request for a specific customer, in a cloud provider's network and compute infrastructure dedicated to that customer, which can be distributed over multiple regions for added disaster-resilience. In addition to infrastructure isolation, dedicated clusters can be customized with advanced network, identity-management, and encryption-related security features.

Request Unit (RU)

Represents the compute and I/O resources used by a query. All database operations in CockroachDB Serverless cost a certain amount of RUs depending on the resources used. For example, a "small read" might cost 2 RUs, and a "large read" such as a full table scan with indexes could cost a large number of RUs. You can see how many Request Units your cluster has used on the Cluster Overview page.

Resource limits

The maximum amounts of storage and RUs a CockroachDB Serverless cluster can use in a particular billing period. The amount you are billed is based on the actual resources the cluster used during that billing period.

Storage

Disk space for permanently storing data over time. All data in CockroachDB Serverless is automatically replicated three times and distributed across Availability Zones to survive outages. Storage is measured in units of GiB-months, which is the amount of data stored multiplied by how long it was stored. Storing 10 GiB for a month and storing 1 GiB for 10 months are both 10 GiB-months. The storage you see in the Cluster Overview page is the amount of data before considering the replication multiplier.

For more information on CockroachDB Cloud, see CockroachDB Cloud Architecture.