Neon Team Setup

1. Prerequisites

Ensure these environment variables are set (loaded by scripts/setup-env.sh):

Install the Neon CLI: npm install -g neonctl

2. Run Team Setup

The scripts/neon-team-setup.sh script (uses set -euo pipefail per project convention):

For each developer (default: sebastian, alex, jake):

1. Create Neon branch dev/{name} from main via neonctl branches create
2. Create database role dev_{name} via neonctl roles create
3. Apply schema using psql with branch connection string + ontology/schema.sql
4. Apply migrations from ontology/migrations/ (if any exist)
5. Grant permissions on all tables in the branch
6. Output connection string for each developer

3. Configure Git Hooks

After team setup, activate the post-checkout hook:

git config core.hooksPath .githooks

This is done automatically by make team-setup.

4. Connect DBeaver (Optional)

Follow docs/dbeaver-setup.md for GUI database access:

1. New PostgreSQL connection in DBeaver Community Edition
2. Host: extract from branch connection string (e.g., ep-xxx.us-east-2.aws.neon.tech)
3. Port: 5432
4. Database: neondb
5. Username/Password: from branch credentials
6. Driver Properties: sslmode=require
7. Initialization: Keep-Alive = 60 seconds (prevents Neon scale-to-zero disconnect)
8. Save separate connections for each developer branch

Git Hook: Auto-Branch Provisioning

The .githooks/post-checkout hook triggers on git checkout:

1. Skip conditions: file checkout (not branch), detached HEAD, main branch
2. New worktrees: copies .env from main worktree if missing
3. Branch creation: creates a Neon branch matching the git branch name (idempotent -- safe to re-run)
4. Env update: writes the branch-specific NEON_DATABASE_URL to .env

This means every git checkout -b feature/my-feature automatically provisions a Neon branch with its own compute endpoint.

Branch Naming Convention

Parallel Subagent Integration

The feature-developer and data-optimizer subagents (.claude/agents/) use isolation: worktree which:

1. Creates a git worktree for the agent
2. Triggers the post-checkout hook
3. Provisions a dedicated Neon branch
4. Agent works on isolated code + isolated database
5. Worktree cleaned up automatically if no changes made

This enables multiple Claude Code agents to develop features in parallel without database conflicts.

Implementation

Cross-References

• For monitoring the database: use the neon-dashboard skill
• For REST API access: use the neon-api skill
• For SQL query patterns: use make sql (Harlequin) or the neon-dashboard SQL screen