Schema

Source: server/storage/schema/.

Purpose

schema defines the invariants of etcd's bbolt layout: which buckets exist, what version of the layout is expected, and how to migrate between versions. It is the place where every other server subsystem registers its on-disk shape, and the one place an etcdutl migrate invocation can rewrite the database.

Directory layout

server/storage/schema/
├── schema.go         # registry of versioned migrations
├── migration.go      # Migrator drives forward/backward steps
├── bucket.go         # named buckets (Key, Lease, Auth, Members, Cluster, Alarm, ...)
├── confstate.go      # serialized Raft conf state
├── cindex.go         # consistent-index tracker
├── alarm.go, lease.go, membership.go, auth.go, auth_users.go, auth_roles.go, version.go, changes.go, actions.go
└── *_test.go

Buckets at a glance

Bucket	Owner	Contents
key	mvcc	<revision> -> mvccpb.KeyValue
lease	lease	<leaseID> -> LeaseInfo
auth	auth	enabled flag, revision counter
authUsers	auth	<username> -> authpb.User
authRoles	auth	<role> -> authpb.Role
members	membership	<memberID> -> Member
members_removed	membership	tombstones for removed members
cluster	etcdserver/version	cluster version, downgrade flag
alarm	v3alarm	active alarms (NOSPACE, CORRUPT)
meta	various	consistent_index, term, scheduled compaction

bucket.go declares the canonical []byte keys and bucket names so subsystems agree on the bytes.

Key abstractions

Symbol	File	Description
Schema	server/storage/schema/schema.go	Version-indexed registry of actions
Migrator	server/storage/schema/migration.go	Walks the registry to take a DB from version A to B
Action	server/storage/schema/actions.go	A reversible step (forward / backward)
BucketID constants	server/storage/schema/bucket.go	Stable IDs for each bucket
UnsafeReadStorageVersion / UnsafeSetStorageVersion	server/storage/schema/version.go	The on-disk version stamp

How migration works

graph LR
    cur[(Current bolt DB)] --> mig[Migrator.Migrate(target)]
    schema[Schema registry] --> mig
    mig -->|forward steps| nv1[v3.5 → v3.6]
    mig -->|backward steps| nv0[v3.6 → v3.5]
    mig --> cur2[(Migrated DB)]

Each registered step is symmetrical (forward + backward). At runtime, EtcdServer consults the schema at startup to upgrade the DB to the cluster version; etcdutl migrate exposes the same logic for offline use.

Integration points

• bbolt backend: every bucket created here is registered with backend.BatchTx.
• mvcc, lease, auth, membership, alarm, version: each provides its own actions.go slice that wires its bucket-level changes into the schema.
• etcdutl migrate: etcdutl/etcdutl/migrate_command.go pulls a Migrator and runs it.
• Cluster version negotiation: server/etcdserver/version/ writes the version stamp this package uses.

Entry points for modification

• A new bucket → declare it in bucket.go, add the corresponding bolt-bucket creation in schema.go.
• A schema change → write paired Actions (forward + backward) in the appropriate file (e.g. auth_users.go for an auth change), wire into schema.go, and add coverage in migration_test.go.
• A new version → bump version.go and api/version/version.go, then make sure the migration registry has a no-op fallback for the new version.

Caveats

• The schema is forward-incompatible by default: a 3.5 binary will refuse to open a 3.6 DB unless the cluster version was lowered first.
• Downgrade is supported only between adjacent versions (3.6 ↔ 3.5).
• Tests under migration_test.go and schema_test.go are the contract; never change a step without updating both directions.