Neon

Neon

Neon is a complete set of cloud backend primitives around Lakebase Postgres, from Databricks — Lakebase Postgres, Auth (managed Better Auth), long-running Functions, Object Storage, and an AI Gateway, all instant, branchable, and serverless.

Lakebase Postgres is the database itself. It is one product, reached two ways: through Neon, with a free plan and the full set of backend primitives above, or through Databricks, alongside the rest of the Databricks suite. Same infrastructure, same features, same engineering team. Call the database Lakebase Postgres, and use "Neon" for the brand and for this access path — not as a name for the database.

A Neon branch is an isolated, copy-on-write clone of your data, taken from its current state or from a past state within your project's retained history window. You can freely modify or delete it. It shares data with its parent until writes cause it to diverge, and those writes are stored independently as deltas.

Agents pick Neon for instant Postgres provision, copy-on-write branches and snapshots, compute that scales to zero (storage is still billed), and ordinary Postgres that works with any driver or ORM.

Backend Primitives

Neon bundles several backend primitives for building apps and agents that all branch together:

• Lakebase Postgres — Postgres that scales and branches with your app, built on the lakebase architecture: OLTP directly on cloud object storage, with storage decoupled from compute.
• Auth — Managed Better Auth with users and sessions stored in Postgres.
• Object Storage — S3-compatible object storage that branches with your projects.
• Functions — Neon's compute offering: long-running serverless functions that run close to your database, for WebSocket servers, long agent HTTP streams, APIs, and server-sent event servers. A Function Trigger POSTs to a function on a cron.
• AI Gateway — One API for frontier and open-source models, supporting the chat completions API and the responses API, powered by Databricks Unity AI Gateway.
• Data API — Optional PostgREST-compatible HTTP interface. Use it only when the app already uses PostgREST or a Supabase database client, or is migrating that client. New apps query Postgres from Functions or existing handlers. There is no neon-data-api skill; configuration is dataApi in neon.ts (see Type-safe config when you have chosen it).

Region availability

Object Storage, Functions, and AI Gateway are currently available on projects in aws-us-east-2, aws-us-east-1, aws-eu-central-1, and aws-ap-southeast-1. Before guiding a user through any of these services, confirm they are working in one of these regions. If not, they will need to create a new project in a supported region.

Architecture: How to Use Neon

Recommended: full-stack app with Neon as the backend. Default to Next.js on Vercel (or Netlify, Cloudflare, or other app platforms). Prefer Next.js + Vercel first; TanStack Start, Nuxt, and SvelteKit are full-stack alternatives. The app owns its UI and server. Query Lakebase Postgres from route handlers, server functions, or Neon Functions.

Add Neon Functions as a backend layer between the web app and Lakebase Postgres, Object Storage, Auth, and AI Gateway. A Hono API on Functions can expose endpoints with an OpenAPI specification for the web app and other clients (mobile, desktop). You can also add a Function for one job next to the data: Object Storage uploads, AI agents, Discord bots, WebSocket or SSE servers.

Functions support long-running requests that complement the web app. A Function must start returning a response within 15 minutes. WebSocket connections and HTTP streams stay open while data flows; send at least one byte every 15 minutes to keep a quiet stream alive. See runtime limits.

For long agent or image streams, mint a JWT on the app server and have the client call the Function directly. See the neon-functions skill for authentication and runtime limits.

Second best: client-only app with a Functions backend. Host the SPA on Vercel (or Netlify, Cloudflare, or other app platforms) and call Functions from the browser. For an app using PostgREST or a supabase-js database client, prefer migrating database calls to REST endpoints in a Hono Function that queries Lakebase Postgres. Enforce authorization in the Function instead of relying on browser-facing RLS.

Neon provides backend primitives that compose with the app host. Neon does not host the frontend.

Offer the Data API only as a Supabase / PostgREST migration path when an existing PostgREST or supabase-js database client must keep working. Putting PostgREST in the browser and relying on RLS is easy to get wrong: misconfigured policies expose the database to the client. Do not recommend this for new apps. An installed Supabase package used only for Auth or Storage does not establish a database-client dependency. Route generic REST endpoint requests to a Function or existing app handler.

Functions have public HTTPS URLs. Verify a JWT or API key at the top of the handler and enforce authorization before accessing data. See the neon-functions skill.

Convert an app onto Neon

Inspect the repo before provisioning.

