Branches Neon, Turso, or Supabase per git worktree for isolated schema work. Use when a worktree changes the schema, or on mention of Neon, Turso, Prisma.
Branches Neon, Turso, or Supabase per git worktree for isolated schema work. Use when a worktree changes the schema, or on mention of Neon, Turso, Prisma.
user-invocable
false
Database Branching for Worktrees
Purpose: Automatically create and manage database branches when working with git worktrees that involve schema changes. Each worktree gets its own isolated database fork, preventing schema modifications from hitting production.
Supported Providers
Provider
Database
Branch Speed
ORM Support
Integration
Neon (recommended)
PostgreSQL
Instant (ms)
Prisma, Drizzle, TypeORM, Django
MCP tools (native)
Turso
libSQL/SQLite
Near-instant
Drizzle, libSQL clients
CLI (turso)
Supabase
PostgreSQL
Seconds
Prisma, Drizzle, TypeORM, Django
CLI (supabase)
When to Use
Creating a worktree that will modify schema files (Prisma, Drizzle, raw SQL migrations)
Adding new database models, columns, or indexes in a feature branch
Testing migrations in isolation before applying to production
Running multiple feature branches that each need different schemas
Any /dev:worktree create where schema changes are anticipated
When NOT to Use
Worktrees that only modify application code (no schema changes)
Quick bug fixes that don't touch the database
Read-only database work (queries, reports)
Projects using databases without branching support
Provider Detection
Auto-detect the provider from the project's .env file:
Pattern in *_DATABASE_URL
Provider
Action
neon.tech
Neon
Use MCP tools (preferred)
turso.io or libsql://
Turso
Use turso CLI
supabase.co
Supabase
Use supabase CLI
Other hosts
None
Skip branching, warn user
# Detection logicif grep -q "neon.tech" .env 2>/dev/null; then
PROVIDER="neon"elif grep -q "turso.io\|libsql://" .env 2>/dev/null; then
PROVIDER="turso"elif grep -q "supabase.co" .env 2>/dev/null; then
PROVIDER="supabase"else
PROVIDER="none"fi
Schema Tool Detection
File/Config
Schema Tool
Push Command Pattern
prisma/*/schema.prisma
Prisma
{name}:push or prisma db push
drizzle.config.ts
Drizzle
drizzle-kit push
migrations/ + knexfile.*
Knex
knex migrate:latest
alembic/
Alembic (Python)
alembic upgrade head
Raw .sql files
Manual
Apply with psql or MCP run_sql
Integration with worktree-lifecycle
This skill extends the existing dev:worktree-lifecycle 6-phase approach:
Phase
Standard Behavior
With DB Branching
Phase 1: Pre-flight
Git checks only
+ Detect provider, check availability
Phase 3: Creation
Git worktree + .gitignore
+ Create DB branch, inject .env
Phase 4: Setup
Install deps, run tests
+ Run schema push against branch
Phase 5: Handoff
Report worktree info
+ Include DB branch ID in metadata
Phase 6: Cleanup
Remove worktree + branch
+ Delete DB branch
Phase 1 Extension: Pre-flight
After standard git checks pass:
Detect provider from .env (see Provider Detection above)
Verify provider tools are available:
Provider
Check
Neon
Try mcp__Neon__list_projects — if MCP tools not available, warn
Turso
Run which turso — if CLI not installed, warn
Supabase
Run which supabase — if CLI not installed, warn
If provider tools are not available:
[WARN] {Provider} tools not available.
Worktree will use the production database URL.
Schema changes will NOT be isolated.
To enable database branching:
Neon: Configure @neondatabase/mcp-server-neon MCP server
Turso: brew install tursodatabase/tap/turso
Supabase: brew install supabase/tap/supabase
Phase 3 Extension: Create Database Branch
Trigger: User confirmed schema changes will be made, OR task description mentions schema/model/migration work.
Insert after git worktree add succeeds, before dependency installation:
Step 1: Ask About Schema Changes
AskUserQuestion:question:"Will this branch involve database schema changes (new tables, columns, indexes)?"header:"Schema"options:-label:"Yes - create database branch (Recommended)"description:"Isolates schema changes from production via {PROVIDER}"-label:"No - use production database"description:"Faster setup, but schema changes would hit production"-label:"Not sure - create branch anyway"description:"Safe default, can delete later if unused"
Step 2: Create Branch (Provider-Specific)
Neon (MCP — preferred)
mcp__Neon__create_branch(
projectId: "{PROJECT_ID}",
branchName: "{BRANCH_NAME}"
)
// Returns: { id: "br-xxx-yyy", ... }
mcp__Neon__get_connection_string(
projectId: "{PROJECT_ID}",
branchId: "{BRANCH_ID}"
)
// Returns: connection string for the new branch endpoint
Turso (CLI)
turso db create "{DB_NAME}-{BRANCH_SLUG}" --from-db "{DB_NAME}"# Get the new database URL
turso db show "{DB_NAME}-{BRANCH_SLUG}" --url
# Get auth token
turso db tokens create "{DB_NAME}-{BRANCH_SLUG}"
The connection string is: libsql://{DB_NAME}-{BRANCH_SLUG}-{org}.turso.io with the auth token.
Supabase (CLI)
supabase branches create "{BRANCH_NAME}" --project-ref "{PROJECT_REF}"# Returns branch ID and connection details
Step 3: Copy and Patch .env
# Copy .env from main worktree to new worktreecp"${ORIGINAL_CWD}/.env""${WORKTREE_PATH}/.env"# Replace the DATABASE_URL with branch connection string# Only swap URLs matching the detected provider - leave other database URLs unchanged
sed -i ''"s|{ENV_VAR_NAME}=.*|{ENV_VAR_NAME}=\"${BRANCH_CONNECTION_STRING}\"|" \
"${WORKTREE_PATH}/.env"# For Turso: also update auth token if separate env var# sed -i '' "s|{TOKEN_VAR}=.*|{TOKEN_VAR}=\"${BRANCH_AUTH_TOKEN}\"|" "${WORKTREE_PATH}/.env"
Important: Add .db-branch.json to .gitignore (contains connection string with credentials).
Phase 4 Extension: Apply Schema
After dependency installation, if database branch was created:
Push Schema to Branch
Use the detected schema tool:
Schema Tool
Command
Prisma
bun run {name}:push or npx prisma db push
Drizzle
npx drizzle-kit push
Knex
npx knex migrate:latest
Alembic
alembic upgrade head
Verify Schema Applied
Neon (MCP)
mcp__Neon__run_sql(
projectId: "{PROJECT_ID}",
branchId: "{BRANCH_ID}",
sql: "SELECT count(*) FROM information_schema.tables WHERE table_schema = 'public'"
)
Turso (CLI)
turso db shell "{DB_NAME}-{BRANCH_SLUG}""SELECT count(*) FROM sqlite_master WHERE type='table'"
Supabase
# Use the branch connection string directly with psql or via Supabase CLI
supabase db execute --project-ref "{PROJECT_REF}" --branch "{BRANCH_NAME}" \
"SELECT count(*) FROM information_schema.tables WHERE table_schema = 'public'"
Phase 5 Extension: Enhanced Handoff
Update the worktree metadata to include database branch info:
Worktree ready:
Path: .worktrees/feature-auth
Branch: feature/auth
Stacks: nodejs
Dependencies: installed
Tests: 47 passing, 7 failing (pre-existing)
DB Provider: Neon (PostgreSQL)
DB Branch: br-xxx-yyy (from production)
Database: Isolated (branch-specific connection)
Status: READY
Safe to run schema commands:
bun run circl:push # Push schema changes (isolated)
bun run circl:generate # Regenerate Prisma client
Phase 6 Extension: Cleanup
Step 1: Check for Branch Metadata
DB_META="${WORKTREE_PATH}/.db-branch.json"if [ -f "$DB_META" ]; then
PROVIDER=$(jq -r .provider "$DB_META")
BRANCH_ID=$(jq -r .branchId "$DB_META")
PROJECT_ID=$(jq -r .projectId "$DB_META")
fi
Step 2: Ask About Schema Migration
AskUserQuestion:question:"This worktree has a {PROVIDER} database branch. Apply schema changes to production?"header:"DB cleanup"options:-label:"Apply schema to production first, then delete branch (Recommended)"description:"Merges code + pushes schema to production"-label:"Delete branch (discard schema changes)"description:"Only the code gets merged, schema changes are lost"-label:"Keep branch for now"description:"Worktree is removed but database branch stays (manual cleanup later)"
Step 3: Apply Schema to Production (if chosen)
cd"${ORIGINAL_CWD}"# Use the project's schema push command against production
