Common Workflows

This guide covers the most common ways teams use Basecut in their day-to-day workflows.

Development: Pull Production Data Locally

Problem: Your local database has toy data (User 1, Test Order). You need realistic data to develop against production-like scenarios. Solution: Extract a subset of production data, anonymize PII, restore to your local database.

# basecut.yml
version: "1"
name: "dev-seed"
from:
  - table: users
    where: 'created_at > :since'
    params:
      since: '2024-01-01'  # Recent users

traverse:
  parents: 5
  children: 10

limits:
  rows:
    per_table: 500  # Keep local DB manageable

anonymize:
  mode: auto

output:
  provider: s3
  bucket: my-team-snapshots
  region: us-east-1

Workflow:

# 1. Create snapshot (self-hosted agent extracts from production)
basecut snapshot create \
  --config basecut.yml \
  --name "dev-seed" \
  --async

# 2. Restore to local database
basecut snapshot restore dev-seed:latest \
  --target "postgresql://localhost:5432/myapp_dev"

# 3. Develop with realistic data
npm run dev

Tradeoffs:

✅ Real data shapes, edge cases, and patterns
✅ Everyone on the team has identical test data
❌ One-time snapshot—doesn’t auto-update as production changes

Tip: Schedule weekly snapshot creation in CI to keep dev data fresh.

Testing: CI Pipeline Integration

Problem: Your test suite runs against seeded fixtures that don’t match production schema or data complexity. Solution: Restore a production-like snapshot before running tests in CI.

# .github/workflows/test.yml
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v3

      - name: Install Basecut CLI
        run: |
          curl -fsSL https://basecut.dev/install.sh | sh
          echo "$HOME/.basecut/bin" >> $GITHUB_PATH

      - name: Restore Test Snapshot
        env:
          BASECUT_API_KEY: ${{ secrets.BASECUT_API_KEY }}
        run: |
          basecut snapshot restore test-data:latest \
            --target "postgresql://postgres:postgres@localhost:5432/test_db"

      - name: Run Tests
        run: npm test

Tradeoffs:

✅ Tests run against production-realistic data
✅ Catches schema mismatches early
❌ Slower CI (restore adds ~30s for typical snapshot)
❌ Tests may be less deterministic (use seed for consistency)

Tip: Create a dedicated test-data snapshot with fixed seed for reproducibility.

Debugging: Extract Data Around Specific Issue

Problem: A bug occurred in production for user ID 12345. You need their exact data state to reproduce locally. Solution: Extract just that user and their related data.

# debug-user-12345.yml
version: "1"
name: "debug-user-12345"
from:
  - table: users
    where: 'id = :user_id'
    params:
      user_id: 12345

traverse:
  parents: 10   # Grab all parent data
  children: 10 # Grab all child data

# No limits—get everything related to this user
limits:
  rows:
    per_table: 0  # unlimited

anonymize:
  # Minimal anonymization for debugging
  mode: manual
  rules:
    '*.credit_card': fake_credit_card

Workflow:

# 1. Extract the specific user's data
basecut snapshot create \
  --config debug-user-12345.yml \
  --name "debug-user-12345" \
  --source "postgresql://readonly@prod-db:5432/myapp"

# 2. Restore to local debug environment
basecut snapshot restore debug-user-12345:latest \
  --target "postgresql://localhost:5432/debug_db"

# 3. Reproduce the bug locally
node scripts/reproduce-bug.js --user-id 12345

Tradeoffs:

✅ Exact production state causing the bug
✅ No production access needed for debugging
❌ May expose PII (use full anonymization if sharing externally)

Tip: Delete the snapshot after debugging to avoid accumulating one-off extractions.

Problem: Integration partner needs sample data that matches your production API schema and data patterns. Solution: Create a curated snapshot with heavy anonymization.

# partner-sample.yml
version: "1"
name: "partner-sample"
from:
  - table: accounts
    where: 'plan = :plan'
    params:
      plan: 'enterprise'  # Show enterprise features

traverse:
  parents: 5
  children: 10

limits:
  rows:
    per_table: 100  # Manageable size for partners

