pgbranch

Never lose your database state when switching git branches again.

The Problem

You’re working on a feature branch. Your database has migrations, seed data, and test records perfectly set up. Then you need to switch to main to fix a bug.

Your database state is now broken.

The migrations from your feature branch don’t exist on main. Your app crashes. You spend 20 minutes resetting your database, only to realize you need to switch back to the feature branch later.

The Solution

pgbranch init -d myapp_dev
pgbranch branch main           # snapshot your clean main state
pgbranch checkout main         # switch to the main branch

pgbranch branch feature-x      # create a new branch (snapshots current state)
pgbranch checkout feature-x    # switch to it
# ... run migrations, break things ...

pgbranch checkout main         # instantly back to clean state

pgbranch creates instant snapshots of your PostgreSQL database using template databases. Switch between database states as easily as you switch git branches.

Features

Instant Snapshots

Create and restore database snapshots in seconds using PostgreSQL’s native template database feature. No slow dumps or restores.

Schema Diff

Compare schemas between branches. See exactly what tables, columns, indexes, and constraints have changed.

Schema Merge

Merge schema changes between branches. Generate migration files or apply changes directly.

Remote Storage

Share database snapshots with your team. Supports AWS S3, MinIO, Cloudflare R2, and local filesystem.

Git Integration

Install a git hook to automatically switch database branches when you switch git branches.

Encrypted Credentials

Remote storage credentials are encrypted locally. Safe to commit config files to version control.

Quick Start

# Install pgbranch
go install github.com/le-vlad/pgbranch/cmd/pgbranch@latest

# Initialize in your project
pgbranch init -d myapp_dev

# Create your first branch and switch to it
pgbranch branch main
pgbranch checkout main

# Create a feature branch and switch to it
pgbranch branch feature-auth
pgbranch checkout feature-auth

# Make changes, run migrations, etc.

# Switch back to main anytime
pgbranch checkout main

Read the full quickstart guide

Requirements

PostgreSQL - Any recent version
Go 1.21+ - For installation via go install