Contributing

Dev workflow

bocal is written in Rust. The pre-push checks (also enforced in CI on Ubuntu + macOS):

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

Or via the Makefile:

make check   # fmt + clippy + test

Tests

  • Fast suite (make test / cargo test) — unit tests plus CLI integration tests that drive the built binary in temp dirs using the custom engine. No external services.

  • Live-service suite (make e2e) — real Postgres/MySQL round-trips and a real S3 push/pull (incl. multipart) against MinIO, gated behind the docker_e2e feature so the fast suite never needs Docker:

    make e2e-up          # docker compose: postgres + mysql + minio
    make e2e             # cargo test --features docker_e2e
    make e2e-down
    

CI runs both suites on every push/PR.

Conventions

  • One logical change per commit.
  • A bug fix gets a failing-then-passing test.
  • New engines require a unit test for param resolution; a round-trip integration test is the bar for merge.

Contributing a new engine

bocal ships postgres and mysql as built-ins; everything else is reachable today via the custom engine. Promote a custom recipe to a built-in only when it clears the bar: the engine is widely used, its dump/restore is stable across versions, and its tooling is something users already have installed.

The flow — open an issue first, then implement:

  1. Open an issue describing the engine and the exact save/restore commands you'd run by hand. Maintainers confirm it clears the bar before you write code.

  2. Implement the Engine trait in a new file under src/engines/ (e.g. src/engines/mongodb.rs). The trait — the same contract the built-in engines satisfy:

    #![allow(unused)]
    fn main() {
    pub trait Engine {
        fn name(&self) -> &'static str;              // the engine = "..." identifier
        fn dump_file(&self) -> &str;                 // default dump filename in the tag dir
        fn save(&self, ctx: &EngineContext) -> Result<()>;
        fn restore(&self, ctx: &EngineContext) -> Result<()>;
        fn probe_version(&self, ctx: &EngineContext) -> Result<Option<String>> { Ok(None) }
        fn probe_client_version(&self, ctx: &EngineContext) -> Result<Option<String>> { Ok(None) }
        fn check_target(&self, ctx: &EngineContext) -> Result<()> { Ok(()) }
        fn required_tools(&self, ctx: &EngineContext) -> Vec<String> { Vec::new() }
    }
    }

    EngineContext carries the resolved host/port, user/dbname resolution (flags → env → defaults, same pattern as postgres/mysql), the tag directory, and the fixture name/tag.

  3. Register it in engines::for_service() so engine = "<name>" resolves.

  4. Document it — add a subsection to Engines with the exact save/restore commands and the params it resolves.

  5. Test — a unit test for param resolution, and a round-trip integration test (save → wipe → restore → assert). Gate live-service tests behind the docker_e2e feature like the existing ones.

Guidance

Prefer streaming over the wire (e.g. mongodump --archive | gzip) over reading files off a container's disk — it works identically whether the service runs on the host or in Docker, needs no service restart, and keeps the "bocal does not manage services" boundary intact.