Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. Use for any Neon-related questions.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. Use for any Neon-related questions.
Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.
Neon Documentation
The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
Fetching Docs as Markdown
Any Neon doc page can be fetched as markdown in two ways:
Request text/markdown on the standard URL: curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching
Both return the same markdown content. Use whichever method your tools support.
Finding the Right Page
The docs index lists every available page with its URL and a short description:
https://neon.com/docs/llms.txt
Common doc URLs are organized in the topic links below. If you need a page not listed here, search the docs index: https://neon.com/docs/llms.txt — don't guess URLs.
What Is Neon
Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice.
The Neon Admin API can be used to manage Neon resources programmatically. It is used behind the scenes by the Neon CLI and MCP server, but can also be used directly for more complex automation workflows or when embedding Neon in other applications.
Neon REST API
Use this for direct HTTP automation, endpoint-level control, API key auth, rate-limit handling, and operation polling.
Identify the use case — serverless function, long-running server, edge runtime, or CI/CD automation. Determines connection method and driver.
Select connection method — TCP for servers (pooled with -pooler in hostname), HTTP for serverless/edge (@neondatabase/serverless), WebSocket for transactions.
Set up the project — run npx neonctl@latest init for guided setup. Or create a project via Neon Console and copy the connection string.
Install the correct driver — @neondatabase/serverless for serverless/edge. Standard pg for Node.js servers with TCP. @neondatabase/neon-js for auth + data workflows.
Configure pooling — add -pooler to endpoint hostname in serverless environments. PgBouncer under the hood.
Implement branching if needed — create preview branches per PR for isolated testing. Use copy-on-write for instant clones.
Set up scale-to-zero awareness — account for cold-start penalty (~hundreds of ms) on first query after idle. Configure suspend timeout if needed.
Error Handling
Cause
Fix
Cold-start timeout on first query after idle
Account for ~hundreds of ms latency. Warm up with a lightweight query on startup. Disable scale-to-zero on launch & scale plan.
"Too many connections" in serverless environment
Add -pooler to endpoint hostname for PgBouncer connection pooling.
@neondatabase/serverless HTTP query fails with large payload
Switch to WebSocket transactions for queries with large data.
Branch creation fails with "quota exceeded"
Check plan limits. Free plan: 1 branch per project. Delete unused branches first.
Connection string not working from Vercel/Netlify
Verify the connection string includes sslmode=require. Use pooled connection string for serverless.
Migration fails on preview branch but works on main
Branch may have diverged. Reset branch from parent or use neonctl branches create --parent main.
neonctl CLI returns authentication error
Run neonctl auth to re-authenticate. Verify API key is valid and not expired.
Restore point-in-time outside retention window
Check plan limits. Free: 7 days. Scale: 30 days. Business: 90 days. Use closest available point.
Anti-Patterns
Pattern
Problem
Fix
Using standard TCP driver in serverless functions
Connection overhead per invocation. Exhausts available connections rapidly.
Use @neondatabase/serverless with HTTP queries or WebSocket.
Not using pooling in high-concurrency environments
Each request opens a new Postgres connection. Hits connection limits fast.
Add -pooler to hostname. PgBouncer handles connection multiplexing.
Long-running transactions on the serverless driver
HTTP queries have timeouts. Long transactions exceed function execution limits.
Split into smaller transactions. Use WebSocket mode for longer operations.
Hardcoding connection strings in source code
Credential exposure in version control
Use environment variables. Neon Console provides .env ready connection strings.
Creating a full database clone for testing instead of branching
