Neon

Neon is a serverless Postgres platform written in Rust that separates storage from compute. The storage layer is custom-built — a distributed, copy-on-write page store that enables instant database branching, continuous archiving to S3, and point-in-time restore to any second in history. The compute layer is unmodified Postgres, so everything that works with Postgres works with Neon.

The open-source repository contains the full Neon storage engine (pageserver, safekeeper, proxy) that powers the managed cloud service, and can be run locally for development.

Features

• Serverless scaling — compute scales to zero when idle and scales up on the first connection; you pay only for active compute time and storage used
• Database branching — create an instant, zero-copy branch of your database for every feature branch, PR, or test run — just like git checkout
• Point-in-time restore — restore your database to any second in its history without restoring from a backup file
• Autoscaling — compute automatically scales up and down within configured min/max bounds as load changes
• Standard Postgres — the compute layer is unmodified Postgres 14/15/16/17; no proprietary extensions or query language changes required
• Postgres extensions — supports pgvector, PostGIS, pg_stat_statements, and hundreds of other standard extensions
• Read replicas — spin up instant read replicas by pointing additional compute nodes at the same storage
• Connection pooling — built-in PgBouncer-compatible connection pooler (pgbouncer) for serverless environments where each request opens a new connection
• Logical replication — supports Postgres logical replication for CDC and data streaming to downstream systems

Architecture

Neon's storage engine is split into two components:

• Pageserver — stores the page history for all databases; serves page reads to compute nodes; archives old data to S3; supports point-in-time reads at any LSN
• Safekeeper — a distributed WAL service based on Paxos; receives WAL from the compute node and durably stores it until the pageserver has processed it

The compute layer is a standard postgres process with a small extension (neon.so) that redirects page reads to the pageserver instead of local disk. This means the entire PostgreSQL ecosystem — drivers, ORMs, tools, extensions — works without modification.

Installation

Neon Cloud (easiest)

Sign up for the managed service at neon.tech — the free tier includes 0.5 GB storage and unlimited branching.

# Debian / Ubuntu / Fedora (and all Linux distros)
# The Neon CLI is distributed via npm and works on any Linux distro
# with Node.js installed.
npm install -g neonctl

# Authenticate
neonctl auth

# Create a project
neonctl projects create --name my-project

# List connection strings
neonctl connection-string

# Connect with psql
psql $(neonctl connection-string)

Running locally

git clone https://github.com/neondatabase/neon
cd neon
cargo build --release

# Start a local Neon instance (starts pageserver, safekeeper, and a Postgres compute)
./scripts/neon_local.py init
./scripts/neon_local.py start

# Connect with psql
psql -h localhost -p 55432 -U cloud_admin postgres

Database Branching

Branching is Neon's standout feature. A branch is an instant, zero-copy copy of your database at a point in time — creating one takes milliseconds regardless of database size, because no data is physically copied.

# Create a branch from the main branch (current HEAD)
neonctl branches create --name feature/my-feature

# Create a branch from a specific point in time
neonctl branches create \
  --name pre-migration \
  --parent main \
  --type time \
  --timestamp "2024-06-01T12:00:00Z"

# List branches
neonctl branches list

# Get connection string for a branch
neonctl connection-string --branch feature/my-feature

# Delete a branch when done
neonctl branches delete feature/my-feature

Typical workflow with PRs

# Create a database branch for each pull request
neonctl branches create --name pr-$(git rev-parse --short HEAD)

# Run migrations against the branch
DATABASE_URL=$(neonctl connection-string --branch pr-$(git rev-parse --short HEAD)) \
  npx prisma migrate deploy

# Tear down the branch when the PR is merged
neonctl branches delete pr-$(git rev-parse --short HEAD)

Point-in-Time Restore

# Restore the main branch to a specific timestamp
neonctl branches restore main \
  --source-branch main \
  --source-timestamp "2024-06-01T11:59:00Z"

# Or restore to a specific Log Sequence Number (LSN)
neonctl branches restore main \
  --source-branch main \
  --source-lsn 0/3A5678

Autoscaling configuration

In the Neon Console or CLI, set min and max compute units for a branch:

neonctl branches update main \
  --compute-units-min 0.25 \
  --compute-units-max 4

0.25 CU means the compute scales down to a quarter of a vCPU (and to zero after the idle timeout), while 4 CU means it can scale up to 4 vCPUs under load.

Connection pooling

For serverless environments (Vercel Edge, Cloudflare Workers, AWS Lambda) where each request creates a new connection, use Neon's pooled connection string:

# Pooled endpoint (goes through PgBouncer)
neonctl connection-string --pooled

# In your application
DATABASE_URL="postgresql://user:pass@ep-xxx.pooler.neon.tech/dbname?sslmode=require"

Use cases

• Preview environments — create a fresh database branch for every PR in CI; merge the PR, delete the branch
• Development databases — each developer gets their own branch of production data; no shared dev database conflicts
• Testing with real data — branch production, run destructive tests safely, discard the branch
• Disaster recovery — restore to any second in the last 7–30 days (depending on plan) without a lengthy backup restore process
• Read scaling — add read replica endpoints in seconds by pointing new compute nodes at the same pageserver storage