Restore downloads a snapshot and inserts its data into a target database. It validates schema compatibility and ensures referential integrity during the process.
Run your migrations first. Restore validates the target schema and inserts
data; it does not create or alter tables.
Usage
basecut snapshot restore <snapshot-ref> [flags]
Arguments
| Argument | Description |
|---|
<snapshot-ref> | Snapshot identifier. Supported forms: UUID, name:tag, or name (resolves to latest). |
Flags
| Flag | Default | Description |
|---|
--target <url>, -t | $BASECUT_DATABASE_URL | PostgreSQL connection string for the destination database. |
--reset | false | Truncate snapshot-managed tables before applying (destructive). |
--force | false | Skip schema validation (may fail if schemas are incompatible). |
--yes, -y | false | Skip confirmation prompts. |
--profile <name> | default | Credential profile to use for API authentication. |
--api-key <key> | $BASECUT_API_KEY | API key override (otherwise uses BASECUT_API_KEY or saved profile). |
Examples
Quick Examples
# Restore the latest version of a snapshot
basecut snapshot restore my-snapshot:latest \
--target "postgresql://localhost:5432/myapp_test"
# Restore a specific version with a reset
basecut snapshot restore my-snapshot:brave-lion \
--target "$BASECUT_DATABASE_URL" \
--reset
Basic Restore
Apply the latest version of a snapshot to your local database:
basecut snapshot restore "weekly-dev-data" \
--target "postgresql://localhost:5432/myapp_dev"
- CLI resolves the latest tag for “weekly-dev-data”.
- Downloads manifest and schema metadata.
- Connects to the target database and validates schema compatibility.
- Downloads data files and inserts rows in dependency order.
- Verifies referential integrity across all restored tables.
Clean Restore (Local Development)
Wipe existing data in the target tables before restoring:
basecut snapshot restore "clean-seed" \
--target "postgresql://localhost:5432/myapp_dev" \
--reset \
--yes
--reset:
- You want to ensure the target tables only contain the snapshot data.
- You are re-running a seed script and want to avoid duplicate key errors.
- You want a clean slate for debugging a specific issue.
CI/CD Integration
Automate restoration for integration tests:
export BASECUT_API_KEY=bc_live_abc123_secret
export BASECUT_DATABASE_URL=postgresql://test_user:pass@localhost:5432/test_db
basecut snapshot restore "ci-baseline:latest" --yes
Output
Success
✓ Loading snapshot: my-snapshot:brave-lion
✓ Validated schema for 23 tables
✓ Inserted 2,847 rows
✓ Verified referential integrity
✓ Restore complete in 3.2s
With Reset
⚠ Truncating 23 tables...
✓ Loading snapshot: my-snapshot:latest
✓ Validated schema for 23 tables
✓ Inserted 2,847 rows
✓ Restore complete
Error Handling
Schema Compatibility Error
✗ Error: schema mismatch detected
Table 'users' is missing column 'last_login_at' which is present in snapshot.
- Run your database migrations to align the target schema with the snapshot.
- Use
--force to skip validation (not recommended if data types have changed).
Connection Failed
✗ Error: failed to connect to target database
dial tcp 127.0.0.1:5432: connect: connection refused
- Verify the target database is running.
- Check the connection string and credentials.
- Ensure the database is accessible from your network.
Next Steps
