Skip to main content
Basecut can execute snapshot creation in two modes. Both produce identical snapshots—the difference is where the processing happens. For production workloads, self-hosted agents are recommended. They provide better security (your credentials stay in your environment), better performance (same region as your database), and predictable costs.

​
Choose Your Execution Mode

Use this decision tree to select the right mode for your use case:

​
Quick Decision Guide

1. Do you have a self-hosted agent with network access to your source database?
  • No → Use Local Execution (default)
  • Yes → Continue
2. Are you working in production or with production-sized data?
  • Yes → Use Self-Hosted Agents (recommended for production)
  • No → Continue
3. Do you have self-hosted agents deployed?
  • No → Use Local Execution (default, no setup required)
  • Yes → Use Self-Hosted Agents (better performance and security)

​
Quick Reference

Default behavior: Local execution (no --async flag)
Deploy agents in your infrastructure to process extractions. Your CLI submits jobs to the Basecut API, self-hosted agents pick up the work, and results are stored in your configured S3/GCS bucket.

​
When to Use

  • Production databases - Agent runs in cloud environment with stable network and resources
  • Large extractions - Process millions of rows without consuming local CPU/memory
  • Team workflows - Centralized execution with job history and shared snapshots
  • CI/CD pipelines - No local database access needed—agent connects directly to your DB

​
How It Works

  1. CLI submits job to Basecut API with your configuration
  2. Self-hosted agent picks up the job from the queue
  3. Agent connects to your database (requires network access)
  4. Extraction runs on agent infrastructure
  5. Snapshot uploaded to configured cloud storage (S3/GCS)
  6. CLI polls for job status and reports completion
Storage: Always uses cloud storage (S3 or GCS) Requirements:
  • Agent needs network access to your database
  • Database credentials passed securely via config
  • Cloud storage bucket configured in basecut.yml

​
Configuration

--async is ignored when output.provider: local (agents can’t write to your local filesystem). In that case, Basecut runs locally and prints a warning.

​
Local Execution

The CLI runs extraction directly on your machine. Useful for development and databases without public access.

​
When to Use

  • No agent deployment yet - Start immediately with no infrastructure
  • DB reachable from your machine - Local dev DB, tunnel, or VPN from laptop
  • Development/testing - Quick iteration without job queue latency
  • Small datasets - Extraction completes in seconds on your laptop
  • Air-gapped environments - No internet access required (with local storage)

​
How It Works

  1. CLI reads configuration
  2. Connects directly to your database
  3. Runs extraction algorithm locally
  4. Stores snapshot in local filesystem or uploads to cloud storage
  5. Reports completion immediately
Storage: Can use local filesystem or cloud storage (your choice) Requirements:
  • Database accessible from your machine
  • Sufficient local CPU/memory for extraction
  • Disk space for snapshot files (if using local storage)

​
Configuration

For local filesystem storage:
For cloud storage (CLI uploads after extraction):
Local snapshots stored on filesystem are tied to the creating machine. Restoring on a different machine requires access to the same file path.

​
Comparison

​
Switching Between Modes

Same configuration file works for both modes. Control via CLI flags:
--async queues agent execution; omitting it runs locally.

​
Next Steps

Storage Providers

Configure S3, GCS, or local filesystem

Self-Hosted Agents

Deploy agents in your infrastructure (recommended for production)

CI/CD Integration

Use self-hosted agents in GitHub Actions

Local Development

Local execution workflow examples