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.
bocalis 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
customengine). - Config files — copied into your worktree on restore.
- Environment variables — written to a plain
KEY=valuefile (.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.
restoreruns a preflight (dumps present, tooling onPATH, target reachable and the database exists, engine versions compatible) before touching anything, then prompts for confirmation likerm. It supports--dry-run,--backup/--undo, and a non-loopback--allow-remoteguard. - Honest about guarantees. A multi-service fixture is not a coordinated point-in-time snapshot; bocal records a per-service
captured_atand warns on divergence rather than hiding it. - Extensible without forking. Postgres and MySQL are first-class; everything else works today via the
customengine (pointsave/restoreat 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:
| Engine | Tools needed on PATH |
|---|---|
postgres | pg_dump, pg_restore, psql |
mysql (incl. Dolt) | mysql, mysqldump |
custom | whatever 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_dumpcan 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.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.
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, soverifyworks even on fixtures that were never pushed. --tagdefaults tolatest. Explicit tags are immutable (need--forceto 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 originalcaptured_at. Unknown service names are rejected.--port/--hostoverride resolution for one service (repeatable).--from-env <file>merges aKEY=valuefile into[env](see parsing rules).savenever 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.tomlparses, 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-remoteis 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:
| Flag | Effect |
|---|---|
--no-env / --no-files | Skip writing the env file / copying files. |
--services | Restore only the listed services (unknown names rejected). |
--dry-run | Preflight + plan, then exit. No prompt, no mutation. |
--yes | Skip the confirmation prompt (hooks/CI). Does not imply --allow-remote. |
--host / --allow-remote | Override host; permit a non-loopback target. |
--pull | Pull the tag from the registry first (keeps the store), then restore. Errors on a diverged local tag. |
--registry <name> | Registry for --pull/--ci. |
--ci | Restore directly from the registry into a throwaway temp dir (no store). Implies --yes. Mutually exclusive with --pull. |
--backup | Dump each target to a sidecar undo set (<store>/.undo/) before overwriting. |
--undo | Reload 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 --cleancan 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 liveHeadBucket).--globalwrites~/.config/bocal/config.toml. Records the profile name only; never a secret.remove— delete a registry block from config. (Contrastrm, 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:
- 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 |
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
| Variable | Purpose |
|---|---|
BOCAL_STORE | Override the default store path. |
BOCAL_REGISTRY | Default registry name. |
BOCAL_WORKTREE | Worktree root for [[files]] (overridden by --worktree; default cwd). |
BOCAL_USER | Identity for created_by/pushed_by (else git config user.email, else $USER). |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_PROFILE | S3 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, PGDATABASE | Postgres connection. |
MYSQL_USER, MYSQL_PWD | MySQL/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→portfield → error. - Host:
--host→host_env→hostfield →127.0.0.1. --clean --if-existsdrops 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 theflate2codec — no externalgzip) todolt.sql.gz. - restore:
dolt.sql.gzis gunzipped in-process and streamed intomysql -h <host> -P <port> -u <user> <dbname>(no externalgunzip). --single-transactiongives a consistent snapshot without locking (InnoDB and Dolt).- The dump carries
DROP TABLE IF EXISTS/CREATE TABLEper 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-passwordflag →PGPASSWORDenv →.pgpass. When the flag is set, bocal exportsPGPASSWORDto the child process for that one invocation only. - MySQL/Dolt:
--mysql-passwordflag →MYSQL_PWDenv →~/.my.cnf. The flag is passed viaMYSQL_PWD(not-p<pw>) so the password is never visible inps.
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:
| Variable | Value |
|---|---|
BOCAL_FIXTURE_DIR | Absolute path to the tag directory. |
BOCAL_TAG | Current tag name. |
BOCAL_FIXTURE_NAME | Fixture name. |
| (the resolved port) | Under the service's port_env name. |
| (the resolved host) | Under the service's host_env name (if declared). |
| everything else | Inherited 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 byPOSTGRES_DB/MYSQL_DATABASEon first boot. - Under an orchestrator: the service it brings up owns DB creation; the hook runs
bocal restoreonly 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 setversion). - 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 newerpg_dumpcan emit settings an older server rejects, e.g.transaction_timeoutfrom a PG17 client into a PG16 server).
--yesdoes not override a blocking version error. The check is skipped when either side is unknown (older fixtures,customwithoutversion).
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 remoteslists the registries you've configured;registry lslists the fixtures inside a bucket. Andregistry removeforgets a remote, whileregistry rmdeletes fixtures from one.
Sync model
Push
bocal push customer-a --tag v1
- Read the local tag's
fixture.toml+ all files, compute SHA-256 of each. - Upload every file to
s3://<bucket>/<prefix>customer-a/v1/(multipart for large files). - Last, upload
manifest.json— per-file SHA-256 plusservices,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
- Fetch
manifest.json. - For each file: skip if a local copy already matches by SHA-256; otherwise download.
- 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 pushas 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
--pullfolds the pull into the restore while keeping the local store, so repeatedecluse ups across slots re-download nothing. It's the recommended hook form — no separatebocal pullstep to remember.--yesskips the confirmation prompt (a hook has no TTY). The preflight still runs — tooling, host/port reachability, target-DB existence, version compatibility, templating.--yesdoes 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 thecustomengine. 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 thedocker_e2efeature 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:
-
Open an issue describing the engine and the exact
save/restorecommands you'd run by hand. Maintainers confirm it clears the bar before you write code. -
Implement the
Enginetrait in a new file undersrc/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() } } }EngineContextcarries the resolved host/port, user/dbname resolution (flags → env → defaults, same pattern as postgres/mysql), the tag directory, and the fixture name/tag. -
Register it in
engines::for_service()soengine = "<name>"resolves. -
Document it — add a subsection to Engines with the exact
save/restorecommands and the params it resolves. -
Test — a unit test for param resolution, and a round-trip integration test (save → wipe → restore → assert). Gate live-service tests behind the
docker_e2efeature 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 --cleandrops 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 diffships with a lightweight checksum/size dump comparison; a heavier schema/row diff or per-table row counts could layer on top.