checkout

The checkout command switches your working database to a different branch’s state.

Usage

pgbranch checkout <branch>

Arguments

Argument	Description
branch	Name of the branch to switch to (required)

Examples

Switch to Main Branch

pgbranch checkout main

Output:

Saving current branch state...
Switching to branch 'main'...
Switched to branch 'main'

Switch to Feature Branch

pgbranch checkout feature-auth

How It Works

When you checkout a branch, pgbranch performs these steps:

1. Saves current state - Updates the current branch’s template database with any changes
2. Terminates connections - Disconnects all active database connections
3. Drops working database - Removes the current working database
4. Restores from template - Creates new working database from target branch’s snapshot

Current state             Target branch
myapp_dev ─────────┐      pgbranch_main
                   │            │
                   ▼            │
              Save to           │
         current branch         │
                   │            │
                   ▼            │
              DROP DATABASE     │
              myapp_dev         │
                   │            │
                   └────────────┤
                                ▼
                        CREATE DATABASE
                        myapp_dev
                        TEMPLATE pgbranch_main
                                │
                                ▼
                   myapp_dev now matches 'main'

Important Considerations

Database Will Be Dropped

The checkout command drops your current working database. While the current state is saved to the current branch first, any applications connected to the database will be disconnected.

Connection Handling

• All active connections are terminated
• Running queries will be cancelled
• Open transactions will be rolled back
• Applications should handle reconnection gracefully

Auto-Save Behavior

Before switching, pgbranch automatically saves the current database state to the current branch. This means:

• Changes made since the last branch operation are preserved
• You can switch branches freely without losing work
• The saved state becomes the new snapshot for that branch

Error Cases

Branch Doesn’t Exist

pgbranch checkout nonexistent

Error: branch 'nonexistent' does not exist

Already On Branch

pgbranch checkout main  # when already on main

Error: already on branch 'main'

Database Connection Issues

If PostgreSQL is not accessible:

Error: could not connect to database: connection refused

Use Cases

Quick Context Switching

# Working on feature, need to check something on main
pgbranch checkout main

# Check the data/schema you needed
psql myapp_dev -c "SELECT * FROM users LIMIT 5"

# Back to feature work
pgbranch checkout feature-auth

Testing Different States

# Test with production-like data
pgbranch checkout prod-snapshot

# Test with minimal data
pgbranch checkout minimal-seed

# Test with edge cases
pgbranch checkout edge-case-data

Rolling Back Changes

# Before risky operation
pgbranch branch pre-experiment

# Try something dangerous
npm run migrate:dangerous

# Didn't work? Roll back
pgbranch checkout pre-experiment

Automatic Checkout with Git

You can automate checkout when switching git branches:

pgbranch hook install

This installs a post-checkout git hook that runs pgbranch checkout <git-branch> automatically.

Learn more about git hooks

Performance

Checkout typically takes 1-5 seconds depending on:

• Database size
• Disk speed
• Number of active connections to terminate

For faster checkouts:

• Keep databases reasonably sized during development
• Close idle database connections
• Use SSD storage

Related Commands

• branch - Create a new branch
• status - View current branch
• log - View all branches