Command reference

Every sluice command, its purpose, the flags that matter most, and worked examples.

The general shape is sluice <command> [flags]. Every command accepts the global flags (--config, --log-level, …). Run sluice <command> --help for the complete flag list — the tables below cover the flags you'll reach for most.

engines

sluice engines

List the database engines built into this binary and their bulk-load / CDC capabilities.

sluice engines

migrate

sluice migrate

Run a one-time schema + data migration: translate the schema, create tables, bulk-copy rows, then build indexes and constraints.

Flag	Purpose
`--source-driver` / `--source`	Source engine name and DSN (or `SLUICE_SOURCE`).
`--target-driver` / `--target`	Target engine name and DSN (or `SLUICE_TARGET`).
`--dry-run`, `-n`	Print the plan; don't touch the target.
`--include-table` / `--exclude-table`	Glob-aware table filters (mutually exclusive).
`--resume`, `-r`	Resume a failed migration from per-table checkpoints on the target.
`--bulk-parallelism`	Parallel reader/writer pairs per large table (0 = auto).
`--type-override`	`TABLE.COLUMN=TYPE` — force a target column type (repeatable).
`--redact`	Redact a PII column, e.g. `users.email=hash:sha256` (repeatable).
`--target-schema`	Postgres-only: land tables under a named schema namespace.
`--reset-target-data`	Destructive recovery: drop source-schema tables on the target, then cold-start. Prompts unless `--yes`.

Filtered dry run, then apply:

sluice migrate --source-driver mysql --source ... --target-driver postgres --target ... \
    --include-table 'app_*' --exclude-table 'app_audit' --dry-run

Redact PII as it copies:

sluice migrate --source-driver mysql --source ... --target-driver postgres --target ... \
    --redact users.email=hash:sha256 \
    --redact users.ssn=mask:ssn

sync start

sluice sync start

Start (or resume) a continuous-sync stream: consistent snapshot → bulk copy → ongoing CDC. Identified by --stream-id for clean restart.

Flag	Purpose
`--stream-id`	Stream identifier; the key its position is persisted under on the target.
`--slot-name`	Postgres replication-slot suffix (default `sluice_slot`); set per-instance to run several streams off one source.
`--apply-batch-size`	CDC changes per target tx, or `auto`. Default `1` (conservative); higher engages the AIMD latency controller.
`--metrics-listen`	Bind a Prometheus `/metrics` + `/readyz` endpoint, e.g. `:9090`.
`--source-heartbeat-interval`	Write a heartbeat row on the source every interval so the slot/binlog can't be evicted past the consumer against an idle source.
`--dry-run`, `-n`	Show cold-start vs warm-resume and the planned actions without starting.
`--schema-already-applied`	Skip all cold-start DDL (you promise the target catalog matches). For Atlas/Liquibase-managed or PlanetScale Safe-Migrations targets.

Run as a service with metrics + idle-source heartbeat:

sluice sync start --source-driver postgres --source ... --target-driver mysql --target ... \
    --stream-id reporting \
    --metrics-listen :9090 \
    --source-heartbeat-interval 30s

sync status / stop / health

sluice sync status · stop · health

Inspect, gracefully stop, and health-check a running stream. All take --stream-id plus the target connection.

sync status — show the stream's persisted position and phase.
sync stop — request the stream to drain in-flight changes and exit cleanly.
sync health — probe freshness against thresholds and return a cron-friendly exit code (non-zero when stale).

sluice sync health --stream-id app-prod --target-driver postgres --target ... \
    --max-lag 5m   # exit non-zero if the stream is more than 5 minutes behind

sync from-backup

sluice sync from-backup run · stop

Replay a backup chain into a target as a long-running broker — polls a chain root (S3/GCS/Azure/local) for new incrementals and applies them. No direct source↔target connectivity required.

sluice sync from-backup run \
    --backup-target s3://my-bucket/app-chain \
    --target-driver postgres --target ... \
    --stream-id app-broker --poll-interval 30s

sluice sync from-backup stop --backup-target s3://my-bucket/app-chain

cutover

sluice cutover

Two-phase sequence priming at cutover: re-read source sequence / AUTO_INCREMENT state and apply it to the target with a safety margin, so the first post-cutover INSERT can't collide on the primary key.

sluice cutover --config sluice.yaml --cutover-sequence-margin 1000

Run after the snapshot has caught up and just before switching application traffic to the target.

backup

sluice backup

Take and verify logical backups — full snapshots and incremental chains, optionally encrypted, to local FS or object storage.

Flag	Purpose
`--full`	Take a full snapshot (chain root).
`--incremental`	Append an incremental onto the existing chain.
`--stream`	Run as a long-lived process appending incrementals continuously.
`--verify`	Verify a backup / chain integrity.
`--prune` / `--compact`	Retention: drop or compact old chain segments.

sluice backup --full --source-driver postgres --source ... --backup-target s3://my-bucket/app-chain
sluice backup --incremental --source-driver postgres --source ... --backup-target s3://my-bucket/app-chain

restore

sluice restore

Restore a logical backup chain (full + every incremental up to the tail) into a target database.

sluice restore --from s3://my-bucket/app-chain \
    --target-driver postgres --target ...

Pair with sync start --resume-from-backup to resume CDC from the chain's tail without re-bulking.

trigger setup

sluice trigger setup

Install (or remove) the postgres-trigger engine's source-side state — slot-less CDC for managed Postgres that blocks logical replication.

Flag	Purpose
`--dsn`	Source Postgres DSN to install the trigger state into.
`--tables`	Tables to capture (default: all).
`--allow-polled-fingerprint`	Permit the non-superuser polled path when event triggers aren't grantable (e.g. Heroku).
`--capture-payload`	`full` (default) / `changed` / `minimal` — how much of each row the trigger records.

sluice trigger setup --dsn 'postgres://user:pass@host:5432/app' --allow-polled-fingerprint
# then stream with the trigger engine:
sluice sync start --source-driver postgres-trigger --source ... --target-driver mysql --target ... --stream-id app

schema preview / diff

sluice schema preview · diff

Inspect translation without moving data: print the target DDL sluice would emit, or diff a live target against what sluice would produce.

sluice schema preview --source-driver mysql --source ... --target-driver postgres
sluice schema diff    --source-driver mysql --source ... --target-driver postgres --target ...

verify

sluice verify

Compare data integrity between source and target — row counts by default, escalating to sampled or full per-row hashing.

Flag	Purpose
`--depth`	How thorough: counts vs sampled-row vs full hash comparison.
`--sample-rows-per-table` / `--sample-seed`	Sampling size and a deterministic seed.
`--strict-hash`	Require byte-identical per-row hashes.
`--format` / `--output`	Report format and output destination (for CI gating).

sluice verify --source-driver mysql --source ... --target-driver postgres --target ... --depth counts

matview refresh

sluice matview refresh

Refresh PostgreSQL materialized views on the target (PG-only). Handy as a scheduled job after a sync catches up.

sluice matview refresh --target-driver postgres --target ... --view reporting.daily_totals

slot list / drop

sluice slot list · drop

Manage source-side Postgres replication slots — list sluice-created slots, or drop an orphaned one left by an interrupted stream.

sluice slot list --source-driver postgres --source ...
sluice slot drop --source-driver postgres --source ... --slot-name sluice_slot

diagnose

sluice diagnose

Assemble an operator bundle (source/target capability + role state, debug-zip shape) to attach when filing an issue.

sluice diagnose --source-driver mysql --source ... --target-driver postgres --target ... --out ./sluice-diagnose.zip