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 → port field → error.
  • Host: --host → host_env → host field → 127.0.0.1.
  • --clean --if-exists drops 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 the flate2 codec — no external gzip) to dolt.sql.gz.
  • restore: dolt.sql.gz is gunzipped in-process and streamed into mysql -h <host> -P <port> -u <user> <dbname> (no external gunzip).
  • --single-transaction gives a consistent snapshot without locking (InnoDB and Dolt).
  • The dump carries DROP TABLE IF EXISTS / CREATE TABLE per 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-password flag → PGPASSWORD env → .pgpass. When the flag is set, bocal exports PGPASSWORD to the child process for that one invocation only.
  • MySQL/Dolt: --mysql-password flag → MYSQL_PWD env → ~/.my.cnf. The flag is passed via MYSQL_PWD (not -p<pw>) so the password is never visible in ps.

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:

VariableValue
BOCAL_FIXTURE_DIRAbsolute path to the tag directory.
BOCAL_TAGCurrent tag name.
BOCAL_FIXTURE_NAMEFixture name.
(the resolved port)Under the service's port_env name.
(the resolved host)Under the service's host_env name (if declared).
everything elseInherited 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 by POSTGRES_DB / MYSQL_DATABASE on first boot.
  • Under an orchestrator: the service it brings up owns DB creation; the hook runs bocal restore only 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 set version).
  • 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 newer pg_dump can emit settings an older server rejects, e.g. transaction_timeout from a PG17 client into a PG16 server).
  • --yes does not override a blocking version error. The check is skipped when either side is unknown (older fixtures, custom without version).

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.