Skip to main content

Built-On Neon — Reference Architecture

This is the reference architecture for a product built on Neon, where the partner provisions a dedicated Neon Lakebase Postgres for each customer, application, or agent and manages its full lifecycle through the Neon API. It is organized around that lifecycle — provision, configure, connect, operate, and meter.

The goal is a framework you can design and validate against, not a reproduction of Neon's product documentation. Each page links to the Neon reference for exact fields and payloads.

In this Section​

PageWhat it covers
Provisioning & LifecycleCreating a project per tenant and choosing the provisioning credential (organization API key, project-scoped key, or personal key).
Compute, Scaling & LimitsAutoscaling and scale-to-zero configuration, and consumption quotas for cost control and plan tiers.
Connectivity & Data AccessControl-plane vs. data-plane access, connection pooling, and reading and writing data.
Telemetry & MeteringPer-customer consumption metrics and fleet inventory metrics.
Use CasesHow the framework is tuned for agents vs. a longer-lived platform database.

Core Principles​

The Project is the Unit of Tenancy​

In Neon, a project is an isolated Postgres cluster with its own branches, databases, roles, and compute. Map one project to one tenant — a customer, an application, or an agent — so isolation, quotas, metering, and lifecycle all operate on a natural boundary. Do not multiplex unrelated tenants into shared databases within one project; that erases the isolation and per-tenant metering that make this architecture worthwhile.

Documentation: Manage projects | Multitenancy | Embedded Postgres (project-per-user)

The Control Plane and the Data Plane are Separate​

Two distinct paths carry two distinct kinds of credential, and conflating them is the most common design error:

  • The control plane — creating projects, setting quotas, reading usage — is driven by the partner backend using a Neon API key. These credentials must never reach the browser or the tenant.
    • Organization API key — the credential for the central provisioning and metering service. It spans the whole fleet. Creating a project and reading org-level consumption require it.
    • Project-scoped API key — use it only to manage an existing project, for example adjusting one tenant's quota. It cannot create projects. It cannot read org-level usage.
    • See Which credential should you use? for the full decision.
  • The data plane — reading and writing rows — is driven by a Postgres connection string scoped to a per-tenant role, used to run SQL. A Neon project-scoped API key manages a single project through the API; it is not how an application connects to run queries. Keep these separate in your design and your secret storage. See Connectivity & Data Access.

Automate the Entire Lifecycle​

At fleet scale — hundreds to hundreds of thousands of databases — every lifecycle step must be programmatic and idempotent: provision, configure compute and quotas, retrieve the connection string, run migrations, suspend, restore, and delete. Neon's public reference at scale is Retool operating 300k+ databases with a single engineer — made possible only because no step required human action.

Operations Are Asynchronous​

Many Neon API calls (project and branch creation, for example) return an operations array and complete asynchronously. Poll operation status before issuing dependent requests, handle 423 Locked responses on conflicting work, and respect the API rate limits.

End-to-End Architecture​

The steps map to the pages in this section: provisioning (1–2) is covered in Provisioning & Lifecycle; compute and quota configuration in Compute, Scaling & Limits; connection retrieval and query traffic (3) in Connectivity & Data Access; and usage polling (4) in Telemetry & Metering.

Note the two control-plane credentials on the edges into the Neon API. The provisioning and metering services use an organization API key across the fleet. A support or admin tool uses a project-scoped API key confined to a single tenant's project. See Which credential should you use?.

What's Next​