Name: neon
Author: neondatabase

Overview of Neon, a complete set of cloud backend primitives for apps and agents, spanning Lakebase Postgres, Auth, the Data API, Object Storage, Compute Functions, and the AI Gateway. Start here to route to the right Neon skill, set up the CLI or MCP server, and follow the branch-first workflow. Us

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, an AI Gateway, and Realtime live queries, 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. Realtime (beta) — Makes any SQL query live. Subscribe in realtime to Lakebase Postgres and build reactive apps and agents with type safe live queries and optimistic mutations. 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, AI Gateway, and Realtime 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](https://neon.com/docs/compute/functions/overview.md) 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](https://neon.com/docs/compute/functions/reference/runtime limits.md). 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. Small static pages: a public read bucket. Neon provides backend primitives that compose with a frontend hosting provider like Vercel (or Netlify, Cloudflare, etc.), which ships static hosting and a CDN. Use one for any app frontend. For prototypes and small pages that ship with a Neon backend, a public read Object Storage bucket is enough: Swagger UI, Mastra Studio, OAuth verification screens, sign in pages for Neon Auth, and personal software. The bucket serves each object at its URL with the Content Type set on upload. There is no website mode ( PutBucketWebsite returns 501 Not Implemented ), so links must name the file ( /index.html ), and there are no SPA fallbacks or custom domains. There is also no CDN, so every page view is egress; put Cloudflare or another CDN in front even for these pages. See the neon object storage skill for bucket setup. 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, live data, 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, custom WebSocket or SSE push, long running agents Functions querying Postgres Live queries for realtime, reactive apps and agents; optimistic mutations neon realtime ( preview.realtime in neon.ts ). Not available on Claimable projects until claimed 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: 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 realtime Realtime makes any SQL query live, for realtime, reactive apps and agents: enabling Realtime, sealing queries, React and TanStack DB bindings, SSR, and optimistic mutations. neon postgres egress optimizer Diagnosing or fixing excessive Postgres egress (network data transfer) costs in a codebase.