skill

Neon Postgres

Guides and best practices for working with Lakebase Postgres on Neon: connections, pooled vs direct, schema migrations, branching (including schema-only, reset-from-parent, and branch-per-PR workflows), autoscaling, scale-to-zero, instant restore, read replicas, IP allow lists, logical replication, egress optimization, and Lakebase Search. Use when the work is an existing DATABASE_URL, SQL, schema, inspect, or search. New backends, Auth, files, Functions, and LLM calls go to the parent `neon`...

neondatabase310,776+ installsVetted

About

**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:

```bash 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.

Login, users, sessions, and `@neon/auth` belong in `neon-auth`.

Live queries, reactive UIs, and realtime data belong in `neon-realtime`.

## Setup Flow

### 1. Select the organization and project

If a `DATABASE_URL` is already supplied (prompt, environment, or repo) or a `.neon` file points at a project, use it. Do not list organizations or create a second project for schema work.

Otherwise use the CLI (default) or MCP server to list organizations and projects. Let the user select an existing project or create a new one.

### 2. Get the connection string

If a `DATABASE_URL` is already supplied, use it. Do not fetch another through the CLI or MCP.

Otherwise 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

Preserve the existing ORM and driver. For new TypeScript schema work with no established choice, Drizzle is a suggestion: https://neon.com/docs/guides/drizzle.md. 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.

Driver notes:

- 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, and CI/CD patterns), read [Branching workflows](references/branching.md).

## 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.

## Egress Optimization

Use this when a user reports high database bills, unexpected network transfer, egress spikes, query overfetching, or wants a cost-efficiency review of database query patterns.

Before editing code, read [Egress optimization](references/egress-optimization.md). Audit all five patterns: unused columns, missing pagination, repeated static reads, application-side aggregation, and JOIN duplication. Do not stop after fixing `SELECT *`.

Work in

Install

Run this command

npx skills add neondatabase/agent-skills

Works with

claude appclaude codeclaude apicursorcodexwindsurfclinezed

Manual steps

Install with `npx skills add neondatabase/agent-skills`, or clone the repository and copy the `skills/neon-postgres` folder into your Claude skills directory.

View source

Frequently asked questions

What is the Neon Postgres skill?

Guides and best practices for working with Lakebase Postgres on Neon: connections, pooled vs direct, schema migrations, branching (including schema-only, reset-from-parent, and branch-per-PR workflows), autoscaling, scale-to-zero, instant restore, read replicas, IP allow lists, logical replication, egress optimization, and Lakebase Search. Use when the work is an existing DATABASE_URL, SQL, schema, inspect, or searc…

How do I install Neon Postgres?

Run this in your terminal:

npx skills add neondatabase/agent-skills
Which AI tools does Neon Postgres work with?

It works with claude_app, claude_code, claude_api, cursor, codex, windsurf, cline, zed.

Who made Neon Postgres?

neondatabase.

Is Neon Postgres free?

Yes, it is free to use.

Related assets

More curated picks in Data & Analytics.

All Neon Postgres alternatives →
skillclaude_appclaude_codeclaude_api
npx skills add heygen-com/hyperframes
Hyperframes Registry
About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, m…1,218,043+
skillclaude_appclaude_codeclaude_api
npx skills add microsoft/azure-skills
Microsoft Foundry
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, a…702,909+
skillclaude_appclaude_codeclaude_api
npx skills add google/agents-cli
Google Agents CLI Observability
This skill should be used when the user wants to "set up tracing", "monitor my agent", "configure logging", "add observability", "debug production tra…568,165+
skillclaude_appclaude_codeclaude_api
npx skills add microsoft/azure-skills
Azure Kusto
Query and analyze data in Azure Data Explorer (Kusto/ADX) using KQL for log analytics, telemetry, and time series analysis. WHEN: KQL queries, Kusto d…552,598+
skillclaude_appclaude_codeclaude_api
npx skills add microsoft/azure-skills
Azure Storage
Azure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers…546,701+
skillclaude_appclaude_codeclaude_api
npx skills add mattpocock/skills
Wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentia…424,988+

Audit before you install

Run any source through our checks - AI visibility, security, performance, and stack detection.

More in Data & Analytics