How neondatabase/neon works
Neon is a serverless PostgreSQL platform: clients connect to stateless PostgreSQL compute, while pageservers provide durable, branchable storage and safekeepers retain redundant WAL until pageservers process it. The tree also contains the proxy and local control-plane tooling, plus storage coordination and remote-storage implementations. The README documents the principal storage flow and local tenant/endpoint/branch workflow; sampled source confirms selected control-plane and pageserver internals. Several runtime links involving unsampled proxy and compute code remain unverified and are shown as dashed.
Main entry points: local_env.rs Local environment CLI · tenant.rs Pageserver · compute.rs Compute node · wal_storage.rs Safekeeper WAL
Components 18
Client access
- Connection proxy
proxy/src/lib.rs
PostgreSQL compute
- Compute node
compute_tools/src/compute.rs - Compute management API
compute_tools/src/http/server.rs
Neon storage engine
- Pageserver
pageserver/src/tenant.rs - Page service
pageserver/src/page_service.rs - Timeline storage
pageserver/src/tenant/timeline.rs - Storage layers
pageserver/src/tenant/storage_layer.rs - Remote storage
libs/remote_storage/src/lib.rs - Virtual files
pageserver/src/virtual_file.rs - File I/O engine
pageserver/src/virtual_file/io_engine.rs - Safekeeper WAL
safekeeper/src/wal_storage.rs - Storage broker
storage_broker/src/lib.rs
Control and operations
- Storage controller
storage_controller/src/service.rs - Local environment CLI
control_plane/src/local_env.rs - Endpoint object storage
endpoint_storage/src/app.rs
Other components
- SQL client
- Cloud object storage
- PostgreSQL server
Connections 16
- SQL client → Connection proxy: connects through
- Connection proxy → Compute node: routes sessions
- Compute node → PostgreSQL server: runs
README.md - Compute node → Pageserver: uses storage
README.md - Compute node → Safekeeper WAL: sends WAL
README.md - Safekeeper WAL → Pageserver: WAL processed by
README.md - Pageserver → Cloud object storage: uploads data
README.md - Pageserver → Timeline storage: manages timelines
pageserver/src/tenant.rs - Timeline storage → Storage layers: uses layers
pageserver/src/tenant/timeline.rs - Storage layers → Virtual files: performs file I/O
pageserver/src/tenant/storage_layer.rs - Virtual files → File I/O engine: dispatches I/O
pageserver/src/virtual_file.rs - Local environment CLI → Pageserver: starts locally
control_plane/src/local_env.rs - Local environment CLI → Safekeeper WAL: starts locally
control_plane/src/local_env.rs - Local environment CLI → Storage broker: starts locally
control_plane/src/local_env.rs - Local environment CLI → Endpoint object storage: starts process
- Storage controller → Local environment CLI: coordinates local setup