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.toml describing 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.

  • latest is a mutable rolling pointer — every save overwrites 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.