anonymize:
  mode: auto
  rules:
    accounts:
      company_name: fake_company
      api_key: hash
    api_logs:
      request_body: redact
      response_body: redact

output:
  provider: s3
  bucket: partner-shared-data
  region: us-east-1

Workflow:

# 1. Create partner-safe snapshot
basecut snapshot create \
  --config partner-sample.yml \
  --name "partner-sample-v1"

# 2. Share access to the snapshot
# Option A: Generate pre-signed S3 URL (time-limited)
# (Resolve storage key with `basecut snapshot inspect` first)
aws s3 presign s3://partner-shared-data/<storage-key>/manifest.json \
  --expires-in 604800  # 7 days

# Option B: Partner uses their own Basecut account to restore
# (Give them the snapshot name and bucket access)

Tradeoffs:

✅ Partners get realistic API response shapes
✅ All PII anonymized for compliance
❌ Static snapshot—may drift from current API
❌ Requires partner to have Basecut CLI (or extract manually)

Team Onboarding: Consistent Dev Environment

Problem: New developers spend hours seeding local databases with realistic data. Solution: Document the snapshot restore process in your README.

# README.md

## Local Development Setup

### 1. Install Dependencies
\`\`\`bash
npm install
\`\`\`

### 2. Start Local Database
\`\`\`bash
docker compose up -d postgres
\`\`\`

### 3. Restore Production-Like Data
\`\`\`bash
# Install Basecut CLI
curl -fsSL https://basecut.dev/install.sh | sh

# Login (or set BASECUT_API_KEY from 1Password)
basecut login

# Restore the latest dev snapshot
basecut snapshot restore dev-seed:latest \
  --target "postgresql://localhost:5432/myapp_dev"
\`\`\`

### 4. Run the App
\`\`\`bash
npm run dev
\`\`\`

You now have 10k realistic users, orders, and activity logs in your local database!

Tradeoffs:

✅ Onboarding takes minutes instead of hours
✅ Everyone has identical data (easier to help debug)
❌ Requires Basecut account for each developer

Schema Migration Testing

Problem: You’re changing your database schema. Will the migration work on production data shapes? Solution: Test migrations against a production-like snapshot.

# 1. Create snapshot of current production schema
basecut snapshot create \
  --config basecut.yml \
  --name "pre-migration-test" \
  --source "postgresql://readonly@prod-db:5432/myapp"

# 2. Restore to staging database
basecut snapshot restore pre-migration-test:latest \
  --target "postgresql://staging-db:5432/myapp"

# 3. Run migration on staging
npm run migrate

# 4. Verify migration succeeded
npm run test:integration

# 5. If successful, run migration on production
npm run migrate:production

Tradeoffs:

✅ Catch migration issues before production deployment
✅ Test with real data volumes and edge cases
❌ Doesn’t catch schema drift between snapshot and current prod

Tip: Snapshot production immediately before running the migration test.

Next Steps

CI/CD Integration

Detailed GitHub Actions, GitLab CI, and CircleCI examples

Snapshot Rules

Complete guide to PII protection strategies

Execution Modes

Choose between self-hosted agent and local execution

Troubleshooting

Debug common workflow issues

Getting Started

Core Concepts

Configuration

Workflows

Integrations

CLI Reference

Deployment

Reference

Common Workflows

Development: Pull Production Data Locally

Testing: CI Pipeline Integration

Debugging: Extract Data Around Specific Issue

Team Onboarding: Consistent Dev Environment

Schema Migration Testing

Next Steps

CI/CD Integration

Snapshot Rules

Execution Modes

Troubleshooting

​Development: Pull Production Data Locally

​Testing: CI Pipeline Integration

​Debugging: Extract Data Around Specific Issue

​Data Sharing: Realistic Datasets for Partners

​Team Onboarding: Consistent Dev Environment

​Schema Migration Testing

​Next Steps

CI/CD Integration

Snapshot Rules

Execution Modes

Troubleshooting

Development: Pull Production Data Locally

Testing: CI Pipeline Integration

Debugging: Extract Data Around Specific Issue

Data Sharing: Realistic Datasets for Partners

Team Onboarding: Consistent Dev Environment

Schema Migration Testing

Next Steps