Neon: serverless Postgres with storage and compute split apart

The problem Neon solves: Postgres compute that holds no data

A conventional PostgreSQL deployment ties the database process to its data directory. Scaling reads means copying storage or adding replicas that still own a full copy of the data; scaling to zero means stopping a process that is the only holder of the state. Neon breaks that tie. The README describes it as an open-source serverless Postgres database platform that "separates storage and compute and substitutes the PostgreSQL storage layer by redistributing data across a cluster of nodes."

The audience is therefore narrower than "anyone using Postgres". It is teams that want Postgres semantics but need compute nodes to be disposable, and platform engineers willing to run a storage engine alongside the database. A single application with one database and steady traffic gets little from the split; the extra processes are overhead. The payoff appears when you want many short-lived Postgres instances, or compute that starts and stops independently of where the bytes live.

Pageserver, safekeepers and the WAL path

The architecture has two halves. Compute nodes are stateless PostgreSQL nodes backed by the Neon storage engine. The storage engine itself has two major components, per the README: the pageserver, a scalable storage backend for the compute nodes, and the safekeepers, which form a redundant WAL service that receives WAL from the compute node and stores it durably until the pageserver has processed it and uploaded it to cloud storage.

That ordering matters. The compute node does not wait for the pageserver before acknowledging a commit; it waits for the safekeepers, which hold the WAL durably. The pageserver then consumes WAL, materializes pages, and pushes them to object storage. A slow pageserver degrades read latency, not write durability. The repository layout reflects this separation: `pageserver/`, `safekeeper/`, `storage_broker/`, `storage_controller/`, and `proxy/` are separate workspace members in Cargo.toml, and `libs/walproposer` and `libs/wal_decoder` sit under libs. The broker is described in the README's own output as existing "for their intercommunication", which tells you the components discover each other through it rather than through static configuration alone. The storage_controller directory exists in the tree but the README does not describe its role, so treat it as undocumented here.

Building Neon locally on Linux and macOS

The README's local instructions are for a workstation, explicitly "for small experiments and to test code changes". On Ubuntu or Debian the package list is long and includes build tools, protobuf, and Python poetry:

apt install build-essential libtool libreadline-dev zlib1g-dev flex bison libseccomp-dev \
libssl-dev clang pkg-config libpq-dev cmake postgresql-client protobuf-compiler \
libprotobuf-dev libcurl4-openssl-dev openssl python3-poetry lsof libicu-dev

On macOS, Xcode command line tools plus Homebrew packages come first, and the README notes that OpenSSL must be on PATH for ed25519 key generation in neon_local:

xcode-select --install
brew install protobuf openssl flex bison icu4c pkg-config m4
brew install libpq
brew link --force libpq

One constraint is easy to miss: the README warns that the path to the neon sources cannot contain a space, and that building requires protoc 3.15 or newer. The clone is recursive because Postgres is a submodule:

git clone --recursive https://github.com/neondatabase/neon.git
cd neon
make -j`nproc` -s

The default is a debug build, which the README calls demonstrably slower than a release build; `BUILD_TYPE=release` switches profiles. The Makefile lists supported PostgreSQL versions as v17, v16, v15 and v14, and installs into `./pg_install` unless POSTGRES_INSTALL_DIR is set.

First run: init, start, and a tenant

Once built, the workflow runs from the repository root. `cargo neon init` creates a repository in `.neon` with paths to binaries and data, and the README notes that a package install script would later own this step:

cargo neon init
cargo neon start

The expected output names the endpoints: the broker at 127.0.0.1:50051, pageserver node 1 at 127.0.0.1:64000, and safekeeper 1 at 127.0.0.1:5454. You should see three processes reported as started. Then create the first tenant and make it the default for later invocations:

cargo neon tenant create --set-default

