neon-postgres_skill

Overview

This skill captures expert patterns for using Neon serverless Postgres with branching, connection pooling, and integration with Prisma or Drizzle. It focuses on safe preview-environment workflows, reliable connection management for serverless apps, and repeatable migration and branching practices. The guidance prioritizes predictable resource use and developer ergonomics.

How this skill works

The skill inspects typical Neon setups and recommends concrete patterns: how to create and manage branch databases for previews, how to configure connection pooling for serverless runtimes, and how to wire Prisma or Drizzle to ephemeral databases. It diagnoses common failure modes (exhausted connections, long-lived transactions, migration conflicts) and prescribes mitigations like proper pool sizing, proxy usage, and branch lifecycle rules.

When to use it

• When you need database-per-preview branches for feature environments
• When running Postgres from serverless functions or short-lived containers
• When integrating Prisma or Drizzle with Neon and avoiding connection exhaustion
• When introducing connection pooling or a proxy like PgBouncer
• When planning migrations across branching or ephemeral databases

Best practices

• Use a database per preview branch and attach short-lived credentials scoped to that branch
• Always route serverless connections through a pooling proxy (Neon proxy or PgBouncer) to limit active backend connections
• Configure client pool sizes conservatively: set max clients << Neon backend connection limit and tune per-function concurrency
• Avoid long-lived transactions in preview branches; keep transactions short to prevent resource locks
• Run schema migrations from a controlled CI job against the target branch, not from ephemeral app instances
• Store branch-specific connection URLs and credentials in secure environment variables and rotate after branch deletion

Example use cases

• Creating a preview environment per pull request with an isolated Neon branch and scoped DB credentials
• Deploying a serverless API that uses Prisma with a pooled connection layer to handle bursts of traffic
• Using Drizzle with Neon for a multi-tenant workflow where each tenant gets a branch-like workspace
• CI pipeline that creates a branch, runs migrations, runs tests against that DB, then tears the branch down
• Scaling a read-heavy service by using read replicas for analytics while routing writes to the branch primary