Neon

Neon is serverless Postgres with copy-on-write branching. With alchemy you declare the project and its branches as resources in the same Stack as your Workers — each preview stage forks its own branch in seconds and destroys it just as fast, and SQL migrations run as part of the deploy.

New here? Set up credentials first.

Resources

A Neon.Project is the top-level container — creating it also provisions a default branch, role, database, and compute endpoint. A Neon.Branch is a copy-on-write fork with its own connection string:

const project = yield* Neon.Project("app-db", {
  region: "aws-us-east-1",
});

const branch = yield* Neon.Branch("app-branch", {
  project,
});

Branches can fork from any parent, pin to a point in time, copy schema only, and expire on their own — see Branching.

Both resources accept a migrationsDir of SQL files applied in order on deploy:

const featureBranch = yield* Neon.Branch("feature", {
  project,
  migrationsDir: "./migrations",
});

Migrations are ordered, hashed, and tracked in a neon_migrations table so each file runs exactly once — see Migrations.

Pooled vs direct

Every project and branch exposes its connection details twice: origin points straight at the branch’s compute endpoint, while pooledOrigin routes through Neon’s pgbouncer pooler. Hyperdrive is itself a pooler, so hand it the direct origin — and hand the pooled one to everything that connects without Hyperdrive in front, like local dev, CI jobs, and containers:

const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("app-hyperdrive", {
  origin: branch.origin, //    direct — Hyperdrive does the pooling
  dev: branch.pooledOrigin, // local dev bypasses Hyperdrive
});

See Connections for the raw URIs, the parsed origin shape, and when each applies.

The Neon path

On Cloudflare, Neon slots into a four-step path:

1. Hyperdrive pools the branch’s direct origin at the edge
2. Drizzle gives the Worker a typed query layer over that connection
3. Shared database keeps one long-lived project instead of provisioning a cluster per stage
4. Branch from a shared database forks a copy-on-write preview branch per PR off that shared project

Reference

• Project
• Branch