PostgreSQL per worktree
TL;DR: The 30-Second Summary
Isolate PostgreSQL across worktrees using template database cloning (`createdb -T`), dynamic search path schemas (`SET search_path`), or Docker PostgreSQL instances per worktree.
The Real-Life Scenario
“A backend engineer needs to test a breaking PostgreSQL 16 schema redesign while keeping production parity tests running on the main branch. Template cloning allows instant branch-specific database provisioning.”
PostgreSQL offers outstanding multi-tenancy and copy-on-write database cloning capabilities, making it the premier relational database for Git worktree isolation.
Concurrent Migration Clashes
Running `ALTER TABLE` in a feature worktree locks tables and breaks code in other worktrees that rely on the previous column structure.
What you see in the terminal:
ERROR: relation "invoices" is locked by transaction in another sessionUnder the Hood: Git Plumbing & Architecture
PostgreSQL's `CREATE DATABASE ... TEMPLATE` leverages filesystem copy-on-write to clone all tables, indexes, and records almost instantaneously.
Quick Command Recipes
Copy and adapt these commands directly in your terminal:
Create template database once
Creates a master seeded database to serve as the template.
createdb app_template
psql app_template < dump.sqlInstant worktree database clone
Clones the master template in 200 milliseconds.
createdb -T app_template app_wt_authDrop worktree database after cleanup
Reclaims storage space when the worktree is deleted.
dropdb app_wt_authStep-by-Step Practical Walkthrough
Follow these verified steps to safely resolve the issue and guarantee that your filesystem and Git references are in sync.
Prepare the base template
Ensure `app_template` is up to date with latest main migrations.
Clone for new worktree
Spawn an independent database clone.
createdb -T app_template app_feat_checkoutUpdate connection string
Set `DATABASE_URL=postgresql://localhost:5432/app_feat_checkout`.
Edge Cases & Advanced Scenarios
Active connections blocking template clone
PostgreSQL blocks `-T` if any connection is open to the template. Terminate idle connections before cloning.
SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'app_template';Common Mistakes to Avoid
❌ Mistake: Forgetting to drop databases when deleting worktrees
Why it causes trouble: Accumulates dozens of orphan databases over months.
What to do instead: Automate database cleanup in WorktreeWise workflow hooks.
Verification Checklist
- ✓Both PostgreSQL databases operate with complete independence
- ✓Migrations execute without locking other branches
Senior Engineering Tips
- ★Use PostgreSQL schemas (`SET search_path TO worktree_name`) for even lighter-weight isolation without creating new databases.
Key Takeaways
- 01.PostgreSQL template cloning (`-T`) is the fastest way to seed worktree databases.
- 02.Schema-based isolation (`search_path`) is ideal for lightweight test suites.
How WorktreeWise Solves This Visually
WorktreeWise eliminates the manual friction and mental overhead of CLI flags. It displays real-time branch states, uncommitted modifications, active terminals, and lock statuses across all worktrees on a single visual dashboard.
WorktreeWise Engineering Publication
Written and curated by the core WorktreeWise team. We build developer tools that turn Git worktrees, workflows, and parallel AI coding agents into second nature.