ephemeral

Run sanitization in a disposable Docker container without a pre-configured destination database.

Usage

clonit ephemeral <target> [snapshot_index] [flags]

Arguments

Argument	Description	Required
`target`	Name of the target to sanitize	Yes
`snapshot_index`	Index of the snapshot to use	No (defaults to latest)

Flags

Flag	Type	Default	Description
`--build`	bool	`false`	Build a fresh original snapshot from the live source database first (see Build-new)
`--fast`	bool	`false`	Skip debug/analysis steps
`--image`	string		Override Docker image (e.g., `postgres:16`)
`--query-id`	string		Use specific sanitize query ID
`--validate`	bool	`false`	Validate the sanitized data in-container and fail the command if sensitive values remain (see Validation)
`--no-push`	bool	`false`	Skip the automatic push of the sanitized snapshot to storage (see Auto-push)

Description

Runs the sanitization pipeline inside an ephemeral Docker container, eliminating the need for a pre-configured sanitize destination database (sanitize_dst_url). Docker must be running.

The command performs the following steps:

Resolve an existing source snapshot – or, with --build, build a fresh original snapshot from the live source database
Start an ephemeral PostgreSQL container
Load the snapshot into the container
Execute the sanitization query
Dump the sanitized database to a new snapshot
Stop and remove the container

The --fast flag skips the debug/analysis steps that otherwise run on failure. Use --image to override the PostgreSQL image used for the ephemeral container, and --query-id to select a specific sanitize query instead of the active one.

The web UI at /targets/{id} shows real-time step progress and maintains a history of ephemeral runs with retry support. The same history and replay are available from the CLI via the list, show, and replay subcommands below.

Build-new (one-step snapshot + sanitize)

--build turns the run into a one-step “build a new original snapshot, then sanitize it” pipeline: the build_snapshot step dumps the live source database into a fresh original snapshot (exactly like build) and immediately sanitizes it. This works on a target with zero snapshots – you no longer need a separate clonit build before the first ephemeral run.

--build cannot be combined with a snapshot_index argument – it always builds a fresh original.
A build failure is recorded as a failed build_snapshot step on the run (with the usual history/retry support), not a pre-run error. The recorded step carries a generic message; the full builder error (which may reference the source connection URL) is written to the agent log only.
The built original records the run’s lineage: the sanitized snapshot’s source is the freshly built original.
Read-only targets are refused (the sanitize half of the pipeline already forbids them). The web UI’s “Build new original snapshot” option is likewise disabled for read-only targets.
With auto-push enabled, both snapshots push per the strict per-type rule: the built original to the target’s original storage profile (as clonit build would) and the sanitized result to the sanitized profile; --no-push suppresses both.

In the web UI, choose “Build new original snapshot (from live source DB)” in the ephemeral dialog’s Source Snapshot selector for the same behaviour.

Validation report

With --validate, clonit validates the sanitized data inside the ephemeral container, before it is torn down. It loads the target’s latest completed analyze run and, for every column that analysis flagged as sensitive, samples up to 1000 values and runs pure-pattern detectors (email, phone, SSN, credit card, IPv4). The behaviour matches sanitize --validate:

Opt-in. Runs only when --validate is passed. Unlike --fast’s effect on stats, validation runs even when --fast is also set — you asked for it.
Counts only. The report records per-column match counts and detector names only; a matched value is never printed, logged, or stored.
Exit-code contract (CI gate). The sanitized snapshot is always produced; failed (matches found) exits non-zero and prints a violations table, skipped (no completed analysis) and error (validation could not run) print a warning and exit 0, and passed exits 0.

The report is persisted on the produced snapshot and shown in the web UI’s snapshot detail view. Whether the run validated is recorded on the run itself (shown by ephemeral show), and ephemeral replay re-runs validation for a run that validated – the gate is part of the recorded parameters and is never silently dropped on replay.

Auto-push

