Technology handbook

Neon

Serverless Postgres branching, connection pooling, autoscaling and environment workflows.

Topics: 18
Sections: 3

Platform model

Projects and branches

Understand the hierarchy that holds compute, storage and databases.

A project holds branches, and a branch holds compute, storage and databases.
The hierarchy is what makes a database branch as cheap as a code branch.
Storage belongs to the branch; compute is attached to it separately.

Copy-on-write branching

Create a branch of real data without duplicating storage.

A branch of real data is created without duplicating the storage.
Only what diverges consumes new space, so branching is near-instant.
A long-lived branch that drifts far from its parent stops being cheap.

Compute endpoints

Attach compute to a branch and size it for the workload.

Compute is attached to a branch and sized for its workload.
The same branch data can be served by a differently sized endpoint.
Resizing restarts the endpoint, which drops open connections.

Autoscaling

Let compute grow with load within bounds you set.

Compute grows with load between the bounds you set.
Bounds are what stop a runaway query becoming a runaway bill.
Scaling reacts to load, so the first moments of a spike are served small.

Scale to zero

Trade idle cost for a resume delay and know where that delay lands.

An idle database suspends, so cost follows use rather than uptime.
The next connection pays a resume delay before it is served.
A health check that never lets it idle removes the saving entirely.

Regions

Place data close to the application and understand cross-region latency.

Data is placed near the application, and cross-region latency understood.
A round trip across regions dominates any query the database runs.
A project's region is fixed, so moving means a new project.

Connecting

Pooled connections

Use the pooled endpoint from short-lived serverless invocations.

The pooled endpoint carries a -pooler suffix in its hostname.
It runs PgBouncer in transaction mode and accepts up to 10,000 client connections.
The documented pool size is 90% of max_connections — 377 of 419 on a 1 CU compute.

Direct connections

Reserve the direct endpoint for migrations and long-lived sessions.

The direct endpoint is the hostname without the -pooler suffix.
Schema migrations, pg_dump/pg_restore and logical replication all require it.
Anything relying on SET, LISTEN/NOTIFY or session state needs it too.

Serverless driver

Query over HTTP where a TCP socket cannot survive the runtime.

Queries travel over HTTP where a TCP socket cannot survive the runtime.
It removes the connection lifecycle entirely for one-shot queries.
Each statement is its own request, so chatty code pays per statement.

Connection strings

Manage per-branch credentials without hardcoding them.

Per-branch credentials are managed rather than hardcoded.
Each branch has its own string, which is what keeps environments apart.
A string committed to the repository is a credential leak, not a config.

SSL requirements

Connect with the encryption the platform requires.

The platform requires encrypted connections.
A client that disables verification is encrypted but not authenticated.
Some drivers need the mode stated explicitly or they fail to connect.

Connection limits

Recognize pool exhaustion and correct the endpoint choice.

PgBouncer accepts up to 10,000 client connections in front of far fewer server ones.
max_connections scales with compute size, so a small endpoint exhausts sooner.
Exhaustion usually means direct connections were used where pooled were needed.

Workflows

Preview branches

Give each pull request an isolated database automatically.

Each pull request gets an isolated database automatically.
Isolation means a destructive test cannot reach shared data.
Branches created per pull request must also be destroyed per pull request.

Migration testing

Run a migration against production-shaped data before shipping it.

A migration runs against production-shaped data before it ships.
Real data volume is what surfaces a migration that locks a table too long.
A schema-only branch will not reveal that, because it has no rows.

Point-in-time restore

Recover by branching from an earlier moment rather than restoring a dump.

Recovery branches from an earlier moment instead of restoring a dump.
The original branch stays untouched, so the two can be compared.
The window is bounded by retention, so an old mistake may be past it.

Schema-only branches

Share structure without copying sensitive rows.

Structure is shared without copying sensitive rows.
It is the safe branch to hand to a contractor or a preview environment.
Queries that depend on data volume behave nothing like production here.

Branch cleanup

Expire ephemeral branches so storage and cost stay bounded.

Ephemeral branches expire so storage and cost stay bounded.
A branch left open keeps diverging and keeps costing.
Automatic expiry is what stops cleanup depending on someone remembering.

Environment separation

Keep development, preview and production credentials distinct.

Development, preview and production credentials are kept distinct.
One shared string means a preview deploy can write to production.
Separation has to be enforced by the credential, not by convention.

Sources

Neon official documentation

Ask follow-up questions on any topic in your dashboard.

Start learning