basecut snapshot restore

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_TARGET_DATABASE_URL`	PostgreSQL connection string for the destination database. Restore does not use `BASECUT_DATABASE_URL` so you do not accidentally restore over your source.
`--reset`	`false`	Truncate snapshot-managed tables before applying (destructive).
`--force`	`false`	Skip schema validation (may fail if schemas are incompatible).
`--batch-size <n>`	`1000`	Rows per insert batch (auto-capped per table by database limits).
`--on-conflict <mode>`	`error`	Conflict behavior: `error` (fail fast) or `skip` (ignore conflicts).
`--analyze-fks`	`false`	Run FK preflight analysis only (no data is applied).
`--unsafe-disable-fk-checks`	`false`	Unsafe bypass: disables FK checks during restore (requires elevated DB privileges).
`--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_TARGET_DATABASE_URL" \
  --reset

# Restore while skipping duplicate key conflicts
basecut snapshot restore my-snapshot:latest \
  --target "$BASECUT_TARGET_DATABASE_URL" \
  --on-conflict skip

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"

What happens:

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

When to use --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.

--reset runs inside the same transaction as restore inserts. If restore fails, all reset and insert operations are rolled back together.

CI/CD Integration

Automate restoration for integration tests:

export BASECUT_API_KEY=bc_live_abc123_secret
export BASECUT_TARGET_DATABASE_URL=postgresql://test_user:pass@localhost:5432/test_db

basecut snapshot restore "ci-baseline:latest" --yes

Analyze Foreign Key Restore Safety

Preview FK-related restore risk before applying any data:

basecut snapshot restore "production:latest" \
  --target "$BASECUT_TARGET_DATABASE_URL" \
  --analyze-fks

--analyze-fks reports:

Number of non-deferrable foreign key constraints.
Self-referential tables in the restore scope.
Whether an inter-table FK cycle exists.
Whether safe restore mode would be blocked.
Whether nullable fallback is available for blocking constraints.

If Nullable fallback available: true, Basecut will automatically handle the restore using a two-phase approach — inserting rows with temporary NULLs for the blocking FK columns, then backfilling the real values — with no additional flags required. This requires that all blocking FK columns are nullable and the affected table has a primary key or unique key. Use this when preparing migrations or debugging FK restore blockers.

Unsafe FK Bypass (Last Resort)

If you need a one-off restore and cannot make constraints deferrable immediately:

basecut snapshot restore "production:latest" \
  --target "$BASECUT_TARGET_DATABASE_URL" \
  --unsafe-disable-fk-checks

--unsafe-disable-fk-checks disables FK enforcement during restore. Use only in controlled environments and validate integrity after restore.

This mode may require elevated PostgreSQL privileges.

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.

Solutions:

Run your database migrations to align the target schema with the snapshot.
Use --force to skip validation (not recommended if data types have changed).

Foreign Key Constraint Error

✗ Error: foreign key violation during restore on orders (orders_user_id_fkey)

Common causes:

Non-deferrable foreign keys combined with cyclic or self-referential dependencies.
Parent rows missing from target scope while child rows are restored.

Solutions:

Run FK preflight first:

basecut snapshot restore "<snapshot-ref>" --target "$BASECUT_TARGET_DATABASE_URL" --analyze-fks

Make relevant foreign key constraints DEFERRABLE where appropriate.
If --analyze-fks reports nullable fallback available, re-run restore normally — Basecut handles it automatically. Note: nullable fallback is not compatible with --on-conflict skip; use the default conflict policy.
Ensure referenced parent tables/rows are included in the snapshot.
If you need a temporary bypass, use --unsafe-disable-fk-checks (unsafe).
Re-run after schema alignment or adjust restore scope.

Conflict Error (`--on-conflict error`)

✗ Error: duplicate key value violates unique constraint ...

Solutions:

Use --reset for a clean restore target, or
Use --on-conflict skip to continue and skip conflicting rows.

Connection Failed

✗ Error: failed to connect to target database
  dial tcp 127.0.0.1:5432: connect: connection refused

Solutions:

Verify the target database is running.
Check the connection string and credentials.
Ensure the database is accessible from your network.

Next Steps

Create Snapshot

Learn how to extract data from your source database

Snapshots Concept

Understand the anatomy and lifecycle of snapshots

Snapshot Versioning

Learn how tags and versions work

Troubleshooting

Common issues and how to solve them

Getting Started

Core Concepts

Configuration

Workflows

Integrations

CLI Reference

Deployment

Reference

basecut snapshot restore

Usage

Arguments

Flags

Examples

Quick Examples

Basic Restore

Clean Restore (Local Development)

CI/CD Integration

Analyze Foreign Key Restore Safety

Unsafe FK Bypass (Last Resort)

Output

Success

With Reset

Error Handling

Schema Compatibility Error

Foreign Key Constraint Error

Conflict Error (`--on-conflict error`)

Connection Failed

Next Steps

Create Snapshot

Snapshots Concept

Snapshot Versioning

Troubleshooting

​Usage

​Arguments

​Flags

​Examples

​Quick Examples

​Basic Restore

​Clean Restore (Local Development)

​CI/CD Integration

​Analyze Foreign Key Restore Safety

​Unsafe FK Bypass (Last Resort)

​Output

​Success

​With Reset

​Error Handling

​Schema Compatibility Error

​Foreign Key Constraint Error

​Conflict Error (--on-conflict error)

​Connection Failed

​Next Steps

Create Snapshot

Snapshots Concept

Snapshot Versioning

Troubleshooting

Usage

Arguments

Flags

Examples

Quick Examples

Basic Restore

Clean Restore (Local Development)

CI/CD Integration

Analyze Foreign Key Restore Safety

Unsafe FK Bypass (Last Resort)

Output

Success

With Reset

Error Handling

Schema Compatibility Error

Foreign Key Constraint Error

Conflict Error (`--on-conflict error`)

Connection Failed

Next Steps