After a successful run – once the container has been torn down – the produced sanitized snapshot is automatically pushed to the target’s sanitized storage profile (--sanitized-storage-profile on targets add/update) when defaults.auto_push is true (the default) and --no-push is not set. The rule is strictly per-type: without a sanitized profile the snapshot silently stays local (no fallback to the target’s original profile).

Validation gate. If --validate ran and the report failed, the snapshot is not pushed – it stays local with a warning.
Non-fatal. A push failure prints a warning but the run still completes; retry with clonit push <target>.

Ephemeral runs started from the web UI follow the same config gate, and ephemeral replay auto-pushes under the same rules (pass replay --no-push to keep the replayed run’s snapshots local). See build – Auto-push for the shared rules.

Subcommands

`ephemeral list`

clonit ephemeral list [target] [flags]

Lists recorded ephemeral runs, newest first. With no argument, runs across all targets are shown; pass a target name to restrict the list to that target.

Flag	Type	Default	Description
`--limit`	int	`20`	Maximum number of runs to show (`0` for no limit)

The output table includes the following columns:

Column	Description
Run ID	First 8 characters of the run ID (use with `show`/`replay`)
Target	Target name (or the raw target ID if the target was deleted)
Status	`pending`, `running`, `completed`, `failed`, or `cancelled`
Step	The failed step for a failed run, otherwise the current/last step
Sanitized	Short ID of the sanitized snapshot the run produced, or `-`
Created	Timestamp when the run started

`ephemeral show`

clonit ephemeral show <run-id>

Shows the full details and per-step breakdown (step, status, duration, and detail/error) of a single run. The run may be identified by its full ID or an unambiguous ID prefix; an ambiguous prefix is rejected.

`ephemeral replay`

clonit ephemeral replay <run-id> [flags]

Starts a new ephemeral run using a prior run’s recorded parameters (source snapshot, sanitize query, fast mode, validation, and Docker image). The run may be identified by its full ID or an unambiguous ID prefix.

Flag	Type	Default	Description
`--build`	bool	`false`	Build a fresh original snapshot instead of reusing the recorded source snapshot
`--no-push`	bool	`false`	Skip the automatic push of the replayed run’s snapshots to storage (see Auto-push)

Only failed or completed runs can be replayed; pending, running, and cancelled runs are refused. Replaying a completed run intentionally produces a new run and a new sanitized snapshot.

A replay reproduces the recorded run: for a --build run that completed its build, the replay reuses the exact original it built (recorded as the run’s source snapshot) rather than building again – pass --build to build a fresh one instead. A --build run that failed during the build recorded no source snapshot, so its replay (and the web UI’s Retry) builds again automatically instead of silently falling back to the latest snapshot.

If the original run validated (--validate), its replay re-runs validation against the fresh sanitized snapshot, with the same report and exit-code contract – a run whose validation FAILED cannot be laundered into a pushable snapshot by replaying it. (The web UI’s Retry refuses runs that validated; replay those from the CLI.)

Examples

Run ephemeral sanitization on the latest snapshot using the active query:

clonit ephemeral mydb

Use a specific snapshot by index:

clonit ephemeral mydb 0

Skip the debug analysis steps:

clonit ephemeral mydb --fast

Sanitize and fail if any flagged column still contains sensitive data (CI gate):

clonit ephemeral mydb --validate

Build a fresh original snapshot and sanitize it in one step (works even with no existing snapshots):

clonit ephemeral mydb --build

Override the Docker image:

clonit ephemeral mydb --image postgres:15

List recent ephemeral runs across all targets:

clonit ephemeral list

List runs for a single target:

clonit ephemeral list mydb

Inspect a run by ID prefix:

clonit ephemeral show 3f9a1c2b

Replay a previous run with its recorded parameters:

clonit ephemeral replay 3f9a1c2b

Replay a previous run but build a fresh original snapshot first:

clonit ephemeral replay 3f9a1c2b --build