neon-postgres
Guides and best practices for working with Lakebase Postgres, the database behind Neon. Covers setup, connection methods and drivers, pooled vs direct connections, branching, schema migrations, autoscaling, scale-to-zero, instant restore, read replicas, connection pooling, IP allow lists, and logical replication. Also covers Lakebase Search: semantic vector search, full-text search with BM25 ranking, and hybrid search. Use when users ask about "Lakebase Postgres", "Neon setup", "connect to Neon", "Neon project", "DATABASE_URL", "serverless Postgres", "Neon CLI", "neon", "Neon MCP", "Neon Auth", "@neondatabase/serverless", "@neondatabase/neon-js", "scale to zero", "Neon autoscaling", "Neon read replica", "Neon connection pooling", "schema migrations", "database troubleshooting", "Postgres performance", "neon inspect db", "semantic search", "vector search", "full-text search", "BM25", or "hybrid search".
neondatabase · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add neondatabase/agent-skills --skill neon-postgres技能说明
name: neon-postgres description: >- Guides and best practices for working with Lakebase Postgres, the database behind Neon. Covers setup, connection methods and drivers, pooled vs direct connections, branching, schema migrations, autoscaling, scale-to-zero, instant restore, read replicas, connection pooling, IP allow lists, and logical replication. Also covers Lakebase Search: semantic vector search, full-text search with BM25 ranking, and hybrid search. Use when users ask about "Lakebase Postgres", "Neon setup", "connect to Neon", "Neon project", "DATABASE_URL", "serverless Postgres", "Neon CLI", "neon", "Neon MCP", "Neon Auth", "@neondatabase/serverless", "@neondatabase/neon-js", "scale to zero", "Neon autoscaling", "Neon read replica", "Neon connection pooling", "schema migrations", "database troubleshooting", "Postgres performance", "neon inspect db", "semantic search", "vector search", "full-text search", "BM25", or "hybrid search". metadata: parent: neon source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres
FIRST: Use the parent neon skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
If the neon skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
npx skills add neondatabase/agent-skills --skill neon
Lakebase Postgres
Lakebase Postgres is the database at the core of Neon. It runs on the lakebase architecture — OLTP built directly on cloud object storage — which decouples storage from compute 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.
It is the same database whether you reach it through Neon or through Databricks; this skill covers the Neon access path.
Setup Flow
1. Select the organization and project
Use the CLI (default) or MCP server to list organizations and projects. Let the user select an existing project or create a new one. Check the .neon file for an existing linked project or branch.
2. Get the connection string
Use the CLI (default), neon env pull, or the MCP server to get the connection string. Store it in .env as DATABASE_URL. Read the file first before modifying it, to avoid overwriting existing values.
When to use pooled vs direct connections
| Use case | Connection type |
|---|---|
| Web applications, serverless functions | Pooled (-pooler) |
| Schema migrations | Direct |
| pg_dump / pg_restore | Direct |
| Logical replication | Direct |
| Long-running analytics with temp tables | Direct |
| Admin tasks needing SET or session state | Direct |
| LISTEN / NOTIFY | Direct |
3. Pick the connection method and driver
Always pair Neon with an ORM such as Drizzle for easy schema management and migrations. Refer to the connection methods guide to pick the correct driver based on how the runtime treats your code: https://neon.com/docs/connect/choose-connection.md.
Recommendations:
- Drizzle as ORM (see https://neon.com/docs/guides/drizzle.md)
- On Vercel, use
node-postgres(npm install pg) with Vercel Fluid compute andimport { attachDatabasePool } from "@vercel/functions"; - On Cloudflare, use
node-postgreswith Cloudflare Hyperdrive - On Neon Functions, use
node-postgres, as the functions are long-running and reuse the pool across requests. - Use the
@neondatabase/serverlessdriver for serverless and edge environments (for example, when using Netlify) — HTTP transport for one-shot queries, WebSocket for transaction support. Link: https://neon.com/docs/serverless/serverless-driver.md
4. Set up the schema
Manage schemas and migrations as code. Avoid running ad hoc schema migrations against your database, since they're hard to manage.
If you're using an ORM, follow your ORM's best practices to manage schemas and migrations. For example, if using Drizzle, only use Drizzle for schema and migration management unless instructed otherwise.
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 neon CLI or MCP server to create, inspect, and compare branches.
Link: https://neon.com/docs/introduction/branching.md
For detailed branch creation workflows (normal vs schema-only branches, reset-from-parent, CLI/MCP selection), use the neon-postgres-branches skill. If it isn't installed, fetch it from https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md or install it with:
npx skills add neondatabase/agent-skills --skill neon-postgres-branches
Migrations
Test a migration on a branch of production, against production-like data, before applying it to production.
Use a direct (non-pooled) connection string when you run the migration, not a pooled one. neon connection-string returns the direct string by default; make sure the hostname does not include the -pooler suffix.
Troubleshooting and Neon-Specific Performance
Use Neon's predefined, read-only diagnostics before writing catalog queries by hand. The Neon CLI neon inspect db subcommands and the Neon MCP server's inspect_database tool run the same checks.
This section covers Neon-specific diagnostic tools, compute cache behavior, and platform signals. When the evidence points to generic Postgres work such as rewriting a query, choosing an index, changing a schema, or interpreting plan nodes, load the [postgres-best-practices](https://github.com/ne