Getting started

This page walks through building Neon from source and running a complete local stack — pageserver, safekeeper, broker, and a Postgres compute node — with the neon_local CLI. The instructions follow the canonical flow in README.md and control_plane/README.md.

Prerequisites

Neon builds against multiple Postgres major versions (14, 15, 16, 17 — see Makefile's POSTGRES_VERSIONS) using a vendored, lightly patched Postgres source tree under vendor/postgres-v*. You therefore need both a Rust toolchain and Postgres build dependencies.

Linux

On Debian / Ubuntu:

apt install build-essential libtool libreadline-dev zlib1g-dev flex bison libseccomp-dev \
  libssl-dev clang pkg-config libpq-dev cmake postgresql-client protobuf-compiler \
  libprotobuf-dev libcurl4-openssl-dev openssl python3-poetry lsof libicu-dev

On Fedora:

dnf install flex bison readline-devel zlib-devel openssl-devel libseccomp-devel perl \
  clang cmake postgresql postgresql-contrib protobuf-compiler protobuf-devel \
  libcurl-devel openssl poetry lsof libicu-devel libpq-devel python3-devel libffi-devel

protoc must be ≥ 3.15. If your distribution ships an older version, install a recent release manually.

macOS

xcode-select --install
brew install protobuf openssl flex bison icu4c pkg-config m4 libpq
brew link --force libpq
echo 'export PATH="$(brew --prefix openssl)/bin:$PATH"' >> ~/.zshrc

Rust toolchain

Install rustup. The active toolchain is pinned in rust-toolchain.toml and picked up automatically when you cd into the repo.

Python (only for integration tests)

The Python tests use Poetry. After cloning, run ./scripts/pysync to install the locked dependencies into a poetry-managed virtualenv.

Clone and build

git clone --recursive https://github.com/neondatabase/neon.git
cd neon

# Debug build (default). For release: BUILD_TYPE=release make -j$(nproc) -s
make -j$(nproc) -s

The top-level Makefile builds three things:

1. The patched Postgres tree(s) — see postgres.mk.
2. The neon Postgres extension and friends in pgxn/ (one copy per Postgres version).
3. All Rust binaries via cargo build.

Cargo build flags can be passed via CARGO_BUILD_FLAGS, e.g. CARGO_BUILD_FLAGS="--features=testing" make.

Run a local Neon

The cargo neon alias is configured in .cargo/config.toml and runs the neon_local binary from control_plane/.

# Initialize a local repo at .neon/
cargo neon init

# Start the storage broker, pageserver, and one safekeeper
cargo neon start

# Create the initial tenant and timeline (and set as default)
cargo neon tenant create --set-default

# Create and start a Postgres compute node on the default timeline
cargo neon endpoint create main
cargo neon endpoint start main

# List running endpoints
cargo neon endpoint list

You can now connect with psql:

psql -p 55432 -h 127.0.0.1 -U cloud_admin postgres

Branching

Branches are first-class. They map to internal timeline objects and are created at a specific LSN.

cargo neon timeline branch --branch-name migration_check
cargo neon timeline list
cargo neon endpoint create migration_check --branch-name migration_check
cargo neon endpoint start migration_check

Each branch is copy-on-write: writes diverge but no extra disk space is consumed until you actually mutate pages.

Stop everything

cargo neon stop

If something goes wrong during initialization, stop everything, delete the local .neon/ directory, and start over.

Run the integration tests

CARGO_BUILD_FLAGS="--features=testing" make
./scripts/pytest

# Or just one Postgres version + release build:
DEFAULT_PG_VERSION=17 BUILD_TYPE=release ./scripts/pytest

The tests use the same neon_local machinery as the local quick-start, so passing tests imply a healthy build. See Testing.

Run unit tests

# Project-wide Rust unit tests with cargo-nextest (preferred)
cargo nextest run

# Lint and format
./run_clippy.sh
./scripts/reformat

Next steps

• Architecture — the conceptual model.
• Pageserver, Safekeeper, Proxy — subsystem deep-dives.
• Patterns and conventions — style, error handling, async patterns.
• Tooling — make, cargo nextest, cargo deny, cargo hakari, ruff, mypy.