Neon

Declare Neon Postgres branches, Functions, object storage, managed Auth, Data API, and AI Gateway connections in the same Alchemy Stack. Functions accept native Fetch handlers or Effect applications; runtime bindings connect them to your backend without exposing the deployment API key.

New here? Complete Setup for credentials, region selection, service access, and the manual prerequisites for each feature. Then follow the authenticated upload tutorial to combine a Vite frontend, private files, managed sessions, SQL records, and an upload-triggered Function.

Before launch, use the dedicated guides for production Auth, AI Gateway access, private networking, custom domains, and state preservation and recovery.

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 migrations folder of SQL files applied in order on deploy:

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

Migrations are ordered, hashed, and tracked in Alchemy’s __alchemy_migrations table so each file runs exactly once — see Migrations.

Organization governance

Manage organization API keys, existing members’ roles, spending-alert thresholds, and AWS PrivateLink associations alongside your application infrastructure. These controls target an existing organization; they do not create organizations or invite users. See Organization governance for adoption, restoration, and private-networking constraints.

Private storage and typed objects

const uploads = yield* Neon.Bucket("Uploads", { branch });
const settings = yield* Neon.Object("Settings", {
  bucket: uploads,
  key: "settings.json",
  value: { theme: "dark", pageSize: 20 },
});

Neon.Object infers the value type; it also accepts an explicit generic and an optional Effect Schema. Functions use Neon.ReadObject(settings) or Neon.WriteObject(settings) for typed access, and bucket bindings for arbitrary keys. Provide the corresponding *Http layer, such as ReadObjectHttp or WriteBucketHttp, on the application. Every storage client uses the same S3-compatible HTTP API: a same-branch production Function uses injected credentials, while local and external hosts receive managed credentials. Pass { credential } to the binding to use an explicit credential instead. Neon scopes apply to a branch and its descendants, not individual buckets or keys.

Native and Effect Functions

const api = yield* Neon.Function("Api", {
  branch,
  main: "./src/api.ts",
});

The native entrypoint exports a Fetch handler. The Effect form adds an initialization Effect to resolve runtime bindings, followed by request handlers. See Functions in the tutorial for both forms, event sources, and authentication. Function URLs are public; handlers must authorize callers before doing protected work.

Subscribe to events

Inside the Function’s initialization Effect, subscribe directly instead of manually pairing a trigger with an HTTP route:

yield* Neon.BucketEventSource(
  uploads,
  { name: "ProcessUploads", prefix: "incoming/" },
  event => Effect.log(event.objectKey),
);

Provide Neon.BucketEventSourceHttp on the application. The subscription registers the route and owns its FunctionTrigger. For a schedule, use Neon.CronEventSource with Neon.CronEventSourceHttp. Keep FunctionTrigger for native Fetch handlers that already expose an event route. See the upload subscription reference for the typed event. These are HTTP deliveries, not a queue with acknowledgement or retry controls; local development does not simulate cloud uploads or run a scheduler.

Websites

const web = yield* Neon.Website.Vite("Web", {
  branch,
  rootDir: "./web",
});

The Website family includes Vite, Astro, Nextjs, Nuxt, SvelteKit, ReactRouter, SolidStart, TanStackStart, Waku, Octane, Foldkit, Vocs, and StaticSite. Production output is a Fetch application deployed as a Function, not S3 website hosting. Local development runs each framework’s native server. Framework reference pages describe packaging requirements and limitations.

Effect AI

const gateway = yield* Neon.AIGateway("AI", { branch });
// Inside a Function's initialization Effect:
const ai = yield* Neon.QueryAIGateway(gateway);
const model = ai.model({ model: "gpt-5-mini", parameters: { maxTokens: 128 } });
// Inside its request handler:
const reply = yield* LanguageModel.generateText({ prompt: "Say hello." }).pipe(
  Effect.provide(model),
);

Import LanguageModel from effect/unstable/ai and provide Neon.QueryAIGatewayHttp on the application. It selects injected or managed credentials automatically and exposes the model layer backed by Neon’s OpenAI-compatible Chat Completions API. Model access and prepaid credits are separate account requirements; declaring a gateway never changes billing. Complete AI Gateway setup for access, credit purchase, and an inference check. See AI Gateway bindings for credentials, streaming, tools, structured output, and dialect URLs.

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