Data models

This page enumerates the major persistent data models in CockroachDB. They fall into three categories: catalog descriptors, system tables, and KV-internal records.

Catalog descriptors

User-visible objects (databases, schemas, tables, types, functions, schedules) are represented by descriptors, defined in pkg/sql/catalog/descpb/structured.proto. Major descriptor protos:

• Descriptor — discriminated union (database, schema, table, type, function).
• TableDescriptor — columns, indexes, constraints, partitioning, locality, mutations.
• IndexDescriptor — column IDs, unique/inverted, partitioning, GIN/IVF metadata.
• TypeDescriptor — enums, composite types, region enums.
• SchemaDescriptor — non-public schemas with their own privileges.
• DatabaseDescriptor — multi-region settings, grants, default privileges.
• FunctionDescriptor — UDFs and stored procedures.

Descriptors live at well-known KV keys built by pkg/keys/:

• <tenant>/Table/3/<descID> — the descriptor row in system.descriptor.
• <tenant>/Table/2/<parentID>/<schemaID>/<name> — the namespace entry in system.namespace.

Helpers and validation: pkg/sql/catalog/descpb/, pkg/sql/catalog/tabledesc/, pkg/sql/catalog/dbdesc/, pkg/sql/catalog/typedesc/, pkg/sql/catalog/funcdesc/.

System tables

Defined in pkg/sql/catalog/systemschema/ (table-by-table) and bootstrapped from pkg/sql/catalog/bootstrap/.

Table	Stores
system.descriptor	Catalog descriptors
system.namespace	Name → ID lookup
system.zones	Legacy zone configs (mostly replaced by system.span_configurations)
system.span_configurations	Materialized span configs
system.settings	Cluster settings
system.users	SQL users
system.role_members	Role graph
system.role_options	Per-role options (LOGIN, NOLOGIN, ...)
system.privileges	Synthetic privileges
system.web_sessions	DB Console sessions
system.jobs, system.job_info, system.job_progress	Jobs
system.scheduled_jobs	Schedules
system.lease	SQL descriptor leases
system.eventlog	Administrative events
system.rangelog	Range admin events
system.statement_statistics, system.transaction_statistics	SQL stats
system.statement_diagnostics_requests, _diagnostics	EXPLAIN ANALYZE bundle requests
system.statement_activity, system.transaction_activity	Persisted activity for the DB Console
system.tenant_settings, system.tenant_settings_table	Per-tenant overrides
system.task_payloads	Background task storage
system.protected_ts_meta, system.protected_ts_records	Protected timestamps
system.span_count	Span count for tenant quotas
system.tenants	Per-tenant metadata (host only)
system.replication_*	LDR/PCR replication metadata
system.sqlliveness	SQL liveness sessions
system.sql_instances	SQL pod instances
system.locations	Locality → lat/long mapping
system.ui	DB Console UI state
system.reports/...	Replication / constraint conformance reports
system.migrations	Long-running upgrade migrations
system.region_liveness	Per-region liveness for global tables
system.mvcc_statistics	MVCC GC stats

Tenants get a copy of (most of) these tables under their own KV prefix.

KV-internal records

Beyond user-visible data, the KV layer stores per-replica state at well-known local keys (see pkg/keys/constants.go):

• RangeAppliedState — per-replica applied index, lease applied index, MVCC stats.
• RangeDescriptor — range bounds, replicas, generation.
• RaftHardState, RaftLogEntries — Raft persistent state.
• RangeTombstone — replica GC marker.
• RangeReplicatedLockTable — separated lock keys (replicated write intents).
• RangeUnreplicatedLockTable — unreplicated locks (SELECT FOR UPDATE).
• MVCCRangeKey — Pebble range keys for MVCC tombstones.

Wire-format model

For readers shipping to other nodes:

• kvpb.BatchRequest/BatchResponse — the main RPC payload (pkg/kv/kvpb/api.proto).
• roachpb.RangeDescriptor / Lease — gossiped and embedded in many types.
• kvserverpb.RangeFeedEvent — rangefeed wire events.

Related pages

• systems/sql — descriptor consumers.
• systems/storage — MVCC encoding.
• packages/keys — keyspace layout.
• packages/roachpb — wire types.