> ## Documentation Index > Fetch the complete documentation index at: https://docs.basecut.dev/llms.txt > Use this file to discover all available pages before exploring further. # Common Workflows > Real-world patterns for using Basecut in development, testing, and debugging 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. ```yaml theme={null} # 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**: ```bash theme={null} # 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. ```yaml theme={null} # .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. ```yaml theme={null} # 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**: ```bash theme={null} # 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. *** ## Data Sharing: Realistic Datasets for Partners **Problem**: Integration partner needs sample data that matches your production API schema and data patterns. **Solution**: Create a curated snapshot with heavy anonymization. ```yaml theme={null} # 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**: ```bash theme={null} # 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//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. ```markdown theme={null} # 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. ```bash theme={null} # 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 Detailed GitHub Actions, GitLab CI, and CircleCI examples Complete guide to PII protection strategies Choose between self-hosted agent and local execution Debug common workflow issues