Fixture format
fixture.toml lives inside each tag directory and fully describes one snapshot. It's written by bocal save and read by bocal restore / verify / diff.
name = "customer-a"
tag = "latest"
description = "Acme Corp demo — 3 users, 2 workspaces, flags on"
created_at = "2026-06-22T14:30:00Z" # when THIS tag was captured
created_by = "francois@enzyme.finance" # provenance, not the restorer
[env]
FEATURE_FLAG_X = "true"
BILLING_MODE = "enterprise"
DATABASE_URL = "postgres://localhost:{{ POSTGRES_PORT }}/app" # {{ }} resolved at restore
[[files]]
src = "settings.json" # path inside the tag dir
dst = "config/settings.json" # path in the worktree
[[files]]
src = "uploads/" # trailing / = a directory mapping (merges)
dst = "public/uploads/"
[[services]]
name = "postgres"
engine = "postgres"
port_env = "POSTGRES_PORT" # env var bocal reads for the port
# port = 5433 # explicit fallback if the env var is absent
# host_env = "POSTGRES_HOST" # optional; default 127.0.0.1
# host = "db.internal" # explicit host fallback (non-loopback needs --allow-remote)
captured_at = "2026-06-22T14:30:00Z" # stamped by save
engine_version = "16.2" # server version stamped by save
Names and tags
Fixture names and tags must match ^[a-z0-9][a-z0-9._-]{0,62}$ (they become directory names and S3 key segments). Invalid names are rejected.
[env]
A map of environment-variable overrides. On restore, bocal writes these to .bocal.env as a KEY=value file — it writes the file, it does not source it. Values are stored (and pushed) in plaintext; see Secrets.
Env templating
[env] values may contain {{ VAR }} placeholders, substituted at restore time when writing .bocal.env. This exists because ports are allocated per session (especially under an orchestrator), so a fixture can't hardcode a connection string. The stored fixture keeps the literal {{ }}; only the written env file gets the concrete value.
Namespace, resolved in order:
- Resolved service ports — under each service's
port_envname (e.g.{{ POSTGRES_PORT }}). - Resolved service hosts — under each service's
host_envname. - bocal vars —
{{ BOCAL_FIXTURE_NAME }},{{ BOCAL_TAG }}. - Whitelisted shell env — only variables listed in
bocal.toml'stemplate_env. Arbitrary shell env is never read, so restores stay reproducible.
Rules: substitution happens only at restore (never save); whitespace inside the braces is ignored ({{X}} == {{ X }}); a literal {{ is written {{{{; and an unresolved placeholder is a hard error in preflight — a typo fails loudly rather than writing a broken value.
[[files]]
Copy files between the worktree and the fixture.
src— path relative to the tag directory (inside the fixture).dst— path relative to the worktree root (--worktree,BOCAL_WORKTREE, else cwd).
On save, bocal copies dst → src (worktree into fixture). On restore, src → dst (fixture into worktree). A src/dst ending in / is a directory mapping that merges into the destination — files in the fixture overwrite their counterparts; files already at dst but absent from the fixture are left in place (no rsync-style delete).
Path safety: on restore, dst must resolve inside the worktree — absolute paths and .. escapes are rejected, so a shared fixture can't write outside the project. Symlinks inside a directory mapping are skipped (with a warning), never followed, so a fixture can't escape the root through a link. Existing files at dst are overwritten; the preflight lists them (skip with --no-files), and directory mappings show (merge).
[[services]]
One block per database to snapshot.
| Field | Meaning |
|---|---|
name | Service name (used by --services, --port, --host). |
engine | postgres, mysql, or custom (see Engines). |
port_env | Env var bocal reads for the port. |
port | Explicit port fallback. |
host_env | Env var for the host (optional; default 127.0.0.1). |
host | Explicit host fallback (optional). |
save / restore | Shell commands (required for custom). |
captured_at | Stamped per service by save. |
engine_version | Server version stamped by save (used for version-compat). |
version | For custom engines only — set it to enable the restore mismatch warning. |
Port resolves --port → port_env → port → error. Host resolves --host → host_env → host → 127.0.0.1.
Parsing --from-env files
bocal save --from-env <file> merges a KEY=value file into [env]. Rules:
- Each line splits on the first
=(values may contain=). - Blank lines and full-line
#comments are ignored. A#inside a value is kept — no inline-comment stripping. - An optional leading
exportis stripped from the key. - One surrounding matching quote pair is removed only if the entire value is wrapped; no escape/expansion processing.
- No multiline values.
- On conflict,
--from-envvalues override inherited[env]values.
Worked examples (input → stored):
| Input | Stored value |
|---|---|
FOO=bar | bar |
FOO="bar" | bar |
FOO="a=b" | a=b |
FOO="bar" # x | "bar" # x |
FOO=bar # x | bar # x |