# cockroachdb/cockroach architecture

> Architecture diagram of the GitHub repository cockroachdb/cockroach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cockroachdb/cockroach
- Repository: https://github.com/cockroachdb/cockroach
- Video tour (about a minute): https://gitdiagram.com/cockroachdb/cockroach/video

## Overview

CockroachDB is a distributed SQL database: clients submit SQL, which is executed through transactional coordination and a strongly consistent, replicated key-value storage layer. The repository also supports data lifecycle workflows including backup and restore, changefeeds, and cross-cluster replication, with cloud storage integrations and job tracking. The README establishes the product workflow and core capabilities; sampled source confirms selected transaction, Raft, storage, changefeed, cloud-storage, replication, and job behavior. Other subsystem links use documented capabilities and tree paths, not inspected implementation details.

Main entry points: [`pkg/sql`](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql) (SQL execution), [`pkg/kv/kvserver/replica_raftstorage.go`](https://github.com/cockroachdb/cockroach/blob/master/pkg/kv/kvserver/replica_raftstorage.go) (KV replicas), [`pkg/cloud/external_storage.go`](https://github.com/cockroachdb/cockroach/blob/master/pkg/cloud/external_storage.go) (External storage API), [`pkg/kv/kvclient/kvcoord/txn_interceptor_pipeliner.go`](https://github.com/cockroachdb/cockroach/blob/master/pkg/kv/kvclient/kvcoord/txn_interceptor_pipeliner.go) (Transaction pipelining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sql["SQL interface"]
  node_sql_exec["SQL execution"]
  node_sql_cli["Built-in SQL client<br/>[sql_client.go]"]
end

subgraph group_distributed["Distributed transactions"]
  node_txn["Transaction pipelining"]
  node_replica["KV replicas"]
  node_raft["Raft consensus<br/>[storage.go]"]
end

subgraph group_storage["Replicated storage"]
  node_engine[("MVCC engine<br/>[engine.go]")]
end

subgraph group_lifecycle["Data lifecycle"]
  node_backup["Backup and restore"]
  node_changefeed["Changefeeds"]
  node_sink["Cloud sink"]
  node_replication["Stream ingestion"]
end

subgraph group_operations["Operations and integrations"]
  node_jobs[("Job tracking")]
  node_external_storage["External storage API"]
  node_s3["Amazon S3<br/>[s3_storage.go]"]
  node_tenant_server["Tenant server lifecycle"]
end

node_client(("SQL client"))
node_cloud_providers(("Cloud providers"))

node_client -->|"submits SQL"| node_sql_exec
node_sql_cli -->|"sends SQL"| node_sql_exec
node_sql_exec -->|"coordinates transactions"| node_txn
node_txn -->|"sends KV batches"| node_replica
node_replica -->|"uses consensus storage"| node_raft
node_replica -->|"reads and writes"| node_engine
node_backup -->|"stores backup data"| node_external_storage
node_changefeed -->|"dispatches events"| node_sink
node_sink -->|"writes files"| node_external_storage
node_replication -->|"reads job state"| node_jobs
node_external_storage -.->|"selects backend"| node_s3
node_cloud_providers -.->|"provides storage"| node_s3
node_tenant_server -->|"starts tenant service"| node_sql_exec

click node_sql_exec "https://github.com/cockroachdb/cockroach/tree/master/pkg/sql"
click node_sql_cli "https://github.com/cockroachdb/cockroach/blob/master/pkg/cli/sql_client.go"
click node_txn "https://github.com/cockroachdb/cockroach/blob/master/pkg/kv/kvclient/kvcoord/txn_interceptor_pipeliner.go"
click node_replica "https://github.com/cockroachdb/cockroach/blob/master/pkg/kv/kvserver/replica_raftstorage.go"
click node_raft "https://github.com/cockroachdb/cockroach/blob/master/pkg/raft/storage.go"
click node_engine "https://github.com/cockroachdb/cockroach/blob/master/pkg/storage/engine.go"
click node_backup "https://github.com/cockroachdb/cockroach/tree/master/pkg/backup"
click node_changefeed "https://github.com/cockroachdb/cockroach/tree/master/pkg/ccl/changefeedccl"
click node_sink "https://github.com/cockroachdb/cockroach/blob/master/pkg/ccl/changefeedccl/sink_cloudstorage.go"
click node_replication "https://github.com/cockroachdb/cockroach/blob/master/pkg/crosscluster/physical/stream_ingest_manager.go"
click node_jobs "https://github.com/cockroachdb/cockroach/blob/master/pkg/jobs/job_info_storage.go"
click node_external_storage "https://github.com/cockroachdb/cockroach/blob/master/pkg/cloud/external_storage.go"
click node_s3 "https://github.com/cockroachdb/cockroach/blob/master/pkg/cloud/amazon/s3_storage.go"
click node_tenant_server "https://github.com/cockroachdb/cockroach/blob/master/pkg/server/server_controller_channel_orchestrator.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sql_exec,node_sql_cli,node_client toneBlue
class node_txn,node_replica,node_raft toneAmber
class node_engine toneMint
class node_backup,node_changefeed,node_sink,node_replication toneRose
class node_jobs,node_external_storage,node_s3,node_tenant_server,node_cloud_providers toneIndigo
```

## Components

### SQL interface

- [SQL execution](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql): `pkg/sql`
- [Built-in SQL client](https://github.com/cockroachdb/cockroach/blob/master/pkg/cli/sql_client.go): `pkg/cli/sql_client.go`

### Distributed transactions

- [Transaction pipelining](https://github.com/cockroachdb/cockroach/blob/master/pkg/kv/kvclient/kvcoord/txn_interceptor_pipeliner.go): `pkg/kv/kvclient/kvcoord/txn_interceptor_pipeliner.go`
- [KV replicas](https://github.com/cockroachdb/cockroach/blob/master/pkg/kv/kvserver/replica_raftstorage.go): `pkg/kv/kvserver/replica_raftstorage.go`
- [Raft consensus](https://github.com/cockroachdb/cockroach/blob/master/pkg/raft/storage.go): `pkg/raft/storage.go`

### Replicated storage

- [MVCC engine](https://github.com/cockroachdb/cockroach/blob/master/pkg/storage/engine.go): `pkg/storage/engine.go`

### Data lifecycle

- [Backup and restore](https://github.com/cockroachdb/cockroach/tree/master/pkg/backup): `pkg/backup`
- [Changefeeds](https://github.com/cockroachdb/cockroach/tree/master/pkg/ccl/changefeedccl): `pkg/ccl/changefeedccl`
- [Cloud sink](https://github.com/cockroachdb/cockroach/blob/master/pkg/ccl/changefeedccl/sink_cloudstorage.go): `pkg/ccl/changefeedccl/sink_cloudstorage.go`
- [Stream ingestion](https://github.com/cockroachdb/cockroach/blob/master/pkg/crosscluster/physical/stream_ingest_manager.go): `pkg/crosscluster/physical/stream_ingest_manager.go`

### Operations and integrations

- [Job tracking](https://github.com/cockroachdb/cockroach/blob/master/pkg/jobs/job_info_storage.go): `pkg/jobs/job_info_storage.go`
- [External storage API](https://github.com/cockroachdb/cockroach/blob/master/pkg/cloud/external_storage.go): `pkg/cloud/external_storage.go`
- [Amazon S3](https://github.com/cockroachdb/cockroach/blob/master/pkg/cloud/amazon/s3_storage.go): `pkg/cloud/amazon/s3_storage.go`
- [Tenant server lifecycle](https://github.com/cockroachdb/cockroach/blob/master/pkg/server/server_controller_channel_orchestrator.go): `pkg/server/server_controller_channel_orchestrator.go`

### Other components

- **SQL client**
- **Cloud providers**

## Connections

- SQL client → SQL execution: submits SQL
- Built-in SQL client → SQL execution: sends SQL
- SQL execution → Transaction pipelining: coordinates transactions
- Transaction pipelining → KV replicas: sends KV batches
- KV replicas → Raft consensus: uses consensus storage
- KV replicas → MVCC engine: reads and writes
- Backup and restore → External storage API: stores backup data
- Changefeeds → Cloud sink: dispatches events
- Cloud sink → External storage API: writes files
- Stream ingestion → Job tracking: reads job state
- External storage API → Amazon S3: selects backend
- Cloud providers → Amazon S3: provides storage
- Tenant server lifecycle → SQL execution: starts tenant service