Architect Neon Expert

A comprehensive Neon serverless PostgreSQL agent that provides architectural guidance and coordinates specialized sub-agents for schema design, authentication, migration, and performance optimization across Neon's platform features.

When to Use This Agent

Choose Neon Expert when:

• Making architectural decisions about Neon PostgreSQL deployment
• Coordinating between schema design, auth, and migration concerns
• Evaluating Neon features (branching, auto-scaling, read replicas) for your use case
• Planning Neon integration with application frameworks (Next.js, SvelteKit)
• Getting general Neon platform guidance before diving into specifics

Consider alternatives when:

• Focused on Drizzle ORM schema design specifically (use the Neon Architect agent)
• Running specific database migrations (use the Neon Ally agent)
• Setting up Neon branching workflows (use the Neon Champion agent)

Quick Start

Copy
# .claude/agents/architect-neon-expert.yml
name: Neon Expert
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a Neon serverless PostgreSQL expert. Provide architectural
  guidance on Neon features, coordinate between schema design,
  authentication, and migration concerns. Route specialized
  questions to appropriate sub-agents when needed.

Example invocation:

Copy
claude --agent architect-neon-expert "We're building a Next.js
  SaaS application on Neon. Advise on project structure, branching
  strategy, connection pooling, auth integration, and deployment
  workflow for dev → staging → production."

Core Concepts

Neon Platform Features

Feature	Use Case	Configuration
Branching	Dev/test isolation, PR previews	Instant copy-on-write from any point
Auto-suspend	Cost optimization for dev/staging	Configurable idle timeout
Auto-scaling	Handle traffic spikes	Min/max compute units
Read Replicas	Read scaling, geographic distribution	Region-specific endpoints
Point-in-Time Recovery	Data recovery, debugging	Configurable retention window
IP Allow List	Network security	Restrict by CIDR ranges

Architecture Patterns for Neon

Pattern: SaaS with Neon
┌──────────────┐     ┌─────────────────────┐
│  Next.js App │────►│ Neon Project         │
│  (Vercel)    │     │ ┌─────────────────┐  │
│              │     │ │ main branch     │  │ ← Production
│  Serverless  │     │ │ (always-on)     │  │
│  Functions   │     │ └─────────────────┘  │
└──────────────┘     │ ┌─────────────────┐  │
                     │ │ staging branch  │  │ ← Staging
┌──────────────┐     │ │ (auto-suspend)  │  │
│  CI Pipeline │────►│ └─────────────────┘  │
│  (GitHub)    │     │ ┌─────────────────┐  │
│              │     │ │ pr-{num} branch │  │ ← PR Preview
└──────────────┘     │ │ (auto-suspend)  │  │
                     │ └─────────────────┘  │
                     └─────────────────────┘

Specialist Agent Routing

General Neon question → Neon Expert (this agent)
                           │
        ┌──────────────────┼──────────────────┐
        ↓                  ↓                  ↓
  Schema Design      Migrations        Infrastructure
  (Neon Architect)   (Neon Ally)       (Neon Champion)
  Drizzle ORM       Safe changes       Branching
  Relations          Zero-downtime      Auto-scaling
  Indexes            Rollback plans     Connection pool

Configuration

Parameter	Description	Default
project_region	Neon project region	us-east-1
compute_size	Default compute units	0.25 - 4 CU
auto_suspend	Idle suspend timeout	300s (prod), 60s (dev)
pooler_mode	Connection pooling mode	Transaction
history_retention	PITR retention window	7 days
framework	Application framework	Next.js
orm	ORM choice	Drizzle

Best Practices

1. Use one Neon project per application, with branches for environments. Don't create separate projects for staging and production—use branches instead. Branches share the project's configuration, security settings, and are created instantly with copy-on-write semantics. The main branch serves production; named branches serve staging, development, and PR previews. This approach reduces configuration management and ensures environment consistency.

2. Configure compute units based on workload, not peak capacity. Neon auto-scales compute units between a minimum and maximum. Set the minimum to the baseline load (0.25 CU for dev, 1 CU for production) and the maximum to handle peak load (4-8 CU). You pay for actual compute usage, so aggressive minimums reduce costs during low-traffic periods without manual scaling.

3. Route read-heavy workloads to read replicas. Neon read replicas are independent compute endpoints that read from the same storage. Route reporting queries, search indexing, and analytics to read replicas to keep the primary endpoint responsive for transactional workloads. Read replicas can be in different regions for geographic performance optimization.

4. Use Point-in-Time Recovery for data debugging, not just disaster recovery. Neon's branching from a specific point in time lets you create a read-only snapshot of your database at any moment within the retention window. Use this to investigate data issues ("what was the value at 3pm yesterday?") without affecting production or maintaining separate debugging databases.

5. Integrate Neon branching into your CI/CD pipeline. Create a branch for each PR, run migrations and tests against it, and delete it when the PR closes. Use the Neon CLI or API in GitHub Actions. This gives every PR a production-equivalent database for testing without maintaining persistent test databases. Branch creation is sub-second and costs nothing until compute runs.

Common Issues

Application experiences intermittent connection errors. This typically happens during Neon compute cold starts (when auto-suspend resumes the endpoint) or during auto-scaling transitions. Use the @neondatabase/serverless driver which handles reconnection automatically. For TCP connections, implement connection retry logic with exponential backoff. Consider increasing auto-suspend timeout for latency-sensitive production endpoints.

Storage costs higher than expected. Neon bills for total storage across all branches. Long-lived branches that diverge significantly from main accumulate storage for their unique data. Implement automated branch cleanup: delete PR branches when PRs close, delete stale development branches older than 7 days. Monitor storage per branch in the Neon dashboard and set alerts for unexpected growth.

Migrations fail on branch but work locally. Neon's PgBouncer pooling can interfere with migration operations that require session-level consistency. Use the direct connection string (port 5433) for migrations, not the pooled connection (port 5432). If migrations create extensions or modify roles, ensure the Neon project's permissions support those operations—some DDL operations require the neondb_owner role.