neondatabase/neon

Control plane (neon_local)

The control_plane/ crate is the developer-facing control plane: a small Rust program (neon_local, invoked as cargo neon) that starts, configures, and stops a complete Neon stack on a workstation. It is not a production control plane — production deployments use a different cloud-side service. neon_local exists so that contributors and integration tests can spin up the full storage + compute stack with one command.

Purpose

cargo neon:

Initializes a local repository in .neon/ with sensible defaults.
Starts the storage broker, one or more pageservers, one or more safekeepers, and the storage controller.
Creates tenants, timelines (branches), and compute endpoints.
Configures and starts a real Postgres process per endpoint.
Cleans up everything on cargo neon stop.

Almost every Python integration test in test_runner/ uses neon_local under the hood.

Directory layout

control_plane/
├── Cargo.toml
├── README.md
├── safekeepers.conf
├── simple.conf
├── src/                 # the neon_local CLI
│   ├── bin/             # neon_local binary
│   └── …                # endpoint, pageserver, safekeeper, storage_controller modules
└── storcon_cli/         # standalone CLI for storage controller (storcon-cli)

Subcommands at a glance

cargo neon init                              # create .neon/ with default config
cargo neon start                             # start broker, pageserver(s), safekeeper(s), storcon
cargo neon stop                              # stop everything
cargo neon tenant create --set-default
cargo neon timeline list
cargo neon timeline branch --branch-name <n>
cargo neon endpoint create <name> [--branch-name ...]
cargo neon endpoint start <name>
cargo neon endpoint stop <name>
cargo neon endpoint list

# fine-grained service control
cargo neon pageserver start
cargo neon safekeeper restart
cargo neon storage_broker stop

cargo neon --help is the truth-source.

What it actually does

neon_local shells out to the same Rust binaries you build with make:

`neon_local` command	spawns
`pageserver start`	`target/<profile>/pageserver`
`safekeeper start`	`target/<profile>/safekeeper`
`storage_broker`	`target/<profile>/storage_broker`
`endpoint start <n>`	a real `postgres` from `pg_install/v<XX>/bin/postgres`, supervised by `compute_ctl`

Each service writes config and logs into a subdirectory of .neon/:

.neon/
├── config                       # neon_local's view of the world
├── pageserver_1/
│   ├── pageserver.toml
│   ├── pageserver.log
│   └── tenants/<id>/...
├── safekeepers/sk1/
│   ├── safekeeper.log
│   └── <tenant>/<timeline>/...
├── storage_controller/
│   └── storage_controller.log
├── storage_broker.log
└── endpoints/
    └── <name>/
        ├── pgdata/
        ├── postgresql.conf
        ├── compute_ctl-NNN.log
        └── postgres.log

The config file at .neon/config is the persistent record of what services are configured locally. Editing it directly is supported.

Pinning Postgres version

By default neon_local uses DEFAULT_PG_VERSION (currently 17) but each tenant and endpoint can be pinned:

cargo neon tenant create --pg-version 16 --set-default
cargo neon endpoint create main --pg-version 16

The vendored Postgres trees in vendor/postgres-v{14,15,16,17} are all built when you run make; neon_local selects the right one by version.

Embedded storage controller

When neon_local start runs, it brings up an embedded storage controller backed by a vanilla Postgres database (default port 1235, database storage_controller). This means most of the production attach/detach paths exercise the same code locally as in production. See Storage controller.

Test-friendly hooks

The CLI honors a few env vars and flags useful in tests:

NEON_REPO_DIR — override the working directory location.
--update-catalog true — run the full set of compute catalog migrations.
--create-test-user true — provision a test user / neondb database.

Source files

File	Purpose
`control_plane/src/bin/neon_local.rs`	CLI entry.
`control_plane/src/local_env.rs`	The `.neon/config` model.
`control_plane/src/pageserver.rs`	Pageserver spawn/control.
`control_plane/src/safekeeper.rs`	Safekeeper spawn/control.
`control_plane/src/endpoint.rs`	Endpoint (compute) spawn/control.
`control_plane/src/storage_controller.rs`	Embedded storcon.
`control_plane/storcon_cli/`	Standalone storage controller CLI.
`control_plane/README.md`	User guide.