Schema Diff

The diff command compares the database schema between two branches and displays the differences.

Usage

pgbranch diff <branch1> [branch2] [flags]

Arguments

Argument	Description
branch1	First branch to compare (required)
branch2	Second branch to compare (optional, defaults to working database)

Flags

Flag	Description
--stat	Show summary statistics only
--sql	Show SQL statements to apply changes

Examples

Compare Two Branches

pgbranch diff main feature-auth

Output:

=== Schema Diff: main → feature-auth ===

 Table: sessions
    + Column: id (uuid, NOT NULL, DEFAULT gen_random_uuid())
    + Column: user_id (uuid, NOT NULL)
    + Column: token (text, NOT NULL)
    + Column: expires_at (timestamp with time zone)
    + Index: sessions_user_id_idx ON sessions(user_id)
    + Foreign Key: sessions_user_id_fkey REFERENCES users(id)

~ Table: users
    + Column: last_login (timestamp with time zone)
    + Column: login_count (integer, DEFAULT 0)

 Enum: auth_provider
    Values: local, google, github

Compare Branch Against Working Database

pgbranch diff main

This compares the main branch snapshot against your current working database state.

Summary Statistics Only

pgbranch diff main feature-auth --stat

Output:

Schema Diff Summary: main → feature-auth

Tables:
  + 1 added
  ~ 1 modified
  - 0 removed

Columns:
  + 5 added
  ~ 0 modified
  - 0 removed

Indexes:
  + 1 added

Constraints:
  + 1 foreign key added

Enums:
  + 1 added

Generate Migration SQL

pgbranch diff main feature-auth --sql

Output:

-- Migration: main → feature-auth
-- Generated by pgbranch

-- Create enum type
CREATE TYPE auth_provider AS ENUM ('local', 'google', 'github');

-- Create table: sessions
CREATE TABLE sessions (
    id uuid NOT NULL DEFAULT gen_random_uuid(),
    user_id uuid NOT NULL,
    token text NOT NULL,
    expires_at timestamp with time zone,
    PRIMARY KEY (id)
);

-- Add columns to users
ALTER TABLE users ADD COLUMN last_login timestamp with time zone;
ALTER TABLE users ADD COLUMN login_count integer DEFAULT 0;

-- Create indexes
CREATE INDEX sessions_user_id_idx ON sessions(user_id);

-- Add foreign keys
ALTER TABLE sessions
    ADD CONSTRAINT sessions_user_id_fkey
    FOREIGN KEY (user_id) REFERENCES users(id);

What Gets Compared

The diff command detects changes in:

Tables

• New tables added
• Tables removed
• Table renames (detected as remove + add)

Columns

• New columns
• Removed columns
• Type changes
• Default value changes
• Nullability changes
• Column renames (detected as remove + add)

Indexes

• New indexes
• Removed indexes
• Index definition changes

Constraints

• Primary keys
• Foreign keys
• Unique constraints
• Check constraints

Enums

• New enum types
• Removed enum types
• Added enum values
• Removed enum values

Functions

• New functions
• Removed functions
• Function signature changes
• Function body changes

Output Format

Color Coding

When displayed in a terminal:

Symbol	Color	Meaning
+	Green	Added
-	Red	Removed
~	Yellow	Modified

Destructive Change Warnings

Potentially destructive changes are highlighted:

=== Schema Diff: feature-auth → main ===

⚠️  DESTRUCTIVE CHANGES DETECTED:

 Table: sessions (will be dropped)
    ⚠️  This will delete all data in the table

~ Table: users
    - Column: last_login (will be dropped)
    - Column: login_count (will be dropped)

Use Cases

Review Before Merge

Before merging schema changes:

# See what will change
pgbranch diff main feature-auth

# If looks good, proceed with merge
pgbranch merge feature-auth main

Generate Migration Files

Create migration files from diff output:

pgbranch diff main feature-auth --sql > migrations/002_add_auth.sql

Audit Schema Evolution

Track how your schema evolved:

# Compare original to current
pgbranch diff v1-schema current-schema --stat

Debug Schema Issues

When something isn’t working:

# Compare working database against known-good branch
pgbranch diff known-good

Limitations

No Data Comparison

The diff command only compares schema, not data. To compare data:

# Use PostgreSQL tools directly
pg_dump --schema-only db1 > schema1.sql
pg_dump --schema-only db2 > schema2.sql
diff schema1.sql schema2.sql

Rename Detection

Renames are detected as separate add/remove operations. pgbranch cannot automatically detect that a column was renamed vs. removed and a new one added.

Extension-Specific Objects

Some PostgreSQL extension-specific objects may not be fully compared.

Related Commands

• merge - Apply schema changes between branches
• branch - Create new branches
• checkout - Switch between branches