bocal

bocal is a CLI for capturing and restoring named environment snapshots. A snapshot bundles together database dumps, config-file overrides, and environment-variable overrides into a named, versioned artifact called a fixture. Fixtures can be saved locally, shared with a team via an S3-compatible registry, and restored into any environment — with or without an orchestrator.

bocal is French for jar — the sealing jar you preserve things in.

I like my env  →  bocal save  →  bocal push  →  teammate: bocal pull  →  bocal restore

The problem

Reproducing a specific application state — a particular customer's data, a regression case, a feature scenario — usually means one of:

  • Seed scripts that are slow, fragile, and drift from real data.
  • Manual database dumps with no versioning or sharing.
  • Every developer maintaining their own local setup with no way to share it.

It gets worse with multiple databases (say Postgres + Dolt), config files that must change alongside the data, and env vars that differ per scenario. There is no standard tool for capturing and restoring a complete environment state as a unit.

What bocal does

A fixture packages three things together:

  • Database dumps — one per service (Postgres, MySQL/Dolt, or anything via a custom engine).
  • Config files — copied into your worktree on restore.
  • Environment variables — written to a plain KEY=value file (.bocal.env) on restore.

Two commands do the real work:

bocal save customer-a       # capture current DB + files + env into a fixture
bocal restore customer-a    # blow that state back into your environment

Plus versioning with tags (latest is the default) and team sharing via an S3-compatible registry (push / pull).

Design philosophy

  • No opinion about your environment. bocal never starts, stops, or manages services. It speaks in ports, files, and env vars — tell it where the database is listening and where your worktree is, and it works. This is why it composes with an orchestrator like ecluse purely by convention, with zero orchestrator-specific code.
  • Safety-first on the destructive path. restore runs a preflight (dumps present, tooling on PATH, target reachable and the database exists, engine versions compatible) before touching anything, then prompts for confirmation like rm. It supports --dry-run, --backup/--undo, and a non-loopback --allow-remote guard.
  • Honest about guarantees. A multi-service fixture is not a coordinated point-in-time snapshot; bocal records a per-service captured_at and warns on divergence rather than hiding it.
  • Extensible without forking. Postgres and MySQL are first-class; everything else works today via the custom engine (point save/restore at shell commands).

Where to go next

  • Install — get the binary.
  • Quickstart — save and restore in a few commands.
  • Concepts — fixtures, tags, stores, registries.
  • Commands — the full CLI reference.

Install

bocal is a single static binary. macOS and Linux are supported (WSL2 works on Windows; native Windows is not supported).

Homebrew

brew install hefgi/tap/bocal

Cargo

cargo install bocal

Requires a Rust toolchain (edition 2021, Rust ≥ 1.89).

npm

A thin wrapper that downloads the prebuilt binary:

npm install -g bocal

Verify

bocal --version

Runtime dependencies

bocal shells out to the standard client tools for the built-in engines — install whichever you use:

EngineTools needed on PATH
postgrespg_dump, pg_restore, psql
mysql (incl. Dolt)mysql, mysqldump
customwhatever your save/restore commands invoke

Compression for the mysql engine is handled in-process (no external gzip/gunzip needed). Cloud credentials for the registry come from the standard AWS chain — see Configuration.

Tip: keep your Postgres client tools' major version ≥ the server you restore into. bocal's preflight blocks a client older than the target and warns when it's much newer (a newer pg_dump can emit settings an older server rejects).

Quickstart

This walks through capturing a fixture and restoring it — standalone, against a local Postgres.

1. Initialize

From your project root:

bocal init

This writes bocal.toml (store path + defaults) and adds .bocal/ and .bocal.env to .gitignore.

2. Declare a fixture

bocal does not auto-discover services — you declare them once in a fixture's fixture.toml. Create .bocal/customer-a/latest/fixture.toml:

name = "customer-a"
tag = "latest"
description = "Acme Corp demo data"

[env]
BILLING_MODE = "enterprise"
DATABASE_URL = "postgres://localhost:{{ POSTGRES_PORT }}/app"

[[services]]
name = "postgres"
engine = "postgres"
port_env = "POSTGRES_PORT"

See the Fixture format for every field. The {{ POSTGRES_PORT }} placeholder is env templating — it's filled in at restore time with the resolved port.

