neon

Overview

Neon provides serverless PostgreSQL with scale-to-zero compute, database branching, and an HTTP-based driver for edge runtimes. It offers full PostgreSQL compatibility including extensions like pgvector, with features like copy-on-write branching for development workflows and automatic preview deployment databases.

Instructions

• When setting up connections, use the pooled connection string (-pooler suffix) for serverless functions and the direct connection string for long-running Node.js servers.
• When creating development workflows, use database branching (neon branches create) to give each feature or PR its own isolated database that inherits schema from the parent branch.
• When deploying to edge runtimes (Cloudflare Workers, Vercel Edge), use @neondatabase/serverless which communicates over HTTP instead of TCP sockets.
• When integrating with ORMs, use @prisma/adapter-neon for Prisma or drizzle-orm/neon-serverless for Drizzle, and reserve raw SQL for complex queries and migrations.
• When enabling AI features, install the pgvector extension at project creation for vector embeddings and ANN search.
• When configuring scaling, set autosuspend_delay to 300s for development and 0 (never suspend) for production, and configure compute autoscaling between 0.25 and 8 CU.
• When running migrations, apply them on the main branch so feature branches inherit schema changes automatically.

Examples

Example 1: Set up Neon with Drizzle ORM for a Next.js app

User request: "Connect my Next.js project to Neon using Drizzle ORM"

Actions:

1. Create a Neon project and obtain the pooled connection string
2. Install @neondatabase/serverless and drizzle-orm
3. Configure Drizzle with the Neon serverless adapter
4. Define schema and run initial migration on the main branch

Output: A type-safe database layer using Drizzle with Neon that works in both server components and edge functions.

Example 2: Set up branch-per-PR workflow

User request: "Automatically create a database branch for each pull request"

Actions:

1. Configure Neon-Vercel integration for automatic branch creation
2. Set up CI script using neonctl branches create --name pr-$PR_NUMBER
3. Pass branch connection string as environment variable to preview deployment
4. Add cleanup step to delete branch when PR is closed

Output: An isolated database branch for each PR with automatic lifecycle management.

Guidelines

• Always use the pooled connection string (-pooler suffix) for serverless functions to avoid exhausting connection limits.
• Use @neondatabase/serverless for edge runtimes; use standard pg for long-running Node.js servers.
• Create database branches for each feature or PR; never develop against the main branch.
• Enable pgvector extension at project creation if vector search will be needed.
• Set autosuspend_delay to 300s for dev and 0 for production.
• Use Drizzle or Prisma with the Neon adapter; use raw SQL only for complex queries and migrations.
• Run migrations on the main branch; feature branches inherit schema automatically.