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:

neon skills -s neon -y

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

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 and import { attachDatabasePool } from "@vercel/functions";
• On Cloudflare, use node-postgres with Cloudflare Hyperdrive
• On Neon Functions, use node-postgres, as the functions are long-running and reuse the pool across requests.
• Use the @neondatabase/serverless driver 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:

neon skills -s neon-postgres-branches -y

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` skill and carry the diagnostic evidence into that workflow.

Docs:

• CLI: https://neon.com/docs/cli/inspect.md
• Query performance: https://neon.com/docs/postgresql/query-performance.md
• pg_stat_statements: https://neon.com/docs/extensions/pg_stat_statements.md
• Neon Local File Cache: https://neon.com/docs/extensions/neon.md

Choose CLI or MCP

Prefer the Neon CLI when terminal access and authentication are available:

neon inspect db <check>

The CLI resolves the project and branch from the current Neon context. Use --project-id, --branch, and --database-name to override it. Omit --database-name to inspect every database on the branch. Use --db-url only when inspecting a Postgres database directly instead of resolving it through the Neon API.

When using Neon MCP, call inspect_database with projectId and one check. Pass branchId, databaseName, or computeId only when needed. Omit databaseName to inspect all databases on the branch. Increase limit only when the result says it was truncated.

Pick the Diagnostic

Do not confuse these checks:

• long-running-queries reports statements running right now for more than five minutes.
• outliers ranks the top queries by cumulative execution time since statistics were reset. It does not rank by mean latency.
• calls ranks by execution count over the same statistics history.

outliers and calls require pg_stat_statements. lfc-hit-rate and working-set require the neon extension. If a check reports a missing extension, ask before running the suggested CREATE EXTENSION statement because installing an extension modifies the database.

Interpret Results Safely

• Treat unused-indexes as a candidate list, not permission to drop indexes. Confirm the observation window, constraints, and workload before removal.
• A sequential scan can be correct for a small table or a query reading much of a table. Check table size, selectivity, and the query plan before adding an index.
• bloat is a statistical estimate. Confirm the impact and plan locks or maintenance before VACUUM FULL, REINDEX, or similar remediation.