Extensions and Postgres fork

Neon delivers a stateless Postgres compute. Achieving that requires both:

1. A Postgres extension (pgxn/neon) that hooks Postgres's storage manager to send page reads and WAL writes over the network.
2. A small set of patches to upstream Postgres (vendor/postgres-v{14,15,16,17}) for hooks the upstream code does not yet expose.

This section covers both. The detailed technical writeups in the repo are docs/core_changes.md (what was changed and why in upstream Postgres) and the READMEs inside pgxn/.

Pages

• The neon Postgres extension — pgxn/neon and friends. The smgr replacement, walproposer, and supporting extensions.
• The vendored Postgres fork — what's in vendor/postgres-v*, the kinds of changes made to upstream, and the upgrade workflow.

Why extensions and patches together

The clean ideal would be to use only Postgres extensions and avoid patching the core. In practice, several integration points need core changes:

• Storage manager (smgr) hook. Postgres's smgr layer was not pluggable enough to install a network-backed implementation purely from an extension. Patches add hook points for smgr_open, smgr_read, smgr_write, etc.
• WAL proposer hook. WAL needs to be sent to safekeepers as it's written, not after group-commit. Patches add hooks at the WAL insertion layer.
• Resource managers (rmgrs) registration. Neon adds custom WAL record types via pgxn/neon_rmgr/; the extension API for custom rmgrs varies between Postgres versions.

Each major Postgres version has its own vendored tree because the patch set has to be reapplied — the upstream code drifts and Neon's patches need to be ported.

Build flow

The Makefile drives a per-version build:

make
  ├── postgres-headers-install     (lays out vendor/postgres-vXX headers)
  ├── postgres-install-vXX         (compiles postgres for each vXX)
  ├── neon-pg-ext-vXX              (compiles pgxn/neon, neon_rmgr, etc. against each vXX)
  ├── walproposer-lib              (compiles a static walproposer C library that Rust links against)
  └── neon                         (cargo build of the whole workspace)

Each pgxn/<name>/ directory is a Postgres extension Makefile. The same source compiles for every supported pg_version and produces version-specific .so files under pg_install/v<XX>/lib/.

Layout

pgxn/
├── Makefile               # builds all extensions for the current PG version
├── neon/                  # the smgr replacement extension; the largest
│   └── communicator/      # async pageserver client used by neon ext (Cargo crate)
├── neon_rmgr/             # custom WAL record types
├── neon_test_utils/       # extension exposing test-only SQL functions
├── neon_utils/            # smaller helpers
├── neon_walredo/          # extension/library used by the pageserver's walredo subprocess
└── typedefs.list          # for pgindent

vendor/
├── postgres-v14/          # upstream Postgres 14, with Neon patches
├── postgres-v15/
├── postgres-v16/
└── postgres-v17/

See also

• pgxn/neon extension
• Postgres fork
• docs/core_changes.md — long-form description of every type of patch made to upstream Postgres.