Claude Code for Neon DB Branching — Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using Neon’s database branching feature, which creates instant copy-on-write branches of your PostgreSQL database — similar to Git branches but for your data. Each branch is a full PostgreSQL instance with its own connection string, sharing storage with the parent branch until data diverges. Claude Code can manage databases, but it creates separate database instances instead of using Neon’s branching.

What Claude Code Gets Wrong By Default

  1. Creates separate databases for each environment. Claude writes scripts to dump and restore databases for staging. Neon branching creates instant copies without data movement — neonctl branches create --name staging gives you a full database branch in seconds.

  2. Uses pg_dump for database copies. Claude runs pg_dump and pg_restore to clone data. Neon branches use copy-on-write at the storage level — branching a 100GB database is instant and costs nothing until data diverges.

  3. Manages connection strings manually. Claude hardcodes different connection strings for each environment. Neon provides connection strings per branch through the API and CLI — use neonctl connection-string --branch-name dev to get the right connection.

  4. Does not clean up test branches. Claude creates branches but never deletes them. Neon branches consume storage for diverged data — delete branches after merge with neonctl branches delete.

The CLAUDE.md Configuration

# Neon Database Branching

## Database
- Provider: Neon (serverless PostgreSQL)
- Feature: Database branching (copy-on-write)
- CLI: neonctl for branch management
- API: Neon API for automation

## Neon Branching Rules
- Create: neonctl branches create --name feature-x
- Connect: neonctl connection-string --branch-name feature-x
- Delete: neonctl branches delete feature-x
- Parent: branches from main by default
- Point-in-time: branch from specific timestamp
- Reset: neonctl branches reset --name dev --parent

## Conventions
- main branch: production data
- dev branch: development (reset weekly from main)
- Feature branches: per PR, deleted after merge
- CI: create branch per test run, delete after
- Preview deploys: each preview gets its own branch
- Use neonctl in CI scripts for automation
- Connection string from Neon API, not hardcoded

Workflow Example

You want to set up a preview environment with its own database branch for each pull request. Prompt Claude Code:

“Create a GitHub Actions workflow that creates a Neon database branch for each pull request, sets the connection string as an environment variable for the preview deployment, and deletes the branch when the PR is closed. Use neonctl.”

Claude Code should create a GitHub Actions workflow with two jobs: one on pull_request: opened/synchronize that runs neonctl branches create --name pr-$PR_NUMBER and outputs the connection string, and one on pull_request: closed that runs neonctl branches delete pr-$PR_NUMBER, using the GitHub event number variable.

Common Pitfalls

  1. Branch divergence eating storage. Claude creates branches and writes significant test data. Neon branches share storage with the parent via copy-on-write, but writes on the branch consume additional storage. Reset or delete test branches regularly.

  2. Missing Neon API token in CI. Claude uses neonctl commands in CI without setting up authentication. Add NEON_API_KEY as a CI secret and set the project ID with --project-id for neonctl commands to work in automated pipelines.

  3. Point-in-time branch confusion. Claude creates branches expecting current data but gets stale data. By default, branches are created from the parent’s current state. For a specific point in time, use --at flag — but be aware of Neon’s retention limits.