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](#type-safe-config-invalid-setups-dont-compile) 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 Query Postgres from Neon Functions or existing app handlers. Use the Data API only for PostgREST / Supabase client compatibility and migrations that already depend on it. Do not default new apps to the Data API. Neon is **not** a place to host your app frontend. Neon provides the backend primitives (Lakebase Postgres, Auth, Object Storage, Functions, AI Gateway) that **compose with** the application platform you already use. The Data API is an optional PostgREST-compatible HTTP path, not a required primitive for a new app. Recommended architectures: **New client-only app** — host the UI on Vercel or Netlify; the browser calls a Neon Function; the Function queries Postgres (and Object Storage, Auth, AI Gateway as needed). **Existing full-stack app on Vercel** (or Netlify) — keep the framework's route handlers querying Postgres. Add a Neon Function when a workload needs long-running compute (WebSocket, SSE, a long agent, an MCP server). As long as there is an active connection, a Neon Function can run up to 24 hours without interruption, with the added benefit of running close to your data. **Existing PostgREST or Supabase-js database client** — keep the Data API compatibility path. An installed Supabase package used only for Auth or Storage is not evidence that database access needs PostgREST. A generic request for REST endpoints is a Function or existing-handler request, not a Data API request. Secure a Function like any standalone REST API — verify a JWT or API key at the top of each handler (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. | Need | Use | | --- | --- | | Login, users, sessions (no existing provider) | `neon-auth` — Managed Better Auth (`auth: true`) | | Existing Better Auth, Clerk, Supabase Auth, or another working IdP | Keep it. `neon-auth` only if they ask to migrate | | User asked to migrate from Supabase Auth | `neon-auth` (Managed Better Auth; keep `SupabaseAuthAdapter()` call shapes) | | Files, uploads, blobs (no existing object store) | Object Storage | | HTTP APIs, cron, WebSocket, SSE, long-running agents | Functions querying Postgres | | LLM calls | AI Gateway | | SQL, schema, inspect, search | `neon-postgres` | | Existing PostgREST / Supabase database client | Data API (`dataApi` in `neon.ts`) | | Generic REST endpoints | Function or existing handler, not Data API | Use `neon-auth` to choose identity and to implement Managed Better Auth; the [Auth guide](references/auth.md) 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`](https://github.com/neondatabase/agent-skills) repo: | Skill | Use it for | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `neon-postgres` | Working with databases, including connections, schemas, queries, search, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. | | `neon-auth` | Identity routing and Managed Better Auth setup (login, users, sessions, trusted domains). Fetch: https://neon.com/docs/ai/skills/neon-auth/SKILL.md | | `neon-postgres-branches` | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. | | `neon-object-storage` | Storing and serving files (uploads, images, blobs), including branching them with the database. | | `neon-functions` | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers, and Function Triggers (cron and object-storage). | | `neon-ai-gateway` | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. | | `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase. | 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`](https://github.com/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`: ```bash 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: ```bash 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 ```bash neon --version ``` If that fails, install first: ```bash 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](#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`. `--agent` takes the coding-agent name. `-y` skips prompts but does not supply project selection or credentials. `--skip-template` skips scaffolding a starter app. Link an existing project: ```bash neon init --skip-template --agent cursor \ --org-id <org-id> --project-id <project-id> -y ``` Create and link a project: ```bash neon init --skip-template --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. 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 ```bash neon mcp --oauth --project --agent cursor -y ``` `--oauth` writes the server URL and leaves sign-in to the MCP client. That is not an authenticated MCP session. `--project` means project-level agent config, not a Neon project ID; the agent must support project-level installs (`cursor` does). Bare `neon mcp -y` installs globally and can reuse or mint an account-wide API key — do not treat it as the unattended default. 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 ```bash 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](#installing-the-right-skill)): ```bash 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](#choosing-the-right-skill) above. Non-interactive link: ```bash 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](#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.