Span config

pkg/spanconfig/ translates SQL-level zone configuration (ALTER ... CONFIGURE ZONE) into per-span policies that the KV layer enforces. It replaces an earlier "system config blob" model that did not scale past a few thousand objects.

Purpose

Operators express placement and replication policy in SQL: number of replicas, locality constraints, GC TTL, voter constraints, follower-read configuration, etc. The KV layer ultimately needs a roachpb.SpanConfig per range. Span-config is the reconciler that bridges the two, scaling to clusters with millions of objects.

Pipeline

graph LR
  Zones["ALTER TABLE … CONFIGURE ZONE …"] --> Catalog["catalog (pkg/sql/catalog)"]
  Catalog --> SQLTranslator["spanconfigsqltranslator: descriptor → span configs"]
  SQLTranslator --> Reconciler["spanconfigreconciler: write to system.span_configurations"]
  Reconciler --> Store["system.span_configurations (KV)"]
  Store --> Subscriber["spanconfigkvsubscriber: rangefeed → in-memory state"]
  Subscriber --> KVServer["replicateQueue / mergeQueue / splitQueue read SpanConfigs"]

Sub-packages

Package	What it does
pkg/spanconfig/	Top-level interfaces and types
pkg/spanconfig/spanconfigsqltranslator/	SQL descriptors → span configs
pkg/spanconfig/spanconfigreconciler/	Reconcile in-memory protobufs against the system table
pkg/spanconfig/spanconfigkvsubscriber/	Rangefeed-driven in-memory mirror of system.span_configurations
pkg/spanconfig/spanconfigsqlwatcher/	Watch SQL descriptor changes
pkg/spanconfig/spanconfigstore/	Sorted, in-memory span-config store
pkg/spanconfig/spanconfigsplitter/	Generate mandatory split keys
pkg/spanconfig/spanconfiglimiter/	Rate-limit span-config churn
pkg/spanconfig/spanconfigtestutils/	Datadriven test helpers

Key types

Type	File	Description
Reconciler	pkg/spanconfig/spanconfigreconciler/reconciler.go	Owns the reconciliation loop
KVSubscriber	pkg/spanconfig/spanconfigkvsubscriber/kvsubscriber.go	Rangefeed-backed mirror used by KV
Store	pkg/spanconfig/spanconfigstore/store.go	In-memory sorted span/config map
SQLTranslator	pkg/spanconfig/spanconfigsqltranslator/sqltranslator.go	Descriptor → SpanConfig
roachpb.SpanConfig	pkg/roachpb/data.proto	The wire-level config

Mandatory splits

Some keyspace boundaries must always be range boundaries — table boundaries, system tables, multi-tenant tenant boundaries. spanconfigsplitter/ enumerates these from the catalog so the splitter queue can ensure splits happen.

Multi-tenant story

In multi-tenant deployments, each tenant gets its own slice of system.span_configurations so operators can tune their own zone configs. The host-tenant reconciler aggregates tenant-level configs into the canonical KV store.

Tests

pkg/spanconfig/spanconfigtestutils/ powers a large suite of datadriven tests under pkg/ccl/spanconfigccl/ and the package tree. Reproducing a reconciliation bug typically just means writing one more testdata file.

Related pages

• KV server — consumer of span configs (allocator, queues).
• SQL — pkg/sql/zone_*.go and pkg/sql/alter_table_locality.go produce zone configs.
• features/multi-region — heaviest user of locality constraints.