3. Save

Point bocal at your database (via the port env var, plus the standard PG* vars for user/dbname):

POSTGRES_PORT=5432 PGDATABASE=app bocal save customer-a

bocal runs pg_dump, writes postgres.dump + a manifest.json (SHA-256 baseline) into the tag, and stamps the capture time and server version.

4. Restore

Later — or on another machine after a pull — reload it:

POSTGRES_PORT=5432 PGDATABASE=app bocal restore customer-a

restore runs a preflight, prints the plan, and prompts for confirmation (it overwrites the live database). Use --dry-run to preview, or --yes in a hook/CI:

POSTGRES_PORT=5432 PGDATABASE=app bocal restore customer-a --dry-run

It also writes the [env] block to .bocal.env (with {{ }} placeholders resolved). bocal writes that file; it does not source it — load it into your processes yourself (set -a; . ./.bocal.env; set +a).

5. Share

Configure a registry, then push and pull:

bocal registry add default s3://my-team-bocal --region us-east-1
bocal push customer-a
# on another machine:
bocal pull customer-a
bocal restore customer-a

Or collapse pull-then-restore into one command (great for orchestrator hooks):

bocal restore customer-a --pull

Next

  • Concepts — the mental model.
  • Commands — every command and flag.
  • Registry — sharing, sync model, conflict handling.

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.

Commands

Every command. Global resolution: the store is --store → BOCAL_STORE → bocal.toml store → .bocal; the registry is --registry → BOCAL_REGISTRY → default.

Exit codes: 0 success, 1 generic error, 3 blocking engine-version incompatibility, 4 lock timeout.


init

bocal init [--store <path>]

Create bocal.toml in the current directory with defaults and add .bocal/ + .bocal.env to .gitignore. bocal.toml is meant to be committed (it holds the store path and shared registry config, no secrets); the store and .bocal.env are not.


save

bocal save <name> [--tag <tag>] [--store <path>] [--services <a,b,c>]
                  [--port <service>=<port>] [--host <service>=<host>]
                  [--worktree <path>] [--from-env <file>] [--force]

Capture the current environment state into a fixture tag. Reads the existing tag's fixture.toml to learn which services/files/env to capture (bocal does not auto-discover).

  • Atomic: writes into a temp dir, then renames over the target tag only after every service succeeds. A failed save never corrupts an existing tag.
  • Writes manifest.json (per-file SHA-256) at save time, so verify works even on fixtures that were never pushed.
  • --tag defaults to latest. Explicit tags are immutable (need --force to overwrite).
  • --services (re)captures only the listed services; the others are carried forward from the existing tag unchanged, and a warning lists them with their original captured_at. Unknown service names are rejected.
  • --port/--host override resolution for one service (repeatable).
  • --from-env <file> merges a KEY=value file into [env] (see parsing rules).
  • save never needs --allow-remote — reading from a remote host is non-destructive.

restore

bocal restore <name> [--tag <tag>] [--store <path>] [--services <a,b,c>]
                     [--port <service>=<port>] [--host <service>=<host>] [--allow-remote]
                     [--worktree <path>] [--env-out <file>] [--no-env] [--no-files]
                     [--dry-run] [--yes] [--pull] [--registry <name>] [--ci]
                     [--backup] [--undo]

Restore a fixture into the current environment. This is the most destructive command bocal has — it overwrites live databases and worktree files, and it is not transactional.

Preflight (always runs, before any write) verifies the whole plan and aborts as a group if anything fails:

  • The tag exists, fixture.toml parses, every declared service's dump is present.
  • Each engine's required tooling is on PATH.
  • Each service's host/port resolves and the target is reachable; for built-in engines, the target database exists and is connectable.
  • Non-loopback guard: any service resolving to a non-loopback host aborts unless --allow-remote is passed (not implied by --yes).
  • Engine version compatibility (see Engines): a blocking error for known-incompatible pairs, a warning otherwise.
  • [[files]] dst paths resolve inside the worktree; [env] {{ }} placeholders all resolve (an unresolved one is a hard error).

If preflight passes, bocal prints the plan and prompts for confirmation unless --yes. --dry-run prints the plan and exits without restoring or prompting.

