Skip to content
Toprent.app Docs

10. Automate Neon Database Branching with Git Hooks

Date: 2025-11-17

Status

Implemented

Context

Following ADR-0008’s migration to Neon, developers need to manually manage Neon database branches when working on features. Without automation, developers either:

  1. Share the staging database - Multiple developers modifying the same database state, causing conflicts and data inconsistency
  2. Manually create and switch branches - Error-prone, time-consuming, and often forgotten
  3. Work with stale data - Forgetting to switch databases when changing Git branches

This creates several problems:

  • Schema Conflicts: Multiple developers testing migrations on the same database
  • Data Corruption: Feature A’s test data interfering with Feature B
  • Manual Overhead: Developers spending time on database management instead of coding
  • Inconsistent State: Database state not matching the code branch

Neon’s database branching feature (similar to Git) can solve this, but requires integration with developer workflows.

Decision

Implement automated Neon database branch management integrated with Git hooks.

Implementation

Git Hook Integration:

  • .husky/post-checkout hook automatically triggered on branch switch/creation
  • Detects new branch creation vs. existing branch checkout
  • Calls Node.js script to manage Neon branches

Automated Behavior:

  1. Creating a new Git branch:

    • Creates corresponding Neon branch from develop
    • Fetches connection credentials
    • Updates .env automatically
    • Shows: ✅ Created and switched to ‘feature/X’ Neon DB

  2. Switching Git branches:

    • Checks if Neon branch exists for target Git branch
    • Creates corresponding Neon branch if necessary
    • Fetches credentials
    • Updates .env automatically replacing only the neon related variables
    • Shows: ✅ Switched to ‘feature/X’ Neon DB

  3. Fallback mechanism:

    • If branch creation fails → Use master branch
    • If branch doesn’t exist → Use create a new
    • Shows: ⚠️ Using ‘master’ DB when failed to get current branch credentials

Security:

  • Database passwords in git-ignored .env

Alternatives Considered

1. Manual Branch Management

  • ❌ Error-prone, often forgotten
  • ❌ High cognitive overhead for developers
  • ❌ Inconsistent adoption across team

2. CLI Tool Only (No Git Hooks)

  • ❌ Requires remembering to run commands
  • ❌ Doesn’t prevent database/code mismatch
  • ⚠️ Better than nothing, but not seamless

3. Docker Compose with Local Postgres

  • ❌ Requires Docker setup on all machines
  • ❌ Data not shared across team
  • ❌ Different from production (Neon)
  • ❌ No production-like testing

4. GitHub Actions Integration

  • ❌ Only works for CI/CD, not local development
  • ❌ Doesn’t help with local database switching
  • ⚠️ Could complement this solution for CI

Consequences

Benefits

Developer Experience:

  • Zero Manual Overhead: Database switching happens automatically
  • Isolation: Each feature gets its own database state
  • Safety: Test migrations without affecting others
  • Consistency: Database always matches code branch

Team Productivity:

  • No Conflicts: Developers work with isolated data
  • Faster Onboarding: New developers get automation automatically
  • Fewer Bugs: Reduced database-related issues

Technical:

  • Production Parity: Testing on actual Neon infrastructure
  • Clean Workflows: No shared state pollution
  • Graceful Degradation: Falls back safely on failures

Migration Path

Phase 1: Setup

  1. ✅ Create Neon API integration script
  2. ✅ Implement post-checkout Git hook
  3. ✅ Add npm scripts for manual operations
  4. ✅ Write comprehensive documentation
  5. ✅ Add configuration templates

Phase 2: Team Rollout

  1. Document setup in team wiki/Slack
  2. Each developer runs npm run neon:install-hooks
  3. Each developer configures credentials
  4. Test with a few feature branches
  5. Gather feedback and iterate
  • ADR-0008: Migrate to Neon Database - This automation leverages Neon’s branching feature

References