Neon Postgres Skill

A Claude Code skill for building applications with Neon — the serverless PostgreSQL platform offering branching, connection pooling, autoscaling, and instant database provisioning for modern development workflows.

When to Use This Skill

Choose this skill when:

• Setting up a serverless PostgreSQL database for a new project
• Configuring Neon with Prisma, Drizzle, or other ORMs
• Using Neon's database branching for preview environments
• Optimizing connection pooling for serverless functions
• Implementing autoscaling databases for production workloads
• Migrating from traditional PostgreSQL to Neon

Consider alternatives when:

• You need a self-managed PostgreSQL instance (use AWS RDS or Docker)
• You need a non-relational database (use MongoDB, DynamoDB)
• You need multiple database engines (use Supabase for Postgres + more)

Quick Start

Copy
# Install Neon serverless driver
npm install @neondatabase/serverless

# Or use with Prisma
npm install prisma @prisma/client

Copy
// Direct connection with Neon serverless driver
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

const users = await sql`SELECT * FROM users WHERE active = true LIMIT 10`;

// Prisma with Neon
// prisma/schema.prisma
// datasource db {
//   provider  = "postgresql"
//   url       = env("DATABASE_URL")  // Pooled connection
//   directUrl = env("DIRECT_URL")    // Direct connection for migrations
// }

Core Concepts

Connection Types

Type	URL Format	Use Case
Pooled	postgres://[email protected]/db?sslmode=require	Application queries (via PgBouncer)
Direct	postgres://[email protected]/db?sslmode=require	Migrations, schema changes
Serverless	HTTP-based via @neondatabase/serverless	Edge functions, serverless

Database Branching

Copy
# Create a branch for preview environment
neonctl branches create --name preview/pr-42

# Each branch is a copy-on-write fork of the parent
# Instant creation, no data copying
# Perfect for PR preview environments

# Delete branch when PR is merged
neonctl branches delete preview/pr-42

Copy
// Automated branching in CI
const branch = await neon.branches.create({
  project_id: projectId,
  branch: { name: `preview/${prNumber}`, parent_id: mainBranchId }
});

// Get connection string for the new branch
const connectionUri = branch.connection_uri;

Prisma Configuration

Copy
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")      // Pooled: for queries
  directUrl = env("DIRECT_DATABASE_URL") // Direct: for migrations
}

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

Configuration

Parameter	Type	Default	Description
DATABASE_URL	string	—	Pooled connection string (required)
DIRECT_DATABASE_URL	string	—	Direct connection for migrations
autoscaling_min	number	0.25	Minimum compute units (CU)
autoscaling_max	number	4	Maximum compute units
suspend_timeout	number	300	Seconds before scaling to zero
pool_size	number	10	Connection pool size per endpoint
region	string	"us-east-2"	Database region

Best Practices

1. Use pooled connections for application queries, direct for migrations — pooled connections go through PgBouncer for connection reuse; direct connections are needed for DDL operations like CREATE TABLE.

2. Enable autoscaling with appropriate min/max — set min: 0.25 to minimize cost during low traffic and max: 4 (or higher) to handle traffic spikes; Neon scales automatically based on query load.

3. Use database branching for preview environments — create a Neon branch for each PR so preview deployments have isolated databases with production-like data; delete branches when PRs are merged.

4. Configure suspend timeout based on traffic patterns — set suspend_timeout: 0 (never suspend) for production databases with consistent traffic; use the default 300 seconds for development and preview branches.

5. Use the @neondatabase/serverless driver for edge functions — the serverless driver uses HTTP-based queries that work in edge runtimes (Vercel Edge, Cloudflare Workers) where TCP connections aren't available.

Common Issues

Cold start latency when database wakes from suspension — Neon scales to zero when idle, causing 1-3 second latency on the first query. Set suspend_timeout: 0 for production or set min: 0.25 CU to keep the database warm.

Prisma migrate fails with pooled connection — DDL operations (CREATE TABLE, ALTER) don't work through PgBouncer. Add directUrl in your Prisma schema pointing to the direct connection string for migrations.

Connection limit exceeded in serverless environment — Each serverless function invocation opens a new connection. Use the pooled connection URL and set pool_size appropriately. For very high concurrency, use the HTTP-based serverless driver instead of TCP connections.