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.