build
Create a snapshot of the source database.
clonit build <target> [flags]Arguments
Section titled “Arguments”| Argument | Description | Required |
|---|---|---|
target |
Name of the target to snapshot | Yes |
| Flag | Type | Default | Description |
|---|---|---|---|
--jobs |
int | 0 |
Number of parallel dump jobs (0 = use target default) |
--no-push |
bool | false |
Skip automatic push to storage after build |
Description
Section titled “Description”Creates a new snapshot of the target’s source database using pg_dump in directory format. The snapshot is stored in the configured working directory (~/.clonit by default).
The --jobs flag controls the number of parallel dump jobs. When set to 0, the target’s configured dump_jobs value is used. If that is also 0, pg_dump uses its own default.
Auto-push
Section titled “Auto-push”After a successful build, Clonit automatically pushes the snapshot to cloud storage. The same auto-push applies to every snapshot-producing command – sanitize and ephemeral auto-push their sanitized snapshots too. A push happens if:
- The target has a storage profile linked for that snapshot type (see the per-type rule below)
- The
defaults.auto_pushconfig option istrue(the default) - The
--no-pushflag is not set (available onbuild,sanitize, andephemeral)
Strict per-type rule. Original snapshots (from build) push to the target’s storage profile (--storage-profile); sanitized snapshots (from sanitize/ephemeral) push only to the target’s sanitized storage profile (--sanitized-storage-profile). There is no fallback between the two: if the matching profile is not configured, the snapshot silently stays local. (Manual clonit push keeps its legacy sanitized-to-original fallback.)
Non-fatal. If the push fails, a warning is printed but the command exits successfully – the snapshot is still available locally and can be retried with clonit push <target>.
Validation gate. A sanitized snapshot whose --validate report failed (sensitive values still present) is never auto-pushed – it stays local with a warning until you fix the query or push it manually. A report with status error (validation could not run, e.g. the sanitized database was unreachable) keeps the snapshot local the same way – only a passed or skipped report (or no report at all) pushes. The gate is fail-closed: an unreadable report, or a failed report that could not be written to the local database, still blocks the push.
To disable auto-push globally, set defaults.auto_push: false in the config file or CLONIT_DEFAULTS_AUTO_PUSH=false in the environment. Builds and ephemeral runs triggered from the web UI follow the same config gate.
Examples
Section titled “Examples”Build a snapshot using target defaults:
clonit build mydbBuild a snapshot with 8 parallel dump jobs:
clonit build mydb --jobs 8Build without auto-pushing to storage:
clonit build mydb --no-pushBuild with debug output:
clonit --debug build production-snap