clover's git

the-knife

1	---
2	title: Neon
3	description: Declare Neon Postgres, Functions, storage, Auth, AI Gateway and websites together in an Alchemy Stack.
4	---
5
6	Declare Neon Postgres branches, Functions, object storage, managed Auth, Data API,
7	and AI Gateway connections in the same Alchemy Stack. Functions accept native
8	Fetch handlers or Effect applications; runtime bindings connect them to your
9	backend without exposing the deployment API key.
10
11	New here? Complete [Setup](/neon/setup) for credentials, region selection, service
12	access, and the manual prerequisites for each feature. Then follow the
13	[authenticated upload tutorial](/neon/tutorial) to combine a Vite frontend,
14	private files, managed sessions, SQL records, and an upload-triggered Function.
15
16	Before launch, use the dedicated guides for [production Auth](/neon/guides/production-auth),
17	[AI Gateway access](/neon/guides/ai-gateway),
18	[private networking](/neon/guides/private-networking),
19	[custom domains](/neon/guides/custom-domains), and
20	[state preservation and recovery](/neon/guides/state-recovery).
21
22	## Resources
23
24	A `Neon.Project` is the top-level container — creating it also
25	provisions a default branch, role, database, and compute endpoint. A
26	`Neon.Branch` is a copy-on-write fork with its own connection string:
27
28	```typescript
29	const project = yield* Neon.Project("app-db", {
30	region: "aws-us-east-1",
31	});
32
33	const branch = yield* Neon.Branch("app-branch", {
34	project,
35	});
36	```
37
38	Branches can fork from any parent, pin to a point in time, copy
39	schema only, and expire on their own — see [Branching](/neon/data/branching).
40
41	Both resources accept a `migrations` folder of SQL files applied in
42	order on deploy:
43
44	```typescript
45	const featureBranch = yield* Neon.Branch("feature", {
46	project,
47	migrations: "./migrations",
48	});
49	```
50
51	Migrations are ordered, hashed, and tracked in Alchemy's
52	`__alchemy_migrations` table so each file runs exactly once — see
53	[Migrations](/neon/data/migrations).
54
55	## Organization governance
56
57	Manage organization API keys, existing members' roles, spending-alert thresholds,
58	and AWS PrivateLink associations alongside your application infrastructure.
59	These controls target an existing organization; they do not create organizations
60	or invite users. See [Organization governance](/neon/governance) for adoption,
61	restoration, and private-networking constraints.
62
63	## Private storage and typed objects
64
65	```typescript
66	const uploads = yield* Neon.Bucket("Uploads", { branch });
67	const settings = yield* Neon.Object("Settings", {
68	bucket: uploads,
69	key: "settings.json",
70	value: { theme: "dark", pageSize: 20 },
71	});
72	```
73
74	`Neon.Object` infers the value type; it also accepts an explicit generic and an
75	optional Effect Schema. Functions use `Neon.ReadObject(settings)` or
76	`Neon.WriteObject(settings)` for typed access, and bucket bindings for arbitrary
77	keys. Provide the corresponding `*Http` layer, such as `ReadObjectHttp` or
78	`WriteBucketHttp`, on the application. Every storage client uses the same
79	S3-compatible HTTP API: a same-branch production Function uses injected credentials,
80	while local and external hosts receive managed credentials. Pass `{ credential }`
81	to the binding to use an explicit credential instead. Neon scopes apply to a branch
82	and its descendants, not individual buckets or keys.
83
84	## Native and Effect Functions
85
86	```typescript
87	const api = yield* Neon.Function("Api", {
88	branch,
89	main: "./src/api.ts",
90	});
91	```
92
93	The native entrypoint exports a Fetch handler. The Effect form adds an
94	initialization Effect to resolve runtime bindings, followed by request handlers.
95	See [Functions in the tutorial](/neon/tutorial/functions) for both forms, event
96	sources, and authentication. Function URLs are public; handlers must authorize
97	callers before doing protected work.
98
99	## Subscribe to events
100
101	Inside the Function's initialization Effect, subscribe directly instead of
102	manually pairing a trigger with an HTTP route:
103
104	```typescript
105	yield* Neon.BucketEventSource(
106	uploads,
107	{ name: "ProcessUploads", prefix: "incoming/" },
108	event => Effect.log(event.objectKey),
109	);
110	```
111
112	Provide `Neon.BucketEventSourceHttp` on the application. The subscription registers
113	the route and owns its `FunctionTrigger`. For a schedule, use
114	[`Neon.CronEventSource`](/providers/neon/croneventsource) with
115	`Neon.CronEventSourceHttp`. Keep [`FunctionTrigger`](/providers/neon/functiontrigger)
116	for native Fetch handlers that already expose an event route. See the
117	[upload subscription reference](/providers/neon/bucketeventsource) for the typed
118	event. These are HTTP deliveries, not a queue with acknowledgement or retry controls;
119	local development does not simulate cloud uploads or run a scheduler.
120
121	## Websites
122
123	```typescript
124	const web = yield* Neon.Website.Vite("Web", {
125	branch,
126	rootDir: "./web",
127	});
128	```
129
130	The Website family includes Vite, Astro, Nextjs, Nuxt, SvelteKit, ReactRouter,
131	SolidStart, TanStackStart, Waku, Octane, Foldkit, Vocs, and StaticSite. Production
132	output is a Fetch application deployed as a Function, not S3 website hosting.
133	Local development runs each framework's native server. Framework reference pages
134	describe packaging requirements and limitations.
135
136	## Effect AI
137
138	```typescript
139	const gateway = yield* Neon.AIGateway("AI", { branch });
140	// Inside a Function's initialization Effect:
141	const ai = yield* Neon.QueryAIGateway(gateway);
142	const model = ai.model({ model: "gpt-5-mini", parameters: { maxTokens: 128 } });
143	// Inside its request handler:
144	const reply = yield* LanguageModel.generateText({ prompt: "Say hello." }).pipe(
145	Effect.provide(model),
146	);
147	```
148
149	Import `LanguageModel` from `effect/ai` and provide
150	`Neon.QueryAIGatewayHttp` on the application. It selects injected or managed
151	credentials automatically and exposes the model layer backed by Neon's
152	OpenAI-compatible Chat Completions API. Model access and prepaid credits are separate account requirements; declaring
153	a gateway never changes billing. Complete [AI Gateway setup](/neon/guides/ai-gateway)
154	for access, credit purchase, and an inference check. See
155	[AI Gateway bindings](/providers/neon/queryaigateway) for credentials, streaming,
156	tools, structured output, and dialect URLs.
157
158	## Pooled vs direct
159
160	Every project and branch exposes its connection details twice:
161	`origin` points straight at the branch's compute endpoint, while
162	`pooledOrigin` routes through Neon's pgbouncer pooler. Hyperdrive is
163	itself a pooler, so hand it the direct origin — and hand the pooled
164	one to everything that connects without Hyperdrive in front, like
165	local dev, CI jobs, and containers:
166
167	```typescript
168	const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("app-hyperdrive", {
169	origin: branch.origin, // direct — Hyperdrive does the pooling
170	dev: branch.pooledOrigin, // local dev bypasses Hyperdrive
171	});
172	```
173
174	See [Connections](/neon/data/connections) for the raw URIs, the parsed
175	origin shape, and when each applies.
176
177	## The Neon path
178
179	On Cloudflare, Neon slots into a four-step path:
180
181	1. [Hyperdrive](/cloudflare/data/hyperdrive) pools the branch's direct
182	origin at the edge
183	2. [Drizzle](/cloudflare/data/drizzle) gives the Worker a typed
184	query layer over that connection
185	3. [Shared database](/cloudflare/data/shared-database) keeps one
186	long-lived project instead of provisioning a cluster per stage
187	4. [Branch from a shared database](/cloudflare/data/branch-from-shared-database)
188	forks a copy-on-write preview branch per PR off that shared
189	project
190
191	## Reference
192
193	- [Project](/providers/neon/project)
194	- [Branch](/providers/neon/branch)