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