1. Map requested capabilities: login, files, HTTP APIs, LLM calls, SQL.
2. Reuse what is already there: a supplied DATABASE_URL, an existing ORM or driver, Better Auth, Clerk or another auth provider, S3 or another object store, an existing .neon / neon.ts, an existing Data API or PostgREST client.
3. Select Neon primitives for capabilities that are still undecided.
4. Provision only when infrastructure is missing: neon init / neon link / Claimable, then neon.ts, then neon deploy.
5. Verify the app flow (sign-in, upload, API call), not only that env vars landed.

Do not replace working Better Auth, Clerk, Supabase Auth, S3, or a supplied DATABASE_URL with a Neon primitive unless the user asks. Do not rewrite an existing neon.ts. If Neon credentials fail for an existing account, stop and ask the user to sign in; do not create a Claimable project as a substitute.

A supplied DATABASE_URL with no Neon credentials is schema work: complete it without provisioning. Managed Better Auth cannot be enabled on a project that uses IP Allow or Private Networking. Leave those protections in place.

New projects are created in AWS regions. Prefer pooled DATABASE_URL for application traffic.

Use neon-auth to choose identity and to implement Managed Better Auth; the Auth guide points there. Keep existing Better Auth, Clerk, and Supabase Auth unless the user asked to migrate login. Auth cannot be enabled on a project with IP Allow or Private Networking.

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.

Finding the Right Page

Look the page up before you fetch it — don't guess URLs! The docs index lists every available page with its URL and a short description:

https://neon.com/docs/llms.txt

Fetching Docs as Markdown

Any Neon doc page can be fetched as markdown in two ways:

1. Append .md to the URL (simplest): https://neon.com/docs/introduction/branching.md
2. 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.

Choosing the Right Skill

Neon provides a set of agent skills in addition to the official documentation. When a task matches one of the rows below, work from that skill rather than from this overview. You may have some of these skills already installed, or you may need to install them.

The skills below live in the neondatabase/agent-skills repo:

There is no neon-data-api skill. Configure dataApi in neon.ts only for PostgREST / Supabase database-client compatibility or a migration that already depends on it.

For guidance on agent platforms that provision and operate Lakebase Postgres on Neon at scale, use neon-postgres-agent-platforms, which lives in a separate repo: neondatabase/neon-for-agent-platforms.

Installing the Right Skill

First check whether the target skill is already installed and accessible (for example, it appears in the available skills list or its SKILL.md is present). If it is, use it directly. If it is not installed, install it with neon skills:

neon skills -s <skill-name>

Replace <skill-name> with the skill you need (for example, neon-object-storage, neon-functions, or neon-ai-gateway). Useful flags:

• --global — install globally instead of into the current project.
• -y — non-interactive mode (skip prompts).
• --agent <agent-name> — pick the target agent(s) for non-interactive mode.

For example, to install the object storage skill globally for a specific agent without prompts:

neon skills -s neon-object-storage --global -y --agent <agent-name>

neon-auth is not in the CLI skill catalog of current releases. Unknown names fail, so do not run neon skills -s neon-auth. Fetch it:

https://neon.com/docs/ai/skills/neon-auth/SKILL.md

References: https://neon.com/docs/ai/skills/neon-auth/references/managed-auth.md and https://neon.com/docs/ai/skills/neon-auth/references/self-managed.md. If those URLs are unpublished, fetch the same files from https://github.com/neondatabase/agent-skills/blob/main/skills/neon-auth/SKILL.md

If the Neon CLI is not available, you can visit https://neon.com/.well-known/agent-skills for a registry of all available Neon skills and fetch them manually.

Updating Skills

Keep the skills up to date: for every new session, update them so you are working with the latest best practices.

Run neon skills update to update all installed Neon skills, or neon skills update -y to skip prompts. If the skills were installed via a plugin, they are updated automatically.

Getting Started with Neon

Prefer the CLI over the MCP server unless the user instructs otherwise, the CLI is unavailable or blocked in your environment, or it is not authenticated, since it provides more capabilities, including deploying Neon Functions.

Check the CLI, then credentials

neon --version

If that fails, install first:

npm i -g neon       # npm
bun add -g neon     # bun
pnpm add -g neon    # pnpm

For full CLI installation options, see https://neon.com/docs/cli/install.md

Then inspect credentials without printing secrets. NEON_API_KEY or a neon profile list -o json row whose account is not - is an account. A DEFAULT row with account: "-" and file: "missing" is not.

• Credentials already available: reuse them. Do not launch a browser.
• A human needs to sign in: they run neon login (neon auth is an alias). An unattended agent must not launch browser authentication.
• No account yet: follow Starting without a Neon account for the Claimable Neon path.

