Neon Database Architect Guru

An agent specialized in Neon serverless PostgreSQL schema design, Drizzle ORM integration, and serverless performance optimization for building efficient, well-structured database layers in modern web applications.

When to Use This Agent

Choose Neon Database Architect when:

• Designing database schemas for Neon serverless PostgreSQL
• Integrating Drizzle ORM with Neon for type-safe database access
• Optimizing query performance in serverless execution contexts
• Building migration workflows using Drizzle Kit
• Implementing connection pooling strategies for serverless functions

Consider alternatives when:

• Setting up Neon infrastructure and branching (use the Neon Champion agent)
• Performing database migrations without schema design (use a migration agent)
• Working with non-Neon PostgreSQL databases (use a general PostgreSQL agent)

Quick Start

Copy
# .claude/agents/neon-database-architect-guru.yml
name: Neon Database Architect
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a Neon database architect specializing in schema design,
  Drizzle ORM integration, and serverless performance optimization.
  Design schemas that work efficiently with Neon's serverless
  architecture and connection pooling model.

Example invocation:

Copy
claude --agent neon-database-architect-guru "Design a Drizzle ORM
  schema for a SaaS application with users, organizations, projects,
  and activity logging, optimized for Neon's serverless model
  with proper indexing and relations"

Core Concepts

Drizzle ORM Schema Design

Copy
import { pgTable, uuid, varchar, timestamp, text,
         integer, boolean, jsonb, index } from 'drizzle-orm/pg-core';
import { relations } from 'drizzle-orm';

export const users = pgTable('users', {
  id: uuid('id').primaryKey().defaultRandom(),
  email: varchar('email', { length: 255 }).notNull().unique(),
  name: varchar('name', { length: 255 }),
  organizationId: uuid('organization_id').references(
    () => organizations.id
  ),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
}, (table) => ({
  emailIdx: index('idx_users_email').on(table.email),
  orgIdx: index('idx_users_org').on(table.organizationId),
}));

export const usersRelations = relations(users, ({ one, many }) => ({
  organization: one(organizations, {
    fields: [users.organizationId],
    references: [organizations.id],
  }),
  projects: many(projects),
}));

Neon Configuration

Copy
// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  schema: './src/db/schema.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,  // Neon pooled connection
  },
});

Connection Strategies

Context	Connection Type	Configuration
Serverless functions	HTTP (neon driver)	@neondatabase/serverless
Long-running server	Pooled TCP	Port 5432 (PgBouncer)
Migrations	Direct TCP	Port 5433 (direct)
Edge functions	HTTP	@neondatabase/serverless with WebSocket

Configuration

Parameter	Description	Default
orm	ORM framework	Drizzle
connection_mode	Default connection strategy	Pooled
schema_location	Schema file path	src/db/schema.ts
migrations_dir	Migration output directory	drizzle/
uuid_version	UUID generation strategy	v4 (random)
timestamp_handling	Timestamp type preference	TIMESTAMPTZ
soft_delete	Soft delete column pattern	deletedAt nullable

Best Practices

1. Use the Neon serverless driver for edge and serverless functions. The @neondatabase/serverless package provides HTTP-based queries that don't require persistent connections, making it ideal for serverless functions that scale to zero. Use it with Drizzle's neon-http adapter for type-safe queries without connection pool overhead. Reserve TCP connections for long-running application servers.

2. Design schemas with connection pooling constraints in mind. Neon uses PgBouncer for connection pooling in transaction mode, which means prepared statements and session-level features (temp tables, SET commands) don't work across transactions. Structure queries to be self-contained within single transactions and avoid relying on session state.

3. Co-locate indexes with the query patterns in your Drizzle schema. Define indexes in the table definition using the third argument to pgTable. This keeps the index definition next to the columns it covers, making it easy to verify that queries have appropriate index support. Review indexes when adding new query patterns and remove indexes when the queries they serve are retired.

4. Use Drizzle's relational queries for read operations and raw queries for writes. Drizzle's relational query API generates efficient JOINs and nested selects for reading data. For complex writes (upserts, bulk operations, CTEs), use Drizzle's sql template literal for direct SQL control. This combination gives type safety for reads and full SQL power for writes.

5. Run migrations through direct connections, not pooled ones. Migration operations (CREATE TABLE, ALTER TABLE, CREATE INDEX) should use Neon's direct connection (port 5433) rather than the pooled connection (port 5432). PgBouncer in transaction mode can interfere with DDL operations that require session-level consistency. Configure separate connection strings for migrations and runtime.

Common Issues

Drizzle queries fail with "prepared statement does not exist" in pooled mode. PgBouncer in transaction mode doesn't support prepared statements because connections are shared between clients. Configure Drizzle to use the neon-http adapter for serverless or set prepare: false in the Drizzle PostgreSQL adapter configuration to use simple protocol queries.

Schema changes break Drizzle's type inference. When you modify a table schema, all queries using that table become type-incompatible until the TypeScript project is rebuilt. Run drizzle-kit generate after schema changes to create migration files, then rebuild the TypeScript project to update type inference. Consider separating the schema package as a shared module in monorepo setups.

Connection errors during cold starts in serverless functions. Neon computes may suspend after inactivity. The first request after suspension triggers a cold start (300-500ms). Handle this with connection retry logic in your database client initialization. The @neondatabase/serverless HTTP driver handles this transparently. For WebSocket connections, implement a connection health check before query execution.