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.