Services

The Neon storage stack is a set of cooperating services. This page is the catalog. Each service has its own page (or directory) below.

A pageserver is the core. Around it, safekeepers durably accept WAL, the storage broker advertises liveness and LSN positions, the storage controller assigns shards to pageservers, and the storage scrubber keeps S3 honest. On the user side, the proxy terminates Postgres protocol connections and forwards them to compute nodes, which are supervised by compute_ctl. The local control plane (neon_local) is the developer-facing CLI that wires all of this together for testing.

Core storage services

Service	Role	Page
Pageserver	Page-level storage; ingests WAL, stores layer files, serves GetPage@LSN, runs WAL-redo.	Pageserver
Safekeeper	Durable WAL acceptor; runs Paxos-style consensus on the WAL stream.	Safekeeper
Storage broker	gRPC pub/sub mesh; pageservers and safekeepers exchange LSN updates.	Storage broker
Storage controller	Shard placement and orchestration across pageservers.	Storage controller
Storage scrubber	Reaps orphaned objects from cloud storage.	Storage scrubber
Endpoint storage	Per-endpoint object store (e.g. for uploaded extensions).	Endpoint storage

Compute and edge

Service	Role	Page
compute_ctl	Per-compute supervisor; configures Postgres, applies spec, manages extensions.	compute_ctl
Proxy	TLS-terminating Postgres protocol proxy; libpq, websockets, SQL/HTTP.	Proxy

Local development

Service	Role	Page
neon_local (cargo neon)	Local control plane; spins up a full Neon stack on a workstation.	Control plane / neon_local

Service interconnections

graph TD
    Compute[Compute Node<br/>postgres + neon ext + compute_ctl] -->|WAL via libpq| SK[Safekeeper]
    Compute -->|GetPage@LSN<br/>libpq + gRPC| PS[Pageserver]
    SK -->|publish<br/>flush_lsn| Broker[Storage Broker]
    PS -->|subscribe| Broker
    PS -->|fetch WAL| SK
    PS <-->|register heartbeat<br/>get assignments| Storcon[Storage Controller]
    Storcon -->|tenant placement DB| StorconDB[(Postgres)]
    PS -->|layer uploads| RemoteStore[(S3 / GCS / Azure)]
    SK -->|WAL backup| RemoteStore
    Scrubber[Storage Scrubber] -->|scan + delete| RemoteStore
    Client[Client] -->|TLS| Proxy[Proxy]
    Proxy -->|libpq| Compute
    EndpointStore[Endpoint Storage] -.->|extensions, etc.| Compute

Repository quick links

Path	Lives	Notes
pageserver/	Cargo crate	Largest single crate; ≈700 source files
safekeeper/	Cargo crate + TLA+ spec	safekeeper/spec/ has the consensus model
storage_broker/	Cargo crate	storage_broker/proto/ for the gRPC schema
storage_controller/	Cargo crate	storage_controller/migrations/ for the metadata DB schema
storage_scrubber/	Cargo crate	Standalone binary
proxy/	Cargo crate	proxy/README.md is the canonical user guide
compute_tools/	Cargo crate	Binary compute_ctl
control_plane/	Cargo crate	Binary neon_local
endpoint_storage/	Cargo crate	Newest service (Apr 2025)

Reading order

If you're trying to understand the system as a whole, the most productive reading order is:

1. Pageserver — the central state machine.
2. Safekeeper — how WAL gets to the pageserver durably.
3. Storage controller — how multiple pageservers are coordinated.
4. Proxy — how clients reach a compute.
5. compute_ctl — how compute nodes are managed.