playbooks

home / skills / xfstudio / skills / neon-postgres

neon-postgres skill

/neon-postgres

This skill helps you configure Neon Postgres patterns for serverless apps, including Prisma, Drizzle, and PgBouncer pooling, with separate URLs for migrations.

npx playbooks add skill xfstudio/skills --skill neon-postgres

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.6 KB
---
name: neon-postgres
description: "Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, database branching, neon postgres, postgres serverless."
source: vibeship-spawner-skills (Apache 2.0)
---

# Neon Postgres

## Patterns

### Prisma with Neon Connection

Configure Prisma for Neon with connection pooling.

Use two connection strings:
- DATABASE_URL: Pooled connection for Prisma Client
- DIRECT_URL: Direct connection for Prisma Migrate

The pooled connection uses PgBouncer for up to 10K connections.
Direct connection required for migrations (DDL operations).


### Drizzle with Neon Serverless Driver

Use Drizzle ORM with Neon's serverless HTTP driver for
edge/serverless environments.

Two driver options:
- neon-http: Single queries over HTTP (fastest for one-off queries)
- neon-serverless: WebSocket for transactions and sessions


### Connection Pooling with PgBouncer

Neon provides built-in connection pooling via PgBouncer.

Key limits:
- Up to 10,000 concurrent connections to pooler
- Connections still consume underlying Postgres connections
- 7 connections reserved for Neon superuser

Use pooled endpoint for application, direct for migrations.


## ⚠️ Sharp Edges

| Issue | Severity | Solution |
|-------|----------|----------|
| Issue | high | See docs |
| Issue | high | See docs |
| Issue | high | See docs |
| Issue | medium | See docs |
| Issue | medium | See docs |
| Issue | low | See docs |
| Issue | medium | See docs |
| Issue | high | See docs |

Overview

This skill documents expert patterns for using Neon serverless Postgres with Prisma and Drizzle, plus guidance on connection pooling and branching. It focuses on practical configuration: pooled app connections, direct migration connections, and selecting the right Neon drivers for serverless or edge environments. Use it to avoid common pitfalls and scale serverless Postgres safely.

How this skill works

The guide explains using two connection strings: a pooled DATABASE_URL for application queries via PgBouncer and a DIRECT_URL for direct connections needed by migrations and DDL. It also maps Drizzle driver choices (neon-http vs neon-serverless) to transaction and latency characteristics. Finally, it outlines Neon’s pooling limits and reserved connections so you can size and instrument your app correctly.

When to use it

  • Building apps on Neon serverless Postgres
  • Using Prisma or Drizzle ORMs with Neon
  • Running migrations or DDL against Neon
  • Deploying to edge or serverless runtimes where connections are ephemeral
  • Needing to tune connection pooling for high-concurrency workloads

Best practices

  • Use two separate URLs: pooled DATABASE_URL for runtime and DIRECT_URL for migrations/DDL
  • Route application traffic through the pooled endpoint (PgBouncer) to avoid exhausting backend Postgres connections
  • Reserve direct connections only for migration tools and administrative tasks
  • Choose Drizzle driver by workload: neon-http for simple one-off queries, neon-serverless for multi-statement transactions and session affinity
  • Monitor pool utilization and underlying Postgres connections; account for Neon’s 7 reserved superuser connections

Example use cases

  • Serverless API with Prisma: app uses pooled DATABASE_URL; CI uses DIRECT_URL to run migrations.
  • Edge functions with Drizzle: use neon-http for short-lived queries and neon-serverless when transactions span requests.
  • High-concurrency web service: scale app instances without sky-rocketing Postgres connection counts by relying on PgBouncer pooling.
  • CI/CD pipeline: run schema migrations against DIRECT_URL to ensure DDL succeeds without pooler interference.

FAQ

Why two connection strings instead of one?

Use the pooled connection for runtime to protect Postgres from too many direct connections. Use the direct connection for migrations and DDL because PgBouncer can block some schema-changing commands.

Which Drizzle driver should I pick for serverless functions?

Pick neon-http for the fastest, stateless single-query calls. Choose neon-serverless when you need transactions, multi-statement sessions, or lower-latency session handling.