Advisor Neon Champion

An agent for building and optimizing applications on Neon's serverless PostgreSQL platform, covering branching workflows, connection pooling, auto-scaling configuration, and cost optimization for serverless database deployments.

When to Use This Agent

Choose Neon Champion when:

• Setting up Neon serverless PostgreSQL for new projects
• Implementing branching workflows for development and testing
• Configuring connection pooling and auto-scaling for production
• Optimizing Neon costs with compute and storage management
• Migrating from traditional PostgreSQL to Neon's serverless model

Consider alternatives when:

• Working with self-hosted PostgreSQL without Neon (use a PostgreSQL DBA agent)
• Using non-PostgreSQL databases (use a database-specific agent)
• Building application logic without database concerns (use a backend dev agent)

Quick Start

Copy
# .claude/agents/advisor-neon-champion.yml
name: Neon Champion
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a Neon serverless PostgreSQL expert. Help teams build
  on Neon's platform using branching for safe schema changes,
  connection pooling for serverless functions, auto-scaling
  for cost efficiency, and proper backup strategies.

Example invocation:

Copy
claude --agent advisor-neon-champion "Set up a Neon branching
  workflow where each PR gets its own database branch for testing,
  with automatic cleanup when the PR is merged or closed"

Core Concepts

Neon Architecture

Project → Branches → Endpoints (compute) → Databases
  │          │            │
  Settings   main      Auto-suspend (scale to zero)
  Roles      dev       Auto-scaling (0.25 - 8 CU)
  Billing    feature/* Connection pooling (PgBouncer)

Branching Workflow

Branch Type	Purpose	Lifecycle
main	Production data	Permanent
dev	Development testing	Long-lived
preview/*	PR preview environments	Ephemeral (auto-delete)
migration/*	Schema migration testing	Short-lived
snapshot/*	Point-in-time data copies	On-demand

Connection Configuration

Copy
// Serverless function connection with Neon
import { neon } from '@neondatabase/serverless';

// HTTP-based queries (serverless-optimized)
const sql = neon(process.env.DATABASE_URL);
const result = await sql`SELECT * FROM users WHERE id = ${userId}`;

// For connection pooling (long-running processes)
import { Pool } from '@neondatabase/serverless';
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

Configuration

Parameter	Description	Default
auto_suspend_seconds	Time before compute suspends	300 (5 min)
min_cu	Minimum compute units	0.25
max_cu	Maximum compute units	4
pooler_mode	PgBouncer pooling mode	Transaction
branch_cleanup	Auto-delete stale branches	7 days
history_retention	Point-in-time recovery window	7 days
region	Deployment region	us-east-1

Best Practices

1. Use branching for every schema migration. Create a branch from production, apply the migration on the branch, run your test suite against it, and only merge when tests pass. Branches are copy-on-write, so creating a branch with full production data takes milliseconds and costs nothing until you write to it. This gives you a realistic testing environment without maintaining separate databases.

2. Configure connection pooling for serverless deployments. Serverless functions (Vercel, AWS Lambda) create new database connections on every invocation. Without pooling, you'll exhaust connection limits quickly. Use Neon's built-in PgBouncer pooler in transaction mode. The pooled connection string uses port 5432 (pooled) versus 5433 (direct). Always use the pooled string for serverless functions.

3. Set auto-suspend and auto-scaling for cost control. Development branches should auto-suspend after 60 seconds of inactivity to minimize costs. Production endpoints should use a longer suspend timeout (300+ seconds) or stay always-on for latency-sensitive apps. Set minimum compute units to 0.25 for development and scale maximum CU based on peak load testing results.

4. Use the HTTP driver for serverless functions, WebSocket for edge. Neon's @neondatabase/serverless package offers both HTTP and WebSocket transports. HTTP queries have lower cold-start overhead and work in all serverless environments. WebSocket connections support transactions and prepared statements needed for ORMs. Choose based on your runtime environment and query patterns.

5. Implement branch-per-PR workflows with CI automation. Use the Neon API or CLI in your CI pipeline to create a branch when a PR opens, run migrations and tests against that branch, and delete the branch when the PR closes. This eliminates "works on my machine" database issues and catches migration problems before they reach production.

Common Issues

Cold start latency when compute wakes from suspension. When a suspended compute endpoint receives a request, it takes 300-500ms to resume. For latency-sensitive applications, increase the auto-suspend timeout or disable suspension for production endpoints. For development endpoints, accept the cold start as a trade-off for cost savings. Pre-warming scripts that ping the database before expected traffic help reduce user-facing impact.

Connection limit errors from serverless functions. Each Neon compute endpoint has a connection limit based on its CU size. Serverless functions without pooling create a new connection per invocation and quickly exhaust limits. Use the pooled connection string (port 5432) and set max_connections in your application pool to stay within limits. Monitor active connections through the Neon dashboard to right-size your compute CU.

Branch storage costs accumulate unexpectedly. Neon branches use copy-on-write storage, so a branch only consumes storage for data that differs from its parent. However, running heavy write workloads on branches creates divergent data that accumulates cost. Delete branches promptly after merging PRs, set up automated branch cleanup in CI, and monitor storage usage per branch in the Neon console.