How It Works

pgbranch leverages PostgreSQL’s built-in template database feature to create instant, efficient snapshots of your database state.

PostgreSQL Template Databases

PostgreSQL has a powerful feature called template databases. When you create a new database, you can specify an existing database as a template:

CREATE DATABASE new_db TEMPLATE existing_db;

This creates a copy of existing_db as new_db. The key benefits:

Fast - PostgreSQL copies the database at the filesystem level
Efficient - Uses copy-on-write on supported filesystems
Complete - Includes all tables, data, indexes, functions, etc.

How pgbranch Uses Templates

When you run pgbranch commands, here’s what happens under the hood:

`pgbranch branch <name>`

Terminates all connections to the working database
Creates a template database: CREATE DATABASE pgbranch_<name> TEMPLATE myapp_dev
Records branch metadata (creation time, parent branch, etc.)

Working DB: myapp_dev
                │
                ▼
    ┌───────────────────┐
    │ CREATE DATABASE   │
    │ pgbranch_main     │
    │ TEMPLATE myapp_dev│
    └───────────────────┘
                │
                ▼
Template: pgbranch_main (snapshot)

`pgbranch checkout <name>`

Terminates all connections to the working database
Drops the current working database
Creates a new working database from the target branch’s template
Updates the current branch pointer

Working DB: myapp_dev          Template: pgbranch_feature
(will be dropped)              (source for restore)
        │                              │
        ▼                              │
    DROP DATABASE                      │
    myapp_dev                          │
        │                              │
        └──────────┬───────────────────┘
                   ▼
    ┌────────────────────────────┐
    │ CREATE DATABASE myapp_dev  │
    │ TEMPLATE pgbranch_feature  │
    └────────────────────────────┘
                   │
                   ▼
Working DB: myapp_dev (restored from feature)

Database Naming Convention

pgbranch creates template databases with a specific naming pattern:

pgbranch_<branch_name>_<project_hash>

For example:

pgbranch_main_a1b2c3
pgbranch_feature_auth_a1b2c3

The project hash ensures multiple projects can use pgbranch without conflicts.

Storage Location

Local Storage

Branch metadata is stored in .pgbranch/ in your project root:

.pgbranch/
├── config.json     # Database connection, remotes
├── branches/       # Branch metadata
│   ├── main.json
│   └── feature.json
└── key             # Encryption key (not committed)

Database Storage

The actual database snapshots are PostgreSQL databases on your server. You can see them:

psql -c "SELECT datname FROM pg_database WHERE datname LIKE 'pgbranch_%'"

Performance Characteristics

Speed

Operation	Typical Time
Create branch	< 1 second
Checkout branch	1-5 seconds
Delete branch	< 1 second

Times depend on database size and disk speed, but are generally very fast due to template database efficiency.

Disk Space

Each branch consumes disk space equal to the database size at the time of snapshot. However:

PostgreSQL uses copy-on-write on supported filesystems (ZFS, Btrfs)
Identical data blocks are shared between databases
Space usage grows as branches diverge

Limitations

Connection Termination

To create or restore a database from a template, PostgreSQL requires no active connections. pgbranch automatically terminates connections, but this means:

Active queries will be cancelled
Transactions will be rolled back
Applications connected to the database will disconnect

Single Machine

Template databases are local to a PostgreSQL instance. To share branches across machines, use remote storage.

No Partial Snapshots

Each branch is a complete database snapshot. You cannot:

Snapshot individual tables
Create incremental backups
Branch specific schemas only

Comparison with Other Approaches

Approach	Speed	Disk Usage	Data Included
pgbranch	Fast	Database size	Complete
pg_dump/restore	Slow	Compressed	Complete
Schema-only migrations	Fast	Minimal	Schema only
Docker volumes	Medium	Container size	Complete

pgbranch is ideal when you need complete database snapshots (including data) with fast switching during development.