Then, in declared order: restore each service's dump, write [env] (placeholders substituted) to the env file, and copy [[files]] into the worktree (directory entries merge; nothing is deleted).

Flags:

FlagEffect
--no-env / --no-filesSkip writing the env file / copying files.
--servicesRestore only the listed services (unknown names rejected).
--dry-runPreflight + plan, then exit. No prompt, no mutation.
--yesSkip the confirmation prompt (hooks/CI). Does not imply --allow-remote.
--host / --allow-remoteOverride host; permit a non-loopback target.
--pullPull the tag from the registry first (keeps the store), then restore. Errors on a diverged local tag.
--registry <name>Registry for --pull/--ci.
--ciRestore directly from the registry into a throwaway temp dir (no store). Implies --yes. Mutually exclusive with --pull.
--backupDump each target to a sidecar undo set (<store>/.undo/) before overwriting.
--undoReload the most recent undo set back into the targets (itself runs preflight). Mutually exclusive with --backup.

Not transactional. A mid-sequence failure leaves earlier services already restored, and a failed pg_restore --clean can leave a database with objects dropped but not recreated. Recovery: re-run after fixing the cause, or (if you ran with --backup) --undo.


ls

bocal ls [--store <path>] [--json]

List all fixtures in the store, one row per tag (name, tag, services, created-at, description).


rm

bocal rm <name> [--tag <tag>] [--store <path>] [--yes]

Delete a fixture or a specific tag from the local store. Without --tag, deletes the whole fixture. Prompts unless --yes. Never touches the registry (use registry rm for that).


diff

bocal diff <a>[:<tag>] <b>[:<tag>] [--store <path>] [--no-env] [--no-files]

Compare two local fixtures (or two tags), from local data only. Reports an [env] key diff, an [[files]] diff (by SHA-256 hashed from disk), and a lightweight per-service dump comparison: identical on a checksum match, else a size delta. See Registry for the contrast with registry diff.


push

bocal push <name> [--tag <tag>] [--registry <name>] [--store <path>]

Upload a fixture tag to the registry — fixture.toml + dumps + files, with manifest.json written last (so a half-completed push has no manifest and is ignored by readers). Large files use multipart upload.


pull

bocal pull <name> [--tag <tag>] [--registry <name>] [--store <path>] [--force]

Download a fixture tag into the local store. Skips files whose local SHA-256 already matches. Without --force, errors if a local tag exists and differs (by checksum), showing local vs remote provenance; --force overwrites.


verify

bocal verify <name> [--tag <tag>] [--store <path>]

Local integrity check (no registry contact): fixture.toml parses, every dump is present, and each file's SHA-256 matches manifest.json. Also surfaces the divergence advisory. Without --tag, verifies all tags.


registry subcommands

Manage registries (like git remotes) and operate on a registry's contents.

bocal registry add <name> <bucket> [--region <r>] [--endpoint <url>] [--prefix <p>]
                                    [--path-style] [--profile <p>] [--global] [--force]
bocal registry remove <name> [--global]
bocal registry remotes [--json]
bocal registry ls [--registry <name>] [--json]
bocal registry diff <name> [--tag <tag>] [--registry <name>]
bocal registry rm <name> [--tag <tag>] [--registry <name>] [--yes]
  • add — write a [registries.<name>] block (validated with a live HeadBucket). --global writes ~/.config/bocal/config.toml. Records the profile name only; never a secret.
  • remove — delete a registry block from config. (Contrast rm, which deletes fixtures from the bucket.)
  • remotes — list configured registries (git remote -v), marking the default with *.
  • ls — list the fixtures inside a registry's bucket.
  • diff — compare a local tag vs the remote (by checksum).
  • rm — delete a fixture or tag from the registry (manifest deleted first). Louder confirmation — it removes it for everyone.

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

Configuration

bocal.toml lives at the project root and is optional — bocal works with defaults and CLI flags. A global ~/.config/bocal/config.toml can hold cross-project registry definitions; project config overrides global by name.

store = ".bocal"              # local fixture store (default)
env_out = ".bocal.env"       # file restore writes [env] to (default)

# undo_keep = 3              # how many `restore --backup` undo sets to keep per
#                           # fixture (default 3; 0 disables pruning)
# divergence_warn_secs = 3600  # warn if a tag's services were captured more than
#                              # this far apart (default 3600 = 1h)

