Quickstart

This guide will walk you through setting up pgbranch for a project and creating your first database branches.

Prerequisites

• pgbranch installed (Installation guide)
• A PostgreSQL database for your project
• PostgreSQL running and accessible

Step 1: Initialize pgbranch

Navigate to your project directory and initialize pgbranch:

cd your-project
pgbranch init -d myapp_dev

This creates a .pgbranch directory in your project root containing:

• Configuration file
• Branch metadata
• Encryption keys for remote credentials

Connection Options

You can specify PostgreSQL connection details during init:

# Full connection specification
pgbranch init -d myapp_dev -H localhost -p 5432 -U postgres

# With password prompt
pgbranch init -d myapp_dev -W

Flag	Description	Default
-d, --database	Database name	(required)
-H, --host	PostgreSQL host	localhost
-p, --port	PostgreSQL port	5432
-U, --user	PostgreSQL user	postgres
-W, --password	Prompt for password	-

Step 2: Create Your First Branch

With your database in a clean state (e.g., after running migrations), create a branch:

pgbranch branch main

This creates a snapshot of your current database state. You can verify it was created:

pgbranch branch

Output:

* main

The * indicates this is your current branch.

Step 3: Make Changes and Create Another Branch

Now let’s simulate working on a feature:

# Run some migrations or make database changes
# For example, add a new table in your app

# Save this state as a new branch
pgbranch branch feature-auth

List your branches:

pgbranch branch

Output:

  main
* feature-auth

Step 4: Switch Between Branches

Need to go back to the main branch? Easy:

pgbranch checkout main

Database Reset

When you checkout a branch, pgbranch:

1. Saves the current database state to the current branch
2. Drops the working database
3. Restores the target branch’s snapshot

Any uncommitted changes to the database will be saved to the current branch before switching.

Your database is now back to the exact state it was when you created the main branch.

Step 5: Check Status

View your current state anytime:

pgbranch status

Output:

Database: myapp_dev (localhost:5432)
Current branch: main
Total branches: 2

Complete Workflow Example

Here’s a typical development workflow:

# Start fresh - create a main branch from clean database
pgbranch init -d myapp_dev
pgbranch branch main

# Start working on a feature
git checkout -b feature/user-profiles
# Run migrations, add test data...
pgbranch branch feature-profiles

# Urgent bug fix needed on main
git checkout main
pgbranch checkout main
# Fix the bug, your database is now in the main state

# Back to feature work
git checkout feature/user-profiles
pgbranch checkout feature-profiles
# Your feature database state is restored!

Automatic Branch Switching

Tired of running pgbranch checkout manually? Install the git hook:

pgbranch hook install

Now pgbranch will automatically switch database branches when you switch git branches (if a matching branch exists).

Learn more about git hooks

Next Steps

• Understand how pgbranch works
• Learn about schema diffing
• Set up remote storage
• Explore all commands