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.