# template_env: shell env vars allowed inside {{ }} placeholders in [env].
# Resolved service ports/hosts and BOCAL_* are always available; this adds
# named shell vars. Arbitrary shell env is never read.
# template_env = ["APP_ENV", "API_BASE_URL"]

# Named registries. "default" is used when --registry is omitted.
[registries.default]
bucket = "s3://my-team-bocal"
region = "us-east-1"
# prefix = "myproject/"     # optional key prefix inside the bucket
# endpoint = "..."          # S3-compatible endpoint (R2, MinIO, …)
# path_style = false        # addressing (see below)
# profile = "..."           # AWS profile for this registry's creds (see below)

# Self-hosted MinIO with its own credentials via an AWS profile
[registries.staging]
bucket = "s3://my-team-bocal-staging"
endpoint = "https://my-minio.internal:9000"
region = "us-east-1"        # MinIO ignores it, but the S3 client requires one
path_style = true
profile = "minio-staging"

Credentials

Credentials follow the standard AWS chain: env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), ~/.aws/credentials, instance role. No credentials are ever stored in a bocal file — which is why bocal.toml is safe to commit.

Per-registry credentials (profile)

The bare AWS chain resolves one identity per process, which isn't enough when different registries need different credentials (AWS for default, MinIO keys for staging, an R2 token elsewhere). A registry block may name an AWS profile:

[registries.staging]
bucket = "s3://team-staging"
endpoint = "https://minio.internal:9000"
profile = "minio-staging"     # selects this identity from ~/.aws/credentials

with the identity in the standard AWS file:

# ~/.aws/credentials
[minio-staging]
aws_access_key_id = minioadmin
aws_secret_access_key = ...

Resolution per operation: the registry's profile → AWS_PROFILE → the default chain. The profile only selects which credentials the chain reads — bocal stores no secret, so the block stays committable.

Addressing (path_style)