The README shows this printing a tenant id and creating an initial timeline. From there, connect with psql or another Postgres client; the README points at the postgresql-client package or at adding `pg_install/bin` and `pg_install/lib` to PATH and LD_LIBRARY_PATH respectively. Note what is missing: the README stops at tenant creation and does not walk through creating a branch, connecting an application, or tearing the environment down. If you want the hosted product instead, the README points at the Neon Free Tier signup and the online SQL Editor.

Where the split hurts

The clearest limitation is stated in the Dockerfile itself: the image "is mainly used as a container for the binaries and for starting e2e tests with custom parameters", and by default the binaries "have some mock parameters and can start, but are not intended to be used inside this image in the real deployments." Anyone hoping to lift the Dockerfile into production should read that twice. The README's local instructions carry the same caveat in different words: a workstation setup is for small experiments.

The second cost is operational surface. A conventional Postgres is one process and one data directory. Neon adds a broker, at least one safekeeper, and a pageserver, each with its own port and its own failure behaviour. The README documents starting them and nothing about restarting, upgrading, or recovering a safekeeper that falls behind. That silence is the real risk: the durability story depends on safekeepers holding WAL until the pageserver has processed it, and the README does not describe what happens when that backlog grows. Finally, the build is heavy. Patched Postgres, a Rust workspace with dozens of members, protobuf, and a pinned toolchain via rust-toolchain.toml mean the first build is not a five-minute affair, and non-rustup users are told they must verify their toolchain manually.

Neon compared with Supabase and plain Postgres

The related searches pair Neon with Supabase, and the difference in approach is architectural rather than feature-level. Supabase is a Postgres-backed platform that bundles database, auth, storage and APIs around a Postgres instance; the database itself remains a conventional Postgres with its own storage. Neon's bet is the opposite: it keeps the Postgres wire protocol and SQL surface but replaces the storage layer underneath, which is what makes stateless compute nodes possible. If you want a batteries-included backend, the storage split buys you nothing. If you want compute that can be created and discarded cheaply, it is the whole point.

Against plain PostgreSQL, the trade is complexity for elasticity. A single Postgres server with a local data directory has one process to reason about, one backup story, and no broker. Neon gives you the split and the resulting operational shape. The repository does ship a `proxy/` workspace member and a `control_plane/` directory, which suggests the pieces for a managed control plane are in the tree, but the README does not document how to run them, so do not assume the open-source build gives you the hosted product's management layer.

Licence and the cost of staying current

Neon is Apache-2.0, declared in Cargo.toml under `[workspace.package]` and shipped as a LICENSE file at the repository root, with a NOTICE file alongside it. Apache-2.0 is permissive, permits commercial use and modification, and includes a patent grant; it also requires that you preserve the NOTICE file and state changes you make. That is a description of the licence text, not legal advice, and the NOTICE file is worth reading before you redistribute anything.

The upgrade cost is the part the README does not help with. There is no documented migration path between versions, no compatibility statement for the on-disk format, and no rollback procedure. The Makefile pins supported PostgreSQL versions to v14 through v17, and rust-toolchain.toml pins the Rust toolchain used in CI, so a build that worked six months ago may need toolchain and dependency updates before it compiles again. The release tags in the repository are component-scoped (release-proxy-8853, release-compute-9073, release-9129), which suggests components version independently rather than as one product. If you run this yourself, budget for reading the source rather than the README when you upgrade.

Editorial conclusion

Adopt Neon if you want Postgres with stateless compute nodes and a storage layer you can run yourself, and you are willing to build patched Postgres from source. Do not adopt it if you need a single-node database with no extra services, or if you expect `cargo neon` to be a production deployment tool: the Dockerfile says its image is for binaries and end-to-end tests, not real deployments. Before committing, verify that your environment has protoc 3.15 or newer, that the neon source path contains no space, and that you have a plan for the safekeeper and pageserver processes, because the README documents `cargo neon start` and nothing about upgrading a running installation.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. neondatabase/neon on GitHub
3. Project website
4. README
5. Releases