Skip to main content
This guide walks you through creating your first production-realistic snapshot using local execution. Perfect for getting started quickly without deploying infrastructure.

​
What You’ll Accomplish

By the end of this guide, you’ll have:
  • ✅ A basecut.yml configuration file tailored to your database schema
  • ✅ A production-realistic snapshot with anonymized PII
  • ✅ A restored snapshot in your local development database
  • ✅ Understanding of the init → snapshot create → snapshot restore workflow
For production: After completing this guide, see Self-Hosted Agents for the recommended production deployment.

​
Prerequisites

  • PostgreSQL database (12+) with some data
  • Database accessible from your local machine (localhost or network-accessible)

​
Step 1: Install CLI

Install the Basecut CLI: 
curl -fsSL https://basecut.dev/install.sh | sh
basecut --version
Success indicator: basecut version x.y.z

​
Step 2: Authenticate

Create a Basecut account and authenticate: 
basecut login
This opens your browser for authentication. Once complete, your credentials are stored locally. Success indicator: ✓ Authenticated as you@example.com

​
Step 3: Generate Configuration

Point Basecut at your database to auto-detect schema and relationships: 
basecut init --source "postgresql://user:pass@localhost:5432/myapp"
What init does automatically: The init command does the heavy lifting for you:
  • 🔍 Schema detection: Analyzes all tables, columns, and data types
  • 🔗 FK analysis: Maps foreign key relationships to build the dependency graph
  • 🎯 Root table suggestions: Identifies good starting points (tables with many incoming FKs)
  • 🔄 Cycle detection: Finds and handles circular relationships
  • 🛡️ PII detection: Auto-detects common PII patterns (emails, phones, names, etc.)
  • 📝 Config generation: Creates a ready-to-use basecut.yml with sensible defaults
This creates basecut.yml in your current directory with:
  • Detected tables and foreign key relationships
  • Suggested root tables and FK connectivity details
  • Optional PII anonymization rules (email, phone, etc.)
Success indicator: ✓ Created basecut.yml with 42 tables detected
Troubleshooting init: If you see connection errors, verify your database is accessible and the connection string format is correct (postgresql://user:pass@host:port/dbname). For SSH tunnels or complex setups, ensure the database is reachable from your local machine.
# Auto-generated by basecut init
version: "1"
name: "my-snapshot"

from:
  - table: users
    where: 'created_at > :since'
    params:
      since: '2024-01-01'

traverse:
  parents: 10 # Follow parent relationships
  children: 2 # Follow child relationships

limits:
  rows:
    per_table: 1000 # Max rows per table
    total: 100000 # Max total rows

anonymize:
  mode: auto

output: ./snapshots

​
Step 4: Create a Snapshot (Local Execution)

Run the extraction locally (default): 
basecut snapshot create \
  --config basecut.yml \
  --name "my-first-snapshot" \
  --source "postgresql://localhost:5432/myapp_dev"
What’s happening:
  1. CLI reads your basecut.yml configuration
  2. Connects directly to your database from your machine
  3. Follows foreign keys from root tables to extract related data
  4. Applies anonymization rules to PII fields
  5. Stores snapshot on your local filesystem
Success indicator: 
⣾ Extracting... (0/42 tables)
✓ Extracted 2,847 rows across 23 tables
✓ Anonymized 312 PII fields
✓ Snapshot written to local output path: ./snapshots
Local is the default. Omit --async to run extraction on your machine without agent infrastructure.

​
Step 5: Restore the Snapshot

Apply the extracted data to a different database (or the same one for testing): 
basecut snapshot restore my-first-snapshot:latest \
  --target "postgresql://localhost:5432/myapp_test"
What’s happening:
  1. CLI reads snapshot from storage
  2. Validates target schema compatibility
  3. Inserts data in dependency order (respects foreign keys)
  4. Reports completion
Run migrations first. Restore does not create or alter tables.
Success indicator: 
✓ Loading snapshot: my-first-snapshot:latest
✓ Validated schema for 23 tables
✓ Inserted 2,847 rows
✓ Verified referential integrity
✓ Restore complete in 3.2s
Your local database now has a production-realistic subset with all PII safely anonymized.

​
Common Next Steps

Now that you’ve created your first snapshot, here’s what to explore next:

Customize Snapshot Rules

Add domain-specific PII protection rules and fine-tune anonymization strategies

Set Up CI/CD

Automate snapshot creation and restore in your CI pipeline for consistent test data

Deploy Agents for Production

Run snapshot extraction inside your VPC for production databases (TEAM plan)

Explore Workflows

Learn patterns for debugging, testing migrations, and sharing data with partners

​
Verify the Data

Check what was restored: 
-- See available tables
\dt

-- Count rows
SELECT
  relname AS table_name,
  n_live_tup::bigint AS estimated_rows
FROM pg_stat_user_tables
ORDER BY estimated_rows DESC;

-- Verify anonymization worked
SELECT email, phone FROM users LIMIT 5;
-- email                    | phone
-- ------------------------ | -------------
-- jane.doe42@example.com   | 555-0192
-- john.smith7@example.com  | 555-0847

​
Ready for Production?

You just completed a local execution quick start. For production workloads, deploy self-hosted agents:

Deploy on Railway

One-click managed deployment for a production-ready Basecut agent

Deploy Self-Hosted Agents

Next step for production: Deploy agents in Docker/Kubernetes (recommended)

Execution Modes

Understand agent vs local execution and when to use each

​
Customize Your Setup

Snapshot Rules

Add custom PII protection for your domain-specific fields

YAML Configuration

Fine-tune extraction depth, limits, and filters

CI/CD Integration

Automate snapshot creation in GitHub Actions

Common Workflows

Patterns for testing, debugging, and data sharing