The S3 client can address a bucket two ways:

  • Virtual-hosted (https://<bucket>.host/<key>) — AWS S3 and Cloudflare R2 default.
  • Path-style (https://host/<bucket>/<key>) — required by MinIO and most self-hosted gateways.

Resolution: explicit path_style in the block wins; otherwise it's auto-enabled when endpoint is set (the MinIO/self-hosted signal) and off for AWS/R2. A bucket name containing dots also forces path-style (TLS-cert mismatch on virtual-hosted).

Region

Required by the S3 client even for providers that ignore it (MinIO). When an endpoint is set and region is omitted, bocal defaults to us-east-1. For AWS, region (or AWS_REGION) must match the bucket's real region.

Validation

bocal validates a registry on first use with a cheap HeadBucket — surfacing endpoint/credential/addressing/profile misconfiguration as a single actionable error rather than a cryptic mid-upload failure. bocal registry add runs the same check at add time.

Environment variables

VariablePurpose
BOCAL_STOREOverride the default store path.
BOCAL_REGISTRYDefault registry name.
BOCAL_WORKTREEWorktree root for [[files]] (overridden by --worktree; default cwd).
BOCAL_USERIdentity for created_by/pushed_by (else git config user.email, else $USER).
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_PROFILES3 credentials / region / profile.
(each service's port_env)Port for that service.
(each service's host_env)Host for that service (non-loopback needs --allow-remote).
PGUSER, PGPASSWORD, PGDATABASEPostgres connection.
MYSQL_USER, MYSQL_PWDMySQL/Dolt connection.

Engines

Every service declares an engine. There are three: postgres, mysql, and custom. The first two are first-class; custom covers everything else.

postgres

  • save: pg_dump -Fc -h <host> -p <port> -U <user> <dbname> > postgres.dump
  • restore: pg_restore -h <host> -p <port> -U <user> -d <dbname> --clean --if-exists postgres.dump

-Fc (custom format) is already compressed — bocal does not gzip it again. The dump is postgres.dump.

  • User/dbname: --pg-user/--pg-dbname → PGUSER/PGDATABASE → postgres/postgres.
  • Port: --port → port_env → port field → error.
  • Host: --host → host_env → host field → 127.0.0.1.
  • --clean --if-exists drops and recreates the objects present in the dump — it does not drop objects absent from the dump. For a fully clean target, drop/recreate the database out of band.
  • bocal does not create the target database; it must already exist and accept connections (preflight checks this).

mysql

Also covers Dolt (MySQL wire-compatible), MariaDB, and standard MySQL.

  • save: mysqldump --single-transaction -h <host> -P <port> -u <user> <dbname>, gzip-compressed in-process (via the flate2 codec — no external gzip) to dolt.sql.gz.
  • restore: dolt.sql.gz is gunzipped in-process and streamed into mysql -h <host> -P <port> -u <user> <dbname> (no external gunzip).
  • --single-transaction gives a consistent snapshot without locking (InnoDB and Dolt).
  • The dump carries DROP TABLE IF EXISTS / CREATE TABLE per table (mysqldump default), so restore is a clean replace of those tables. Tables absent from the dump are not dropped.
  • User: --mysql-user → MYSQL_USER → root. Host/port resolve like postgres.

Authentication

bocal never stores a database password in any file. For the built-in engines the password resolves:

  • Postgres: --pg-password flag → PGPASSWORD env → .pgpass. When the flag is set, bocal exports PGPASSWORD to the child process for that one invocation only.
  • MySQL/Dolt: --mysql-password flag → MYSQL_PWD env → ~/.my.cnf. The flag is passed via MYSQL_PWD (not -p<pw>) so the password is never visible in ps.

The MySQL engine invokes the client with --protocol=TCP so -h localhost connects over TCP to the resolved -P <port> rather than silently switching to a unix socket. A rejected password surfaces in the restore preflight (check_target) with an actionable message.

custom

Both save and restore are shell commands. bocal injects:

VariableValue
BOCAL_FIXTURE_DIRAbsolute path to the tag directory.
BOCAL_TAGCurrent tag name.
BOCAL_FIXTURE_NAMEFixture name.
(the resolved port)Under the service's port_env name.
(the resolved host)Under the service's host_env name (if declared).
everything elseInherited from the calling shell.
[[services]]
name = "my-store"
engine = "custom"
save = "my-dump.sh $MY_STORE_PORT > $BOCAL_FIXTURE_DIR/my-store.dump"
restore = "my-load.sh $MY_STORE_PORT < $BOCAL_FIXTURE_DIR/my-store.dump"
port_env = "MY_STORE_PORT"
# version = "7.0"   # optional; enables the restore version-mismatch warning

A non-zero exit is a failure. The custom engine covers MongoDB, SQLite, ClickHouse, Redis, an S3 bucket of files — anything dumpable and reloadable from a port + a file — with no changes to bocal's source.

Target database provisioning

bocal restores into an existing, reachable database — it never runs CREATE DATABASE, starts a server, or creates a container. On a fresh environment the target DB must exist before restore runs, or preflight fails. Who creates it:

  • Standalone: you (or docker run/compose). The official Postgres/MySQL images create the DB named by POSTGRES_DB / MYSQL_DATABASE on first boot.
  • Under an orchestrator: the service it brings up owns DB creation; the hook runs bocal restore only after the server is up. See ecluse integration.

Version compatibility

Dump formats are version-sensitive, and fixtures are shared across machines and over time, so capture-time and restore-time versions routinely differ. bocal makes this visible rather than failing cryptically.

  • At save, bocal stamps each service's server version into engine_version (postgres: SHOW server_version; mysql: SELECT VERSION(); custom: only if you set version).
  • At restore (preflight), bocal compares two things:
    • Dump-server vs target-server. Dump major > target major for postgres is a blocking error (a newer archive can't restore into an older server). Any other mismatch is a warning.
    • Restore-client vs target-server. pg_restore's major must be ≥ the server. A client older than the target is a blocking error; a client much newer is a warning (a newer pg_dump can emit settings an older server rejects, e.g. transaction_timeout from a PG17 client into a PG16 server).
  • --yes does not override a blocking version error. The check is skipped when either side is unknown (older fixtures, custom without version).

Adding an engine

Promoting a custom recipe to a built-in is a community contribution against a small Engine trait — see Contributing. Prefer streaming over the wire (e.g. mongodump --archive) so it works identically on host or in Docker and needs no service restart.

Registry

A registry is an S3-compatible bucket used to share fixtures between machines. See Configuration for setting one up (bucket, endpoint, region, path-style, per-registry AWS profile).

Managing registries (like git remotes)

bocal registry add origin s3://my-team-bocal --region us-east-1   # git remote add
bocal registry remotes                                            # git remote -v
bocal registry remove staging                                     # git remote remove
bocal push customer-a --registry origin

registry add validates the bucket with a live HeadBucket (using the resolved credentials, including --profile), so misconfiguration fails at add time. --global writes to ~/.config/bocal/config.toml for cross-project use. remotes marks the default (BOCAL_REGISTRY, else default) with a *.

Two different "lists": registry remotes lists the registries you've configured; registry ls lists the fixtures inside a bucket. And registry remove forgets a remote, while registry rm deletes fixtures from one.

Sync model

Push

bocal push customer-a --tag v1
  1. Read the local tag's fixture.toml + all files, compute SHA-256 of each.
  2. Upload every file to s3://<bucket>/<prefix>customer-a/v1/ (multipart for large files).
  3. Last, upload manifest.json — per-file SHA-256 plus services, created_at, description, pushed_at, pushed_by.

Writing the manifest last makes the push atomic from a reader's point of view: a tag with no manifest is ignored by pull/diff/ls, so an interrupted push is never mistaken for a valid tag.

Pull

bocal pull customer-a --tag v1
  1. Fetch manifest.json.
  2. For each file: skip if a local copy already matches by SHA-256; otherwise download.
  3. Verify checksums after download.

Conflict handling

Pull without --force errors if a local tag exists and any file's SHA-256 differs from the remote — divergence is by checksum, never mtime. If everything matches, pull is a no-op. The error shows which files differ plus local vs remote provenance, and suggests --force (overwrite) or --tag (pull into a new tag). restore --pull applies the same rule but has no --force: a diverged local tag is a hard error telling you to resolve it first.

Listing

bocal registry ls scans the bucket for */*/manifest.json and renders one row per tag from the manifest alone (no fixture.toml fetch):

FIXTURE          TAG       SERVICES              PUSHED AT             PUSHED BY
customer-a       latest    postgres, dolt        2026-06-20 10:12      alice@...
customer-a       v1        postgres, dolt        2026-06-18 09:44      francois@...
empty            latest    postgres              2026-06-15 14:01      francois@...

Deletion

bocal registry rm customer-a --tag experiment   # one tag
bocal registry rm customer-a                     # whole fixture (all tags)

Deletes the manifest first (instantly invisible to readers), then the rest. The confirmation is louder than local rm because it removes the fixture for everyone with registry access. --yes skips it.

Two diffs

  • bocal diff <a> <b> — compare two local fixtures/tags (see Commands).
  • bocal registry diff <name> — compare one tag, local vs remote, by checksum.

Concurrency

bocal serializes store-mutating operations on a single machine with per-fixture advisory locks. It does not coordinate two machines (or two pushes) writing the same tag to the registry — there it's last-writer-wins at the object level, surfaced afterward by the checksum-based pull conflict check.

Secrets

Fixtures store [env] values in plaintext inside fixture.toml, and bocal push uploads them to the registry as-is. Because fixtures are meant to be shared, any secret placed in [env] (API keys, tokens) is exposed to everyone with bucket read access and may be cached or indexed downstream.

The rule

Treat [env] as carrying test-tier values, not production secrets:

  • Store a literal only when it's non-sensitive — a test API key (sk_test_…), a feature-flag boolean, non-sensitive config.
  • For real secrets, keep them in your normal secret store and let [env] carry only a pointer or a test-tier value.
  • Restrict registry bucket access and enable bucket-level encryption at rest (SSE).
  • Treat bocal push as publishing — once pushed, assume the values are out of your control even after deletion.

Why plaintext is a deliberate choice

This is a v0 decision, not a known gap. bocal's intended use is sharing test data — the "keep real secrets elsewhere, put only a pointer or test value in [env]" rule is the contract for what belongs in a fixture. Encryption at rest is delegated to S3 bucket SSE + ACLs.

Note that credentials for the registry itself are never in any bocal file — they come from the AWS chain (see Configuration). Only [env] values you author are plaintext.

Per-fixture application-layer encryption (age/SOPS) is tracked as future work but is not planned for v0; the plaintext model is considered sufficient for the test-data sharing bocal is built for.

ecluse integration

bocal has no dependency on any orchestrator and contains no orchestrator-specific code. It composes with ecluse (an ephemeral local-environment orchestrator) purely by convention, through three contracts bocal already exposes. This page is a practical guide; the full contract is specified in PRD-ecluse-integration.md in the repo.

The workflow neither tool does alone:

"Spin up a fresh isolated environment for this branch and load it with a specific named dataset a teammate captured."

ecluse gets you the empty, isolated environment; bocal fills it with known state.

Contract 1 — ports in, via env var

ecluse publishes each service's per-slot port as ECLUSE_<SERVICE>_PORT. Point each fixture service's port_env at it:

# fixture.toml
[[services]]
name = "postgres"
engine = "postgres"
port_env = "ECLUSE_POSTGRES_PORT"   # bocal reads the per-slot port ecluse allocated

That's the entire wiring on bocal's side — no new code.

Contract 2 — hooks invoke bocal

# .ecluse.toml
[hooks]
post_up  = "bocal restore customer-a --pull --yes"   # pull-if-needed, then restore
# pre_down = "bocal save customer-a"                   # optional: capture on teardown
  • --pull folds the pull into the restore while keeping the local store, so repeated ecluse ups across slots re-download nothing. It's the recommended hook form — no separate bocal pull step to remember.
  • --yes skips the confirmation prompt (a hook has no TTY). The preflight still runs — tooling, host/port reachability, target-DB existence, version compatibility, templating. --yes does not imply --allow-remote, so a hook can never silently restore over a remote DB (ecluse services are on loopback anyway).

The target database must already exist when post_up fires. The service ecluse brings up owns DB creation (the official Postgres image creates POSTGRES_DB on first boot); bocal only fills it. bocal's preflight catches a not-yet-created DB up front with an actionable error.

Contract 3 — env out, via file

bocal restore writes [env] to .bocal.env (a KEY=value file). bocal writes it and stops — loading it into the running processes is the orchestrator's (or your) job. Two supported mechanisms; pick one:

A — ecluse sources the file (if your ecluse supports it):

# .ecluse.toml
source_env = [".bocal.env"]

B — the dev command sources it (always works):

[[services]]
name = "api"
command = "set -a; . ./.bocal.env 2>/dev/null; set +a; npm run dev"

Per-slot values via templating

A fixture can't hardcode a value that depends on the per-slot port — most commonly a connection string. Use env templating:

# fixture.toml — [env]
DATABASE_URL = "postgres://localhost:{{ ECLUSE_POSTGRES_PORT }}/app"

On restore into a slot, bocal substitutes the resolved port, so .bocal.env carries the correct per-slot DATABASE_URL while the stored fixture stays slot-agnostic and shareable. To interpolate other ecluse-published vars, allowlist them via template_env in bocal.toml.

End-to-end

# Developer A — capture and share
ecluse up feat-demo                 # ports published as ECLUSE_*_PORT
# ... set up data in the running app ...
bocal save customer-a --tag v1
bocal push customer-a --tag v1

# Developer B — just spin up; the hook pulls and restores
ecluse up feat-demo                 # post_up runs `bocal restore customer-a --pull --yes`

For ephemeral CI with no persistent store, bocal restore customer-a --ci reads straight from the registry (implies --yes).

Contributing

Dev workflow

bocal is written in Rust. The pre-push checks (also enforced in CI on Ubuntu + macOS):

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

Or via the Makefile:

make check   # fmt + clippy + test

Tests

  • Fast suite (make test / cargo test) — unit tests plus CLI integration tests that drive the built binary in temp dirs using the custom engine. No external services.

  • Live-service suite (make e2e) — real Postgres/MySQL round-trips and a real S3 push/pull (incl. multipart) against MinIO, gated behind the docker_e2e feature so the fast suite never needs Docker:

    make e2e-up          # docker compose: postgres + mysql + minio
    make e2e             # cargo test --features docker_e2e
    make e2e-down
    

CI runs both suites on every push/PR.

Conventions

  • One logical change per commit.
  • A bug fix gets a failing-then-passing test.
  • New engines require a unit test for param resolution; a round-trip integration test is the bar for merge.

Contributing a new engine

bocal ships postgres and mysql as built-ins; everything else is reachable today via the custom engine. Promote a custom recipe to a built-in only when it clears the bar: the engine is widely used, its dump/restore is stable across versions, and its tooling is something users already have installed.

The flow — open an issue first, then implement:

  1. Open an issue describing the engine and the exact save/restore commands you'd run by hand. Maintainers confirm it clears the bar before you write code.

  2. Implement the Engine trait in a new file under src/engines/ (e.g. src/engines/mongodb.rs). The trait — the same contract the built-in engines satisfy:

    #![allow(unused)]
    fn main() {
    pub trait Engine {
        fn name(&self) -> &'static str;              // the engine = "..." identifier
        fn dump_file(&self) -> &str;                 // default dump filename in the tag dir
        fn save(&self, ctx: &EngineContext) -> Result<()>;
        fn restore(&self, ctx: &EngineContext) -> Result<()>;
        fn probe_version(&self, ctx: &EngineContext) -> Result<Option<String>> { Ok(None) }
        fn probe_client_version(&self, ctx: &EngineContext) -> Result<Option<String>> { Ok(None) }
        fn check_target(&self, ctx: &EngineContext) -> Result<()> { Ok(()) }
        fn required_tools(&self, ctx: &EngineContext) -> Vec<String> { Vec::new() }
    }
    }

    EngineContext carries the resolved host/port, user/dbname resolution (flags → env → defaults, same pattern as postgres/mysql), the tag directory, and the fixture name/tag.

  3. Register it in engines::for_service() so engine = "<name>" resolves.

  4. Document it — add a subsection to Engines with the exact save/restore commands and the params it resolves.

  5. Test — a unit test for param resolution, and a round-trip integration test (save → wipe → restore → assert). Gate live-service tests behind the docker_e2e feature like the existing ones.

Guidance

Prefer streaming over the wire (e.g. mongodump --archive | gzip) over reading files off a container's disk — it works identically whether the service runs on the host or in Docker, needs no service restart, and keeps the "bocal does not manage services" boundary intact.

Limits

Intentional v0 boundaries. These are deliberate, documented choices — not bugs.

bocal does not manage your environment

bocal never starts, stops, or provisions services. It does not create databases, run CREATE DATABASE, start a server, or spin up a container. It restores into an existing, reachable database — which must exist before restore runs (the preflight checks this). See target database provisioning.

Restore is not transactional

restore overwrites live targets and cannot roll them back, at two levels:

  • Across services — a mid-sequence failure leaves earlier services already restored.
  • Within a service — pg_restore --clean drops objects before recreating them, so a failure mid-restore can leave a database with objects dropped but not recreated.

The preflight catches predictable failures (missing tool, unreachable port, missing database, version mismatch) before the first write, but it can't make the sequence itself atomic. Recovery: re-run after fixing the cause, or use --backup/--undo for a manual undo path.

Cross-service consistency

A multi-service fixture is not a coordinated point-in-time snapshot. 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 the risk visible — per-service captured_at, and a divergence warning (verify and restore) when timestamps span more than divergence_warn_secs. The reliable way to get a consistent multi-service snapshot today is to quiesce writes while saving. This suits bocal's target use — dev/test environments where the developer is the only one touching the DB during a save.

Secrets are plaintext

[env] values are stored and pushed in plaintext. Keep real secrets out of fixtures — see Secrets.

Loopback by default

bocal defaults to 127.0.0.1. Non-loopback targets are supported via host resolution (--host / host_env / host), but restoring over a non-loopback host requires an explicit --allow-remote (not implied by --yes), because overwriting a remote/shared DB is far more destructive than a local one. bocal is not a backup tool for production databases.

Platform

macOS and Linux only. WSL2 works; native Windows does not.

Tracked for the future

Not planned for v0, but on the radar:

  • Per-fixture encryption (age/SOPS) for [env] — currently delegated to S3 bucket SSE.
  • Selective table capture (pg_dump --table) for very large databases.
  • Consistency groups — a coordinated cross-service point-in-time capture, removing the sequential-capture caveat.
  • Semantic DB diff — bocal diff ships with a lightweight checksum/size dump comparison; a heavier schema/row diff or per-table row counts could layer on top.