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:

  1. Resolved service ports — under each service's port_env name (e.g. {{ POSTGRES_PORT }}).
  2. Resolved service hosts — under each service's host_env name.
  3. bocal vars — {{ BOCAL_FIXTURE_NAME }}, {{ BOCAL_TAG }}.
  4. Whitelisted shell env — only variables listed in bocal.toml's template_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.

FieldMeaning
nameService name (used by --services, --port, --host).
enginepostgres, mysql, or custom (see Engines).
port_envEnv var bocal reads for the port.
portExplicit port fallback.
host_envEnv var for the host (optional; default 127.0.0.1).
hostExplicit host fallback (optional).
save / restoreShell commands (required for custom).
captured_atStamped per service by save.
engine_versionServer version stamped by save (used for version-compat).
versionFor 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 export is 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-env values override inherited [env] values.

Worked examples (input → stored):

InputStored value
FOO=barbar
FOO="bar"bar
FOO="a=b"a=b
FOO="bar" # x"bar" # x
FOO=bar # xbar # x