YAML Reference

The basecut.yml file defines what Basecut extracts, how traversal is bounded, how PII is anonymized, and where output is written.

Complete Example

version: '1'
name: 'my-snapshot'

from:
  - table: users
    where: 'id = :id'
    params:
      id: 42
  - table: billing.invoices
    where: 'org_id = :org_id'
    params:
      org_id: 10

exclude:
  - audit_logs
  - internal_tokens

include_all:
  - countries
  - currencies

traverse:
  parents: 10
  children: 2
  stop_at:
    - user_roles
    - order_tags

virtual_foreign_keys:
  - from: posts.author_id
    to: users.id
  - from:
      table: billing.invoice_items
      columns: [invoice_id, tenant_id]
    to:
      table: billing.invoices
      columns: [id, tenant_id]

limits:
  rows:
    per_table: 1000
    total: 100000
    tables:
      events: 200
      logs: 0

sampling:
  mode: random
  seed: 42

anonymize:
  mode: auto
  excluded_domains:
    - yourcompany.com
  rules:
    users:
      email: fake_email
      phone: fake_phone
    '*.password_hash': redact

output: ./snapshots
# Or object form:
# output:
#   provider: s3
#   bucket: my-team-snapshots
#   region: us-east-1

Top-Level Fields

Field	Required	Type	Description
`version`	Yes	string	Config version. Must be `'1'`.
`name`	No	string	Snapshot name fallback used by CLI if `--name` is not provided.
`from`	Yes	array	One or more root selectors to start extraction.
`exclude`	No	array	Tables to exclude entirely from extraction.
`include_all`	No	array	Lookup/reference tables extracted in full before traversal.
`traverse`	No	object	Traversal controls (`parents`, `children`, `stop_at`).
`virtual_foreign_keys`	No	array	User-defined FK edges for relationships not declared in DB constraints.
`limits`	No	object	Row-count budgets and overrides.
`sampling`	No	object	Row selection mode and random seed.
`anonymize`	No	string/object	`off`, `auto`, or object with `mode` + `rules`.
`output`	Yes	string/object	Output destination (`./path`, `s3://...`, `gs://...`, or provider object).

`from`

from defines the starting rows.

from:
  - table: users
    where: 'id = :id'
    params:
      id: 1

Use table: users for public.users.
Use table: schema.table for non-public schemas.
where supports named params (:id), values go in params.

`traverse`

traverse:
  parents: 10
  children: 2
  stop_at:
    - user_roles

Field	Type	Default	Description
`parents`	int	`10`	Max parent FK depth (`-1` = unlimited).
`children`	int	`2`	Max child FK depth (`0` = disable downstream traversal).
`stop_at`	array	-	Junction/link tables where FK expansion should stop.

`virtual_foreign_keys`

Use virtual_foreign_keys when related tables are enforced in application code but not declared as database FK constraints. Single-column (compact) form:

virtual_foreign_keys:
  - from: posts.author_id
    to: users.id
  - from: comments.post_id
    to: public.posts.id

Composite-column (structured) form:

virtual_foreign_keys:
  - from:
      table: billing.invoice_items
      columns: [invoice_id, tenant_id]
    to:
      table: invoices
      columns: [id, tenant_id]

Notes:

Virtual FK edges are traversed the same way as real FKs during extraction.
Bare table names are normalized to public.<table>.
Compact endpoints must be table.column or schema.table.column.
from.columns and to.columns must have the same number of columns.
Duplicate virtual FK definitions are rejected.

`limits.rows`

limits:
  rows:
    per_table: 1000
    total: 100000
    tables:
      users: 200
      audit_logs: 0

Field	Type	Default	Description
`per_table`	int	`1000`	Default row-count cap per table.
`total`	int	`100000`	Total row-count cap across the snapshot.
`tables`	map[string]int	-	Per-table row-count overrides (`0` means unlimited for that table; use `exclude` to skip extraction).

Cycle handling: When tables form circular foreign key relationships (cycles), Basecut automatically caps the combined row count for the cycle group based on the sum of effective table limits. For example, if three tables in a cycle each have per_table: 1000, the cycle budget is 3000 total rows. Adjust per_table or add individual tables entries to control cycle sizes.

`anonymize`

Shorthand:

anonymize: auto

Object form:

anonymize:
  mode: manual # auto | manual | off
  excluded_domains: # optional: global email domains to skip anonymization
    - company.com
    - test.example.com
  rules:
    users:
      email: fake_email
    partners:
      email:
        strategy: fake_email
        params:
          excluded_domains: [partner.org]  # per-rule: replaces global list for this rule
    audit_logs:
      email:
        strategy: fake_email
        params:
          excluded_domains: []  # explicit empty: anonymize ALL emails, ignore global list
    '*.password_hash': redact

Notes:

mode: auto enables built-in PII auto-detection plus explicit rules.
mode: manual applies only explicit rules.
mode: off disables anonymization.
Table-grouped rule keys can be unqualified (users) for public.users.
excluded_domains (top-level) is an optional list of email domains that bypass anonymization. Emails matching these domains (case-insensitive, exact match) are left unchanged, whether the email strategy was set via explicit rules or auto-detection. Useful for preserving internal/test emails like @yourcompany.com.
Per-rule params.excluded_domains overrides the global list for that specific rule. If present (even as an empty list), the global excluded_domains are ignored for that rule. A rule without params.excluded_domains inherits the global list.

`output`

String shorthand:

output: ./snapshots
# output: s3://my-bucket/team-a
# output: gs://my-bucket/team-a

Object form:

output:
  provider: local # local | s3 | gcs
  path: ./snapshots

For cloud providers:

output:
  provider: s3
  bucket: my-bucket
  region: us-east-1
  endpoint: https://<accountid>.r2.cloudflarestorage.com # optional for S3-compatible backends
  prefix: team-a/snapshots

Notes:

For provider: s3, bucket is required.
For Cloudflare R2, use provider: s3 + endpoint and set region: auto.

Minimal Config

version: '1'

from:
  - table: users
    where: 'id = :id'
    params:
      id: 1

anonymize: auto
output: ./snapshots

Getting Started

Core Concepts

Configuration

Workflows

Integrations

CLI Reference

Deployment

Reference

Complete Example

Top-Level Fields

`from`

`traverse`

`virtual_foreign_keys`

`limits.rows`

`anonymize`

`output`

Minimal Config

​Complete Example

​Top-Level Fields

​from

​traverse

​virtual_foreign_keys

​limits.rows

​anonymize

​output

​Minimal Config

Complete Example

Top-Level Fields

`from`

`traverse`

`virtual_foreign_keys`

`limits.rows`

`anonymize`

`output`

Minimal Config