neon-postgres
Skill923 starsChanged 5 months agoMITView on GitHub
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.
We split this skill into the rules it gives an agent
21 rules. 9 are common, 5 are distinctive, and 7 are very specific to this project.
9
Common
Most of the 22 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 35
Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice.
- Distinctive: line 41
Use this for first-time setup: org/project selection, connection strings, driver installation, optional auth, and initial schema setup.
- Distinctive: line 47
Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, …
- Very specific: line 53
Use this for @neondatabase/serverless patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations.
- Distinctive: line 59
Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup.
- Very specific: line 65
Use this for local development enablement with npx neonctl@latest init, VSCode extension setup, and Neon MCP server configuration.
- Very specific: line 71
Use this for terminal-first workflows, scripts, and CI/CD automation with neonctl.
- Distinctive: line 81
Use this for direct HTTP automation, endpoint-level control, API key auth, rate-limit handling, and operation polling.
- Very specific: line 87
Use this when implementing typed programmatic control of Neon resources in TypeScript via @neondatabase/api-client.
- Very specific: line 93
Use this when implementing programmatic Neon management in Python with the neon-api package.
- Very specific: line 99
Use this for managed user authentication setup, UI components, auth methods, and Neon Auth integration pitfalls in Next.js and React apps.
- Common: line 107
Use this when the user is planning isolated environments, schema migration testing, preview deployments, or branch lifecycle automation.
- Common: line 113
Use the neonctl CLI or MCP server to create, inspect, and compare branches.
- Common: line 119
Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior.
- Common: line 125
Use this when optimizing idle costs and discussing suspend/resume behavior, including cold-start trade-offs.
- Common: line 137
Use this when the user needs point-in-time recovery or wants to restore data state without traditional backup restore workflows.
- Common: line 149
Use this for read-heavy workloads where the user needs dedicated read-only compute without duplicating storage.
- Common: line 161
Use this when the user is in serverless or high-concurrency environments and needs safe, scalable Postgres connection management.
- Very specific: line 166
Add -pooler to endpoint hostnames to use pooled connections.
- Common: line 173
Use this when the user needs to restrict database access by trusted networks, IPs, or CIDR ranges.
- Common: line 179
Use this when integrating CDC pipelines, external Postgres sync, or replication-based data movement.
“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Neon Serverless Postgres
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:
- Append
.mdto the URL (simplest): https://neon.com/docs/introduction/branching.md - Request
text/markdownon 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.txtCommon 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.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/what-is-neon.md
Getting Started
Use this for first-time setup: org/project selection, connection strings, driver installation, optional auth, and initial schema setup.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/getting-started.md
Connection Methods & Drivers
Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, long-running).
Link: https://neon.com/docs/ai/skills/neon-postgres/references/connection-methods.md
Serverless Driver
Use this for @neondatabase/serverless patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-serverless.md
Neon JS SDK
Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-js.md
Developer Tools
Use this for local development enablement with npx neonctl@latest init, VSCode extension setup, and Neon MCP server configuration.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/devtools.md
Neon CLI
Use this for terminal-first workflows, scripts, and CI/CD automation with neonctl.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-cli.md
Neon Admin API
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.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-rest-api.md
Neon TypeScript SDK
Use this when implementing typed programmatic control of Neon resources in TypeScript via @neondatabase/api-client.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-typescript-sdk.md
Neon Python SDK
Use this when implementing programmatic Neon management in Python with the neon-api package.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-python-sdk.md
Neon Auth
Use this for managed user authentication setup, UI components, auth methods, and Neon Auth integration pitfalls in Next.js and React apps.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/neon-auth.md
Neon Auth is also embedded in the Neon JS SDK - so depending on your use case, you may want to use the Neon JS SDK instead of Neon Auth. See https://neon.com/docs/ai/skills/neon-postgres/references/connection-methods.md for more details.
Branching
Use this when the user is planning isolated environments, schema migration testing, preview deployments, or branch lifecycle automation.
Key points:
- Branches are instant, copy-on-write clones (no full data copy).
- Each branch has its own compute endpoint.
- Use the neonctl CLI or MCP server to create, inspect, and compare branches.
Link: https://neon.com/docs/ai/skills/neon-postgres/references/branching.md
Autoscaling
Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior.
Link: https://neon.com/docs/introduction/autoscaling.md
Scale to Zero
Use this when optimizing idle costs and discussing suspend/resume behavior, including cold-start trade-offs.
Key points:
- Idle computes suspend automatically (default 5 minutes, configurable) (unless disabled - launch & scale plan only)
- First query after suspend typically has a cold-start penalty (around hundreds of ms)
- Storage remains active while compute is suspended.
Link: https://neon.com/docs/introduction/scale-to-zero.md
Instant Restore
Use this when the user needs point-in-time recovery or wants to restore data state without traditional backup restore workflows.
Key points:
- Restore windows depend on plan limits.
- Users can create branches from historical points-in-time.
- Time Travel queries can be used for historical inspection workflows.
Link: https://neon.com/docs/introduction/branch-restore.md
Read Replicas
Use this for read-heavy workloads where the user needs dedicated read-only compute without duplicating storage.
Key points:
- Replicas are read-only compute endpoints sharing the same storage.
- Creation is fast and scaling is independent from primary compute.
- Typical use cases: analytics, reporting, and read-heavy APIs.
Link: https://neon.com/docs/introduction/read-replicas.md
Connection Pooling
Use this when the user is in serverless or high-concurrency environments and needs safe, scalable Postgres connection management.
Key points:
- Neon pooling uses PgBouncer.
- Add
-poolerto endpoint hostnames to use pooled connections. - Pooling is especially important in serverless runtimes with bursty concurrency.
Link: https://neon.com/docs/connect/connection-pooling.md
IP Allow Lists
Use this when the user needs to restrict database access by trusted networks, IPs, or CIDR ranges.
Link: https://neon.com/docs/introduction/ip-allow.md
Logical Replication
Use this when integrating CDC pipelines, external Postgres sync, or replication-based data movement.
Key points:
- Neon supports native logical replication workflows.
- Useful for replicating to/from external Postgres systems.
Link: https://neon.com/docs/guides/logical-replication-guide.md
Other versions27 projects use a version of this.
Word for word · 5
- coinacci/TravelMintNFT★ 69100% same
- Xenonesis/code-guardian-report★ 48100% same
- SamarthPyati/Open-Source-Scout★ 4100% same
- Pantessa/website★ 1100% same
- sayuru-akash/web-audit-mcp★ 1100% same
Edited · 17
- xai-org/plugin-marketplace★ 31652% same
- mezotv/notra★ 25617% same
- usenotra/notra★ 25617% same
- neondatabase/agent-skills★ 10816% same
- jaakla/openmapstack★ 7616% same
- jaakla/openmapstack-skills★ 7616% same
- iyashjayesh/tokenchit★ 1516% same
- LeonardoTrapani/better-skills★ 1195% same
- vercel-labs/hatchery★ 730% same
- AbdulSamad94/Legalyze-AI★ 237% same
7 more not listed
Wrote their own version · 5
- xfstudio/skills★ 9same name
- ai4brands-design/claude-skills★ 2same name
- Ghosteken/agent-harness★ 2same name
- liuchiawei/agent-skills★ 2same name
- chenson42/stackkeel★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use neon-postgres-branches, neon-auth and 4 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
xAISkillneon-postgres-branches
Choose and create the right Neon branch type for testing and development. Use when users ask about Neon branching, migration testing with real data, isolated test environments, schema-only branch workflows for sensitive data, or branch creation via Neon CLI or Neon MCP. Triggers include "Neon branch", "test migrations safely", "branch production data", "schema-only branch", "reset branch" and "sensitive data testing".
Also in 5 projects that use this
neondatabaseSkillneon-auth
Add authentication to a new app. Use for "add auth", "add login", Neon Auth (Managed Better Auth), identity routing, sign-up, sign-in, password reset, email OTP, magic links, organizations, phone OTP, OAuth, OAuth server for MCP or third-party OAuth clients, passkeys, MFA, trusted domains, invalid domain, and @neon/auth. No existing identity: default to Managed Better Auth. Keep working Better Auth, Clerk, Supabase Auth, or another IdP. User asked to migrate from Supabase Auth: Managed Better Auth. A required plugin outside Managed support: self-managed Better Auth on a Neon Function or the existing app host. Also use for auth APIs in @neon/neon-js.
Also in 5 projects that use this
sayuru-akashSkillneon-postgres-egress-optimizer
Diagnose and fix excessive Postgres egress (network data transfer) in a codebase. Use when a user mentions high database bills, unexpected data transfer costs, network transfer charges, egress spikes, "why is my Neon bill so high", "database costs jumped", SELECT * optimization, query overfetching, reduce Neon costs, optimize database usage, or wants to reduce data sent from their database to their application. Also use when reviewing query patterns for cost efficiency, even if the user doesn't explicitly mention egress or data transfer.
Also in 5 projects that use this
- neondatabaseSkill
neon-ai-gateway
One API and one credential for frontier and open-source LLMs and embedding models, built into your Neon branch and powered by Databricks. Use when a user wants to call an LLM, generate embeddings, add AI/chat/an agent to their app, route between model providers (OpenAI, Anthropic, Google/Gemini, Meta, Alibaba, and more), or avoid juggling separate provider API keys and accounts — especially when they already use Neon and want AI requests to branch with their project. Works with the OpenAI SDK, Anthropic SDK, google-genai, the Vercel AI SDK, and Mastra by changing only the base URL. Triggers include "call an LLM", "add AI to my app", "chat completion", "model routing", "LLM proxy/gateway", "one API for all models", "use Claude/GPT/Gemini", "AI SDK", "Mastra agent", "Neon AI Gateway", "generate embeddings", "generate images", and "log/rate-limit AI calls".
Also in 4 projects that use this
- +2 more from neondatabase
In this repository30 other files it gives its agents.
- .agents/skills/composition-patterns/AGENTS.mdAGENTS.md
- .agents/skills/react-best-practices/AGENTS.mdAGENTS.md
- .agents/skills/react-hook-form/AGENTS.mdAGENTS.md
- .agents/skills/zod/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/nextjs-cursor-rule.mdcCursor rule
- accessibilitySkill
- bash-defensive-patternsSkill
- better-auth-best-practicesSkill
- vercel-composition-patternsSkill
- drizzle-ormSkill
- email-and-password-best-practicesSkill
- frontend-designSkill
- next-best-practicesSkill
- next-cache-componentsSkill
- next-upgradeSkill
- nodejs-backend-patternsSkill
- nodejs-best-practicesSkill
- organization-best-practicesSkill
- vercel-react-best-practicesSkill
- react-hook-formSkill
- seoSkill
- shadcnSkill
- tailwind-css-patternsSkill
- tailwind-v4-shadcnSkill
- turborepoSkill
- two-factor-authentication-best-practicesSkill
- typescript-advanced-typesSkill
- ai-sdkSkill
- zodSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.