branch

The branch command lists existing branches or creates a new branch from the current database state.

Usage

# List all branches
pgbranch branch

# Create a new branch
pgbranch branch <name>

Arguments

Argument	Description
name	Name for the new branch (optional)

Examples

List All Branches

pgbranch branch

Output:

  main
* feature-auth
  feature-payments

The * indicates the current branch.

Create a New Branch

pgbranch branch feature-notifications

Output:

Branch 'feature-notifications' created

Create Initial Branch

After initializing pgbranch, create your first branch:

pgbranch init -d myapp_dev
pgbranch branch main

How It Works

When you create a branch, pgbranch:

1. Terminates active connections to the working database
2. Creates a template database as a snapshot
3. Records metadata (creation time, parent branch)

The template database is named: pgbranch_<branch_name>_<project_hash>

Working database: myapp_dev
         │
         ▼
    CREATE DATABASE
    pgbranch_feature_auth_abc123
    TEMPLATE myapp_dev
         │
         ▼
Snapshot stored as template database

Branch Naming

Branch names should:

• Contain only alphanumeric characters, hyphens, and underscores
• Not start with a number
• Be reasonably short (PostgreSQL has a 63-character limit on identifiers)

Good branch names:

main
feature-auth
bugfix-login-issue
v2-schema

Branching Strategy

Mirror Git Branches

A common strategy is to mirror your git branch names:

git checkout -b feature/user-profiles
pgbranch branch feature-user-profiles

Snapshot Points

Create branches at significant points:

# After fresh migration
pgbranch branch clean-schema

# After seeding test data
pgbranch branch with-seed-data

# Before risky migration
pgbranch branch pre-migration

Viewing Branch Details

To see more information about branches, use the log command:

pgbranch log

Output:

* main (current)
    Created: 2024-01-15 10:30:00
    Parent: -

  feature-auth
    Created: 2024-01-15 14:22:00
    Parent: main

Storage Considerations

Each branch creates a complete database copy. Monitor disk usage:

# Check PostgreSQL database sizes
psql -c "SELECT pg_database.datname, pg_size_pretty(pg_database_size(pg_database.datname))
         FROM pg_database WHERE datname LIKE 'pgbranch_%';"

Use pgbranch prune to clean up old branches:

pgbranch prune -d 7  # Remove branches not accessed in 7 days

Common Workflows

Feature Development

# Start from main
pgbranch checkout main

# Create feature branch
pgbranch branch feature-new-api

# Work on feature...
# Run migrations, add test data

# Switch back to main for a hotfix
pgbranch checkout main
pgbranch branch hotfix-critical-bug

Testing Migrations

# Save current state
pgbranch branch before-migration

# Run migration
npm run migrate

# If migration fails, restore
pgbranch checkout before-migration

Related Commands

• checkout - Switch to a different branch
• delete - Delete a branch
• log - View branch history
• status - Show current branch