Snapshot Workflow

Overview

The core Clonit workflow follows a Build -> Load pattern:

1. Build – Create a snapshot from a source database using pg_dump
2. Load – Restore a snapshot to a destination database using pg_restore or psql

This two-step approach lets you capture a point-in-time copy of your database and restore it wherever you need it – a local development environment, a staging server, or a teammate’s machine.

Build

The build command creates a snapshot of the source database configured on a target.

clonit build <target>

Under the hood, Clonit invokes pg_dump in directory format, which supports parallel dumping and selective restore.

Options

Flag	Description
--jobs	Number of parallel dump jobs. Set to 0 to use the target or config default.
--no-push	Skip automatic push to storage after build.

Auto-push to storage

If the target has a storage profile linked, the build command automatically pushes the snapshot to cloud storage after a successful build. This is enabled by default and can be disabled per-invocation with --no-push or globally with defaults.auto_push: false in the config file. See configuration for details.

Storage layout

Snapshots are stored in the working directory (~/.clonit by default) organized by target name and snapshot name:

~/.clonit/
  <target-name>/
    <snapshot-name>/
      ... (directory-format dump files)

Each snapshot record tracks the following metadata:

• Name – unique identifier for the snapshot
• Filename – path to the snapshot directory
• Type – the snapshot type (e.g., snapshot or sanitized)
• Size – total size of the snapshot on disk
• Created – timestamp when the snapshot was created

Load

The load command restores a snapshot to the destination database configured on the target. The target must have a dst_url configured.

There are three modes of loading:

Load the latest snapshot

clonit load <target>

Restores the most recent snapshot for the given target.

Load a specific snapshot by index

clonit load <target> <index>

Restores the snapshot at the given index. Use the snapshots command (described below) to see available indices.

Load a raw SQL file

clonit load <target> /path/to/file.sql

Executes a raw SQL file directly against the destination database using psql, bypassing the snapshot store entirely.

Restore behavior

• Directory-format snapshots are restored with pg_restore.
• SQL files are executed with psql.
• The --jobs flag controls the number of parallel restore jobs (applies to pg_restore only).

Listing Snapshots

To see what snapshots are available for a target, use:

clonit snapshots <target>

This displays a table with the following columns:

Column	Description
Index	Numeric index used to reference the snapshot in other commands
Name	Unique snapshot identifier
Type	Snapshot type (snapshot, sanitized, etc.)
Size	Size on disk
Created	Creation timestamp

Example End-to-End Workflow

1. Add a target

clonit targets add \
  --name mydb \
  --src-url "postgres://user:pass@prod-host:5432/mydb" \
  --dst-url "postgres://user:pass@localhost:5432/mydb_dev"

2. Build a snapshot from the source database

clonit build mydb --jobs 4

3. List available snapshots

clonit snapshots mydb

Example output:

Index  Name                          Type      Size      Created
0      mydb-20260208T120000          snapshot  245 MB    2026-02-08 12:00:00

4. Load the snapshot to the destination database

clonit load mydb

Or load a specific snapshot by index:

clonit load mydb 0

5. Verify the restored database

Connect to the destination database and confirm the data is present:

psql "postgres://user:pass@localhost:5432/mydb_dev" -c "SELECT count(*) FROM users;"