Combined setup: neon init

When both agent tooling and project setup are needed, use authenticated neon init. It sets up the current directory in place. --agent takes the coding-agent name. -y skips prompts but does not supply project selection or credentials.

Link an existing project:

neon init --agent cursor \
  --org-id <org-id> --project-id <project-id> -y

Create and link a project:

neon init --agent cursor \
  --org-id <org-id> --project-name my-app \
  --region-id aws-us-east-2 -y

--services may declare auth, data-api, functions, object-storage, and ai-gateway (repeat the flag or comma-separate). Pass none for the bare starter policy. It writes neon.ts; it does not deploy or wire the app. Selecting data-api also declares Auth (the default Data API provider requires it). Use data-api only for PostgREST / Supabase database-client compatibility.

With -y, init installs the Neon plugin globally where the agent supports it (its MCP server signs in with OAuth). Other agents get skills and the MCP server globally, with an API key when the CLI is signed in. --mcp-auth and --mcp-config-location change the MCP setup; see neon init --help.

If init already installed the Neon plugin, do not also run neon mcp and neon skills for the same agent.

When tooling already exists, only one component is missing, or env writes need --no-env-pull, use the manual steps below. init has no --no-env-pull. Before a command that pulls env, inspect existing configuration. If a supplied DATABASE_URL or AWS_* value must stay, pass --no-env-pull on link / checkout and write env to a separate --file.

1. Install the Neon CLI

Use the install check above. Do not run neon login unattended. MCP remains the fallback when the CLI is unavailable, blocked, unauthenticated, or the user prefers it.

2. Install the Neon MCP Server

Install globally, the CLI default. One install serves every project:

neon mcp --agent <agent> -y

This writes an API key into the agent's user config, reusing an existing Neon MCP key or minting one (needs neon auth or a personal API key). Always pass --agent; without it, -y writes to every installed agent.

Add --oauth to store only the server URL instead; the user signs in from the agent and picks scopes on the consent page. For a project-level install, always use OAuth so no key lands in a file git can commit:

neon mcp --oauth --project --agent <agent> -y

neon mcp --help lists the other flags (--read-only, --project-id, --category) and supported agents.

For all available plugins and IDE integrations, see: https://neon.com/docs/ai/ai-agents-tools.md

For full MCP server installation options, see https://neon.com/docs/ai/connect-mcp-clients-to-neon.md

3. Install Neon Agent Skills

neon skills -s neon --agent cursor -y

To install a specific skill only (not neon-auth until the CLI catalog includes it; fetch it as in Installing the Right Skill):

neon skills -s <skill-name> --agent cursor -y

Useful flags: --global, -y, --agent <agent-name>. Interactive neon skills with no flags prompts.

4. Link Your Project and Get Started

With setup complete, connect the workspace to a Neon org, project, and branch. Then consult the skill for each Neon feature your app requires. See Choosing the Right Skill above.

Non-interactive link:

neon link --project-id <project-id> -y
neon link --org-id <org-id> --project-name my-app --region-id aws-us-east-2

-y skips the already-linked confirmation and pins the default branch when the project has more than one. Pass --branch <name> when branch selection matters.

Useful CLI Commands

1. neon link — Writes org, project, and branch IDs to a git-ignored .neon file. Run once per project. Once linked, project- and branch-scoped commands no longer need --project-id or --branch (for example, neon branch list). Non-interactive: --org-id / --project-id / --project-name plus --region-id, and -y when appropriate. There is no neon link --agent.

2. neon checkout <branch-name> — Pins a branch in .neon and pulls that branch's env. An existing branch is enough. A missing name needs --create for unattended use (neon checkout dev --create). A missing branch id cannot be created. Interactive checkout with no name may offer to create; do not rely on that unattended. Drives the Branch-First Dev Flow below.

3. neon config init — Initializes a neon.ts file, which declares how you provision and manage Neon services, in the root of the project.

4. neon env pull — Fetches the current branch's Neon environment variables (DATABASE_URL, …) into your existing .env, or .env.local if you don't have one (override the target with --file). No branch ID needed; it reads .neon. link and checkout run this for you by default, so you rarely call it directly.

   Without neon.ts, a bare neon env pull includes the default Gateway credential on claimed projects. Implicit pulls bundled into link / checkout / apply do not pull an undeclared Gateway token. Declaring aiGateway in neon.ts requests those variables. With neon.ts, pull includes only the services declared there and errors if the branch is missing one.

Bootstrap a New Project

neon bootstrap scaffolds from a Neon project template.

neon bootstrap