Skip to content
CloneDB

Getting started

CloneDB is a single static binary. PostgreSQL is supported today (MySQL is planned behind the same driver interface).

Requires PostgreSQL 12 or newer on the source: CloneDB models declarative partitioning via pg_partition_tree and has no older-server fallback.

Install

Section titled “Install”

Install with Homebrew:

Terminal window
brew install clonedb/tap/clonedb

Quickstart

Section titled “Quickstart”

1. Generate a config

Section titled “1. Generate a config”

init is an interactive wizard — it connects, then walks you through choosing schemas, tables, and filters, and writes a clonedb.toml:

Terminal window
clonedb init

Picked the wrong thing? Choose ← Back (the first entry on each list prompt) to return to the previous question and revise it without losing earlier answers, or press Esc to cancel. See the CLI reference for the full navigation rules.

Prefer non-interactive (CI, scripting)? Use generate-config:

Terminal window
clonedb generate-config --schemas public --source "$SOURCE_DATABASE_URL"

2. Preview the plan

Section titled “2. Preview the plan”

See what a run would pull — per-table estimated row counts — before moving any data:

Terminal window
clonedb run --dry-run

These are fast planner estimates (rendered ~N) — --dry-run never scans rows. Each table shows a scoped count (trimmed to your seed closure) or a whole count (pulled entire because nothing connects it to a seed yet). A big whole count means wire that table up — add a virtual FK or a restriction. Treat the plan as a scope check, not an exact size — see the CLI reference for details.

3. Pull the subset

Section titled “3. Pull the subset”

Into a live dev database (idempotent upsert):

Terminal window
clonedb run --target "$DEV_DATABASE_URL"

…or to a portable SQL file:

Terminal window
clonedb run --output-sql subset.sql

4. Keep the config current

Section titled “4. Keep the config current”

After a migration adds tables, reconcile the config without losing your edits. By default sync-config only previews the diff — pass --write to apply it:

Terminal window
clonedb sync-config           # preview the changes
clonedb sync-config --write   # apply them, preserving your edits and comments

Next steps

Section titled “Next steps”