Neon

Neon is an open-source serverless Postgres platform. It separates compute (stateless PostgreSQL nodes) from storage, replacing PostgreSQL's local file storage with a distributed page service that durably stores WAL across a cluster of nodes and reconstructs database pages on demand at any LSN.

What this repository contains

This monorepo holds every server-side component needed to run a Neon installation, plus the Postgres patches that make stateless compute possible. The work splits into four broad areas:

• Storage services (Rust) — pageserver/, safekeeper/, storage_broker/, storage_controller/, storage_scrubber/, endpoint_storage/. The pageserver ingests WAL, materializes pages on demand, and serves them to compute nodes. The safekeeper is a Paxos-style WAL acceptor that durably accepts WAL from compute. The storage_controller orchestrates pageserver shards across the fleet. The storage_broker mediates discovery between safekeepers and pageservers.
• Compute (Rust + C + Postgres patches) — compute_tools/ (the compute_ctl binary that supervises a Postgres process inside a Neon compute node), compute/ (Dockerfiles and image specs), pgxn/ (the neon Postgres extension that hooks the storage manager to talk to the pageserver), and vendor/postgres-v14..v17 (forks of upstream Postgres).
• Edge / connection management (Rust) — proxy/ is a TLS-terminating Postgres protocol proxy that handles authentication, connection pooling, SQL-over-HTTP, query cancellation, and websocket tunneling. libs/proxy/ holds proxy-specific protocol crates.
• Local control plane and tests (Rust + Python) — control_plane/ provides the neon_local CLI for spinning up a full Neon stack on a developer workstation. test_runner/ is a Python pytest-based integration test framework that exercises the end-to-end system. libs/ contains shared Rust crates used across services.

Who uses this code

The same code that runs on neon.com runs in this repository. A typical reader is one of:

• A storage engineer extending the pageserver, safekeeper, or shard controller.
• A compute engineer changing the neon Postgres extension or upgrading the patched Postgres fork.
• A proxy engineer adding a new authentication backend or wire protocol surface.
• A contributor running cargo neon start locally and adding a feature or fix.
• An operator reading the architecture pages to understand how pageserver tenants are migrated, sharded, or scrubbed.

Quick links

• Architecture — how compute, safekeepers, pageservers, and the broker fit together.
• Getting started — build the project, run a local Neon, and connect with psql.
• Glossary — Neon-specific vocabulary (LSN, timeline, layer, basebackup, walproposer, …).
• Pageserver — the most code-heavy subsystem.
• Safekeeper — the WAL service.
• Proxy — Postgres-over-TCP, websockets, and HTTP.
• How to contribute — branching, PR process, formatting, tests.
• Reference — configuration, data models, dependencies.

Project facts at a glance

• Languages: Rust (≈300k LOC), Python (≈77k LOC, integration tests), C (≈25k LOC, Postgres extension and patches), SQL (migrations and Postgres regression tests).
• Workspace: a single Cargo workspace with 50+ member crates, plus a Poetry-managed Python project for tests, plus a C/Make build for the patched Postgres tree.
• Supported Postgres major versions: 14, 15, 16, 17 (see Makefile's POSTGRES_VERSIONS).
• License: Apache-2.0 (LICENSE, NOTICE).
• First commit: March 2021. Active development with hundreds of commits per quarter.

For the data behind these claims, see by-the-numbers.