subset

Extract a subset of a target’s source database into a loadable SQL file.

Usage

clonit subset <target> [flags]

Arguments

Argument	Description	Required
`target`	Name of the target whose source database to subset	Yes

Flags

Flag	Type	Default	Description
`--root`	stringArray	–	Root table to seed the subset (repeatable; pairs with `--filter` by position)
`--filter`	stringArray	–	WHERE filter for the corresponding `--root` (repeatable)
`--with-dependents`	bool	`false`	Also follow inbound foreign keys (pull child rows)
`--limit`	int	`0`	LIMIT applied to a single root selection
`--include`	stringArray	–	Restrict subsetting to this table (repeatable; overrides target config)
`--exclude`	stringArray	–	Exclude this table from subsetting (repeatable; overrides target config)
`--schema-only`	bool	`false`	Emit schema DDL only (no row data)
`--data-only`	bool	`false`	Emit row data only (no schema DDL)
`--output`	string	–	Output `.sql` path (default: working dir)

Description

Extracts a subset of a target’s source database by selecting rows from one or more root tables and following foreign keys outward to every referenced parent row, producing a SQL file that loads into a fresh database with referential integrity intact.

Roots are given as repeated --root/--filter pairs, matched by position. Each --root names a table to seed the subset, and the --filter in the same position supplies a WHERE clause that selects the seed rows from that table.

By default, the subset follows foreign keys outward — for every selected row, every parent row it references is included so the result has no dangling references. Add --with-dependents to also follow inbound foreign keys and pull child rows that reference the selected rows (for example, each selected customer’s orders), not just their parents.

Use --include or --exclude to restrict or trim which tables participate in subsetting; these override the target’s configuration. Control the output shape with --schema-only (DDL only) or --data-only (rows only), and choose where the .sql file is written with --output (it defaults to the working directory).

Examples

Grab five customers and everything they reference:

clonit subset mydb --root customer --filter "customer_id <= 5"

Also pull the dependent child rows (for example, each customer’s orders):

clonit subset mydb --root customer --filter "customer_id <= 5" --with-dependents

Seed from multiple root tables (each --root pairs with the --filter in the same position):

clonit subset mydb \
  --root customer --filter "region = 'us-west'" \
  --root product  --filter "active = true"

Cap a single root selection with a row limit:

clonit subset mydb --root events --filter "created_at >= '2026-01-01'" --limit 1000

Restrict subsetting to specific tables, overriding the target config:

clonit subset mydb --root customer --filter "customer_id <= 5" \
  --include customer --include orders

Emit only the schema DDL (no row data):

clonit subset mydb --root customer --filter "customer_id <= 5" --schema-only

Write the subset to a specific path:

clonit subset mydb --root customer --filter "customer_id <= 5" \
  --output /tmp/customer-subset.sql