Skip to content
pocket-kit Docs

Instant Database Branching

Database branching allows developers to fork live databases into isolated preview environments in under 200 milliseconds.

Branching Lifecycle Flow

flowchart TD
    subgraph ProductionEnv ["🟢 Production Database (prod.pocket-kit...)"]
        ProdDB[("Live SQLite data.db")]
        ProdHooks["Server Logic (pb_hooks/)"]
        ProdDB ~~~ ProdHooks
    end

    subgraph SnapshotEngine ["⚡ Pocket Kit Snapshot & Provisioning Engine"]
        CopyOp["1. Atomic Disk Copy (data.db & pb_hooks)"]
        PortAlloc["2. Allocate Port (8091..8999)"]
        SpawnProc["3. Spawn Isolated PocketBase Process"]
        CaddyRoute["4. Dynamic Ingress (staging.pocket-kit...)"]
        CopyOp --> PortAlloc --> SpawnProc --> CaddyRoute
    end

    subgraph StagingEnv ["🟡 Staging Branch (staging.pocket-kit...)"]
        StagingDB[("Isolated SQLite Copy")]
        StagingHooks["Isolated Server Hooks"]
        StagingDB ~~~ StagingHooks
    end

    ProductionEnv -->|"Trigger Staging Clone (< 200ms)"| SnapshotEngine
    SnapshotEngine -->|"Deploy Instant Staging Branch"| StagingEnv

Key Benefits

  1. Zero Downtime: Production remains fully operational while the snapshot is copied.
  2. True Parity: Staging contains the exact schema, migrations, data records, and server hooks.
  3. Safe Destruction: Delete or reset the staging branch anytime with one click.