Skip to content
armadillo

db-safety

DB Safety

Section titled “DB Safety”

The Contract

Section titled “The Contract”
Production DB   → main branch only → never in any worktree .env
Staging DB      → persistent preview branch → long-lived worktrees only
Preview DB      → ephemeral Neon/Supabase branch → per PR worktree
Dev DB          → local or Neon dev branch → developer's personal worktree

Constraints

Section titled “Constraints”
  1. Never put production DATABASE_URL in any worktree .env — production credentials belong only to the main branch deployment (Vercel production, Railway production, etc.)
  2. Each worktree gets its own database branch — use Neon dev/<branch-name> or Supabase preview branch. Never share a DB across worktrees.
  3. Warn on missing .env — when a worktree is created for DB-touching work and no .env exists in the worktree, warn the developer to configure DATABASE_URL before running migrations
  4. Migration PRs should be separate — when possible, merge migration-only PRs before app code PRs that depend on the new schema. This prevents coupled failures.
  5. No manual SQL on production — every schema change is a tracked migration file. Forward-only in production.

Per-Worktree .env Template

Section titled “Per-Worktree .env Template”

When setting up a worktree that touches the database:

Terminal window
# .env in worktree root (gitignored)
DATABASE_URL=<neon-branch-url-or-supabase-preview-url>
DATABASE_URL_UNPOOLED=<direct-connection-for-migrations>

For Neon: neonctl connection-string --branch dev/<branch-name> --pooled For Supabase: get credentials from supabase branches get <branch-name> For local: postgresql://postgres:postgres@localhost:54322/postgres

When Active

Section titled “When Active”
  • When creating worktrees for work that involves database schemas, migrations, or seed data
  • When writing .env files in any worktree
  • When safe-merge encounters migration files in a branch diff
  • When writing-plans creates tasks involving DB schema changes

When Inactive

Section titled “When Inactive”
  • Projects with no database (pure frontend, CLI tools, static sites)
  • Main branch deployments (production DB config is managed by the deploy platform)

Integration

Section titled “Integration”
SkillHow it uses this rule
worktreeWarn when worktree has no .env and branch touches DB files
safe-mergeCheck for migration conflicts before merging
writing-plansFlag migration-first pattern when plan involves schema changes
neonProvides branching patterns for per-worktree DB isolation
supabaseProvides branching patterns for per-worktree DB isolation