Operating dbmazz with the ez-cdc CLI

The ez-cdc CLI wraps dbmazz in a Docker-based developer experience: one command spins up a demo pipeline, another connects your own databases, and a live dashboard shows throughput, snapshot progress and LSN in real time.

The CLI and the daemon ship as two independent artifacts. The CLI targets Linux and macOS (amd64 and arm64); the daemon runs inside Docker on that same host.

Install

curl -sSL https://raw.githubusercontent.com/ez-cdc/ez-cdc-cli-releases/main/install.sh | sh

The script drops the binary into ~/.local/bin/ez-cdc (or /usr/local/bin/ez-cdc if you run it as root). Verify:

ez-cdc --version

Try the demo

The fastest way to see dbmazz end-to-end is the bundled demo stack. It boots a Postgres source pre-seeded with data, a Postgres sink, wires dbmazz against them, and opens the live dashboard:

ez-cdc quickstart --demo

That single command:

1. Starts the demo source and sink containers (Postgres + Postgres).
2. Runs dbmazz against them in Docker.
3. Opens the dashboard on the running daemon.

Inside the dashboard:

• t — generate live traffic (inserts, updates, deletes).
• q — detach from the dashboard. The daemon keeps running.

To tear the demo down when you're done:

ez-cdc demo down

Connect your own databases

Once you have your own PostgreSQL source and a sink (PostgreSQL, StarRocks, or Snowflake) reachable from the host, configure them through the datasource subcommands:

1. Initialize the config file

ez-cdc datasource init

Writes a commented ~/.config/ez-cdc/config.yaml template. You can also start from an empty file with --template blank or the in-repo demo config with --template demo.

2. Add a source and a sink

ez-cdc datasource add

An interactive wizard asks for connection details, runs a connectivity test against the database, and appends the entry to your config file. Run it once for the source, once for the sink.

You can verify each entry later with:

ez-cdc datasource list
ez-cdc datasource test <name>

3. Run the pipeline

ez-cdc quickstart --source my-pg --sink my-warehouse

Same flow as the demo, just pointed at your datasources. The dashboard comes up once dbmazz has completed the initial snapshot and is streaming CDC events.

Operating a running daemon

Command	Action
ez-cdc status	Stage, LSN, throughput snapshot from the daemon
ez-cdc dashboard	Reattach the live dashboard on the running daemon
ez-cdc logs	Tail the dbmazz container logs
ez-cdc stop	Stop and remove the dbmazz container (graceful drain)
ez-cdc run	Start + tail logs in one terminal (alternative to quickstart)
ez-cdc clean	Drop the replication slot and truncate target tables (test harness)

Verify the pipeline

The CLI includes a 13-check e2e verification suite covering schema, snapshot integrity, CDC INSERT / UPDATE / DELETE, TOAST handling, NULL roundtrip, and idempotency drift:

ez-cdc verify --source my-pg --sink my-warehouse
ez-cdc verify --source my-pg --sink my-warehouse --quick    # skip slow checks
ez-cdc verify --source my-pg --sink my-warehouse --json-report results.json

The JSON report is CI-friendly.

Advanced flags

Flag	Purpose
--dbmazz-image <ref>	Pin a specific dbmazz image (e.g. to test a local build). Also settable via DBMAZZ_IMAGE.
--http-port <port>	Publish the dbmazz control API on a custom host port (default 50051). Also DBMAZZ_HTTP_PORT.
--config <path>	Use a config file outside ~/.config/ez-cdc/.

Shell completions:

ez-cdc completions zsh  > "${fpath[1]}/_ez-cdc"
ez-cdc completions bash > ~/.local/share/bash-completion/completions/ez-cdc
ez-cdc completions fish > ~/.config/fish/completions/ez-cdc.fish

Troubleshooting

docker compose up failed: container ezcdc-dbmazz is unhealthy Most common cause is the daemon failing to connect to the source or sink. Check ez-cdc logs dbmazz for the first error line — usually wal_level, missing REPLICA IDENTITY, or a firewall blocking the sink port.

Cached compose.yml with the wrong image after passing --dbmazz-image Clear the compose cache and re-run:

rm -rf ~/.cache/ez-cdc/compose

The dashboard says uptime 0s That's a cosmetic lag in the first two poll ticks (~1 s). It settles on the real value after the container inspect lands.