Multi-tenant

A CockroachDB cluster can host many SQL tenants over a shared KV layer. Tenants are isolated namespaces with their own catalog, jobs, and SQL stats; they share storage, gossip, and the system tenant's KV store.

Components

• pkg/multitenant/ — base types: tenantID, capabilities.
• pkg/multitenant/tenantcapabilities/ — fine-grained per-tenant capability gates.
• pkg/multitenant/tenantcostmodel/ — per-tenant resource accounting.
• pkg/multitenant/tenantcostserver/ and pkg/multitenant/tenantcostclient/ — RU (request-unit) consumption protocol.
• pkg/ccl/multitenantccl/ — tenant administration (create/destroy/inspect).
• pkg/server/server_controller*.go — host process that runs many SQL tenants.
• pkg/server/tenant.go — the per-tenant SQL server.
• pkg/kv/kvclient/kvtenant/ — tenant-side KV client that proxies through the host.

How a tenant runs

graph LR
  Host["host process"] --> Controller["serverController"]
  Controller --> T1["tenant 2 SQLServer"]
  Controller --> T2["tenant 3 SQLServer"]
  T1 -->|proxied KV| KVHost["host kv layer"]
  T2 -->|proxied KV| KVHost
  KVHost -->|MVCC over Pebble| Engine

Each tenant has:

• A unique tenant ID (system tenant is ID 1).
• A KV namespace prefix (/Tenant/<id>/...).
• Its own system.* tables under that prefix.
• A capability set controlling which host APIs it can call.

Isolation

CockroachDB enforces tenant isolation at multiple layers:

• Wire — pkg/rpc/auth_tenant.go only accepts requests for the tenant ID encoded in the certificate.
• Capabilities — pkg/multitenant/tenantcapabilities/ mediates host RPCs: a tenant cannot start a backup that touches another tenant's keys.
• Cost — tenantcostclient accumulates RU consumption that the host can throttle and bill.
• Storage — every range is assigned to a tenant in its descriptor. Out-of-tenant access is rejected at the kvserver entry.

Tenant lifecycle

The cockroach mt CLI subtree (pkg/cli/mt_*.go) and the SQL CREATE/DROP TENANT statements drive the lifecycle. A tenant boot copies bootstrap data into its KV prefix, registers with the host's tenantsettingswatcher, and starts its SQL server.

SQLProxy

pkg/ccl/sqlproxyccl/ is a stand-alone TCP proxy used by CockroachDB Serverless. It terminates pgwire, looks up the target tenant, and forwards traffic. The proxy uses session-revival tokens (pkg/security/sessionrevival/) to keep long-running connections live across tenant restarts.

Related pages

• Server — serverController lives there.
• Security — tenant client certs.
• Span config — per-tenant zone configs.