Concepts
Four nouns cover bocal's whole model: fixture, tag, store, and registry.
Fixture
A fixture is a named, versioned snapshot. Each tag of a fixture is a fully self-contained snapshot directory containing:
- One dump file per declared service (e.g.
postgres.dump,dolt.sql.gz). - One
fixture.tomldescribing that tag's metadata, services, file mappings, and env overrides. - A
manifest.json(per-file SHA-256 integrity baseline). - Zero or more copied config files declared in
[[files]].
fixture.toml lives inside each tag directory, not at the fixture level — each tag is captured at a different time, by a different person, and may declare a different set of services and files.
<store>/
└── customer-a/
├── latest/
│ ├── fixture.toml
│ ├── manifest.json
│ ├── postgres.dump
│ └── dolt.sql.gz
└── v2/
├── fixture.toml
├── manifest.json
└── postgres.dump
Tag
Each fixture has one or more tags. The default is latest. Tags are directory names under the fixture name.
latestis a mutable rolling pointer — everysaveoverwrites it.- Every explicit (non-
latest) tag is immutable — once saved, re-saving it errors unless you pass--force. This makes a named tag a frozen snapshot you can pin a known-good state to (the model mirrors an artifact registry).
bocal save customer-a # writes customer-a/latest/ (overwrites)
bocal save customer-a --tag v2 # writes customer-a/v2/ (errors if v2 exists)
bocal save customer-a --tag v2 --force # overwrites an existing immutable v2
bocal restore customer-a --tag v2 # reads customer-a/v2/
Store
The fixture store is a directory on disk. Default: .bocal/ at the project root (configurable via --store or BOCAL_STORE). It also holds a reserved .undo/ directory for restore --backup undo sets. The store is meant to be gitignored — fixtures are shared via the registry, not Git.
Registry
A registry is an S3-compatible bucket (AWS S3, Cloudflare R2, MinIO, …) used to push and pull fixtures between machines. Multiple named registries are supported — much like git remotes, where default plays the role of origin. See Registry and Configuration.
The empty fixture (a convention)
empty is an ordinary fixture by convention, not a special construct. It captures a database with its schema but no (or minimal) data: create the empty database, run migrations, then bocal save empty. It exists because bocal restore requires the target database to already exist — empty is the conventional way to get a schema-correct, data-free starting point onto a fresh environment in one command. Nothing in bocal hardcodes the name; call it baseline or schema-only if you prefer.
What a fixture does not guarantee
A multi-service fixture is not a single coordinated point-in-time across services — bocal save captures services sequentially, each with its own captured_at. If writes land between two captures, the set can be cross-service inconsistent. bocal makes this visible (per-service captured_at + a divergence warning) rather than hiding it. The reliable way to get a consistent multi-service snapshot today is to quiesce writes while saving. See Limits.