Glossary

Neon borrows heavily from PostgreSQL vocabulary and adds storage-engine-specific terms. The full reference is docs/glossary.md in the repo; the entries below cover the words that appear most often in the wiki.

Core domain concepts

Tenant — A single Neon customer. Tenants are the unit of isolation in the pageserver: each tenant has its own set of timelines, layer files, WAL-redo process, and quotas. One pageserver process serves many tenants. See pageserver/src/tenant.rs and Tenant and timeline.

Timeline — A linear history of WAL belonging to a tenant. Timelines are exposed to users as branches. A new timeline can be created at any point on its parent's WAL stream and then diverges. Internally a timeline has a last_record_lsn, a disk_consistent_lsn, a remote_consistent_lsn, and an ancestor_lsn. See pageserver/src/tenant/timeline.rs.

Branch — User-facing name for a timeline. Created with cargo neon timeline branch.

LSN (Log Sequence Number) — A 64-bit byte offset into the WAL stream. Printed as two hex numbers separated by /, e.g. 0/16B5A50. Almost every Neon API takes an (tenant_id, timeline_id, LSN) triple. See LSN and WAL.

Shard — A horizontal partition of a tenant. Block ranges of relations are mapped to a shard via a stable hash. The storage controller assigns shards to pageservers.

Storage layout

Layer — A unit of pageserver storage covering a key range and an LSN range. Two kinds:

• Image layer — A snapshot of pages for a key range at a single LSN.
• Delta layer — WAL records for a key range across an LSN range.

See pageserver/src/tenant/storage_layer.rs and Storage layers.

Layer map — In-memory index of which layers exist for a timeline. pageserver/src/tenant/layer_map.rs.

L0 / L1 layer — L0 layers cover the entire key space and a narrow LSN range (the output of an in-memory layer flush). Compaction reshuffles L0 layers into L1 layers, each covering the entire LSN range but a narrow key range.

In-memory layer (ephemeral) — WAL freshly received from safekeepers, held in pageserver/src/tenant/ephemeral_file.rs until checkpointed to an L0 file.

Compaction — Background job that turns L0 layers into L1 layers and eventually creates new image layers, reducing the depth of the redo chain. See docs/pageserver-compaction.md and pageserver/compaction/.

Garbage collection — Removal of layer files that are no longer needed by any timeline within the configured PITR horizon.

WAL pipeline

WAL (Write-ahead log) — Postgres's durability journal. Every change is appended as a WAL record before the page is modified.

WAL record — A single entry in the WAL.

WAL segment — A fixed-size file (16 MB by default) containing a contiguous slice of WAL.

WAL redo — Replaying a WAL record on top of a base page image to produce a newer page image. Neon does this in a sandboxed Postgres process started in --wal-redo mode. See pageserver/src/walredo.rs and WAL redo.

Walproposer — The compute-side component (a C library inside the neon extension) that proposes WAL records to a quorum of safekeepers. Implements a Paxos variant. See libs/walproposer/, pgxn/neon/.

Walreceiver — The pageserver-side component that pulls WAL from a safekeeper and feeds the in-memory layer.

Safekeeper — A node in the WAL service that durably accepts WAL records and forwards them to pageservers. Forms a quorum. See Safekeeper.

Compute and protocol

Compute node — A stateless Postgres process running in a Neon-built image. The Postgres binary is from vendor/postgres-v*, supervised by compute_ctl.

compute_ctl — Per-compute supervisor written in Rust (compute_tools/). Configures Postgres, applies the spec, downloads requested extensions, and exposes an HTTP control API.

Basebackup — A tarball of files needed to bootstrap a compute node onto a timeline at a given LSN. Generated by the pageserver (pageserver/src/basebackup.rs). Distinct from upstream Postgres pg_basebackup.

Page service — The pageserver's GetPage@LSN server. Speaks a custom binary protocol over either the libpq wire format or gRPC. See pageserver/src/page_service.rs.

GetPage@LSN — Read of a specific page at a specific LSN. The fundamental compute → storage operation.

Backpressure — Mechanism that throttles compute writes when the pageserver or safekeepers fall behind. Tuned via max_replication_write_lag, max_replication_flush_lag, max_replication_apply_lag.

Cluster orchestration

Storage broker — A small gRPC service that pageservers and safekeepers use to publish/subscribe to LSN updates so they can find each other without a central coordinator. storage_broker/.

Storage controller — Cluster manager that assigns shards to pageservers and orchestrates migration and reconciliation. storage_controller/.

Storage scrubber — Tool that scans cloud storage and removes orphaned objects. storage_scrubber/.

Pageserver / safekeeper generation — A monotonically increasing number used to fence stale instances during failover and migration. Stored in tenant metadata.

Internal Postgres terms

Relation — A Postgres table, index, sequence, or other on-disk object with a name and a list of attributes.

Fork — A separate file series for a relation: the main fork holds row data, the FSM (free space map) and VM (visibility map) hold metadata.

SLRU — Postgres's "simple LRU" caches: pg_clog, pg_multixact/*. Neon stores a subset persistently.

Checkpoint (Postgres) — A point in the WAL where all dirty buffers have been flushed.

Checkpoint (Neon) — Distinct from above: writing the in-memory layer to a new L0 layer file when it grows past checkpoint_distance.

XLOG — Postgres's old name for WAL.

For the full glossary including PITR, retention policy, replication slot, segment, etc., see docs/glossary.md.