Quickstart

Preflight a source, wait for its replica to become ready, and create your first writable branch.

1. Point the client at your server

export SNAPSHOTDB_SERVER=https://snapshotdb.example.com
export SNAPSHOTDB_TOKEN='<your server access token>'

2. Preflight the source

Preflight checks the database read-only and prints exactly what to fix. It creates nothing and stores nothing.

$ snapshotdb preflight postgres 'postgresql://user:pass@db:5432/app'
  ✓ connection (PostgreSQL 16.4)   ✓ is writer   ✓ wal level (actual: logical)
  ✓ can replicate   ✓ can read tables   ! replica identity (1 table skipped)
  ✓ Preflight passed.

Exit code is 2 if it does not pass, so it drops straight into a script.

3. Keep a replica, then branch it

# one continuously-synced replica of production
$ snapshotdb clone prod 'postgresql://user:pass@db:5432/app'
$ snapshotdb status prod

# wait for the initial copy to finish and replication to be healthy
$ snapshotdb create fix-orders --from prod --print-url
postgresql://snapshotdb_agent:••••@branches.internal:57375/app

Connect a compatible database client to that URL over your private network or encrypted tunnel. Keep the URL secret: it grants access to the copied data. When you are done:

$ snapshotdb rm fix-orders

The same shape, any engine

Swap postgres for mysql or mongodb in preflight; clone infers the engine from the connection string. See the per-engine guides under Connect a database.

SQLite starts from a file on the server or snapshotdb import sqlite demo --new; it has no live source replication. Its branches expose an authenticated SQL-over-HTTP endpoint.

Prepare capacity for agents

For repeated claims from a fixed snapshot, prepare running branches ahead of time. Preparation and initial replication are outside the claim timing; an empty pool returns an error. See AI agents.

snapshotdb prepare release-1 --from prod --count 3
snapshotdb create agent-task --from release-1 --print-url