The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 207 lines 7.67 KB
Raw
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 ## Roles
56
57 A `Neon.Role` is a Postgres login on a branch. Give your app and your
58 migrations their own:
59
60 ```typescript
61 const app = yield* Neon.Role("App", { branch });
62 const migrator = yield* Neon.Role("Migrator", { branch, name: "migrator" });
63 ```
64
65 `app.password` is `Redacted` and stays the same across deploys — see
66 [Roles](/neon/data/roles).
67
68 ## Organization governance
69
70 Manage organization API keys, existing members' roles, spending-alert thresholds,
71 and AWS PrivateLink associations alongside your application infrastructure.
72 These controls target an existing organization; they do not create organizations
73 or invite users. See [Organization governance](/neon/governance) for adoption,
74 restoration, and private-networking constraints.
75
76 ## Private storage and typed objects
77
78 ```typescript
79 const uploads = yield* Neon.Bucket("Uploads", { branch });
80 const settings = yield* Neon.Object("Settings", {
81 bucket: uploads,
82 key: "settings.json",
83 value: { theme: "dark", pageSize: 20 },
84 });
85 ```
86
87 `Neon.Object` infers the value type; it also accepts an explicit generic and an
88 optional Effect Schema. Functions use `Neon.ReadObject(settings)` or
89 `Neon.WriteObject(settings)` for typed access, and bucket bindings for arbitrary
90 keys. Provide the corresponding `*Http` layer, such as `ReadObjectHttp` or
91 `WriteBucketHttp`, on the application. Every storage client uses the same
92 S3-compatible HTTP API: a same-branch production Function uses injected credentials,
93 while local and external hosts receive managed credentials. Pass `{ credential }`
94 to the binding to use an explicit credential instead. Neon scopes apply to a branch
95 and its descendants, not individual buckets or keys.
96
97 ## Native and Effect Functions
98
99 ```typescript
100 const api = yield* Neon.Function("Api", {
101 branch,
102 main: "./src/api.ts",
103 });
104 ```
105
106 The native entrypoint exports a Fetch handler. The Effect form adds an
107 initialization Effect to resolve runtime bindings, followed by request handlers.
108 See [Functions in the tutorial](/neon/tutorial/functions) for both forms, event
109 sources, and authentication. Function URLs are public; handlers must authorize
110 callers before doing protected work.
111
112 ## Subscribe to events
113
114 Inside the Function's initialization Effect, subscribe directly instead of
115 manually pairing a trigger with an HTTP route:
116
117 ```typescript
118 yield* Neon.BucketEventSource(
119 uploads,
120 { name: "ProcessUploads", prefix: "incoming/" },
121 event => Effect.log(event.objectKey),
122 );
123 ```
124
125 Provide `Neon.BucketEventSourceHttp` on the application. The subscription registers
126 the route and owns its `FunctionTrigger`. For a schedule, use
127 [`Neon.CronEventSource`](/providers/neon/croneventsource) with
128 `Neon.CronEventSourceHttp`. Keep [`FunctionTrigger`](/providers/neon/functiontrigger)
129 for native Fetch handlers that already expose an event route. See the
130 [upload subscription reference](/providers/neon/bucketeventsource) for the typed
131 event. These are HTTP deliveries, not a queue with acknowledgement or retry controls;
132 local development does not simulate cloud uploads or run a scheduler.
133
134 ## Websites
135
136 ```typescript
137 const web = yield* Neon.Website.Vite("Web", {
138 branch,
139 rootDir: "./web",
140 });
141 ```
142
143 The Website family includes Vite, Astro, Nextjs, Nuxt, SvelteKit, ReactRouter,
144 SolidStart, TanStackStart, Waku, Octane, Foldkit, Vocs, and StaticSite. Production
145 output is a Fetch application deployed as a Function, not S3 website hosting.
146 Local development runs each framework's native server. Framework reference pages
147 describe packaging requirements and limitations.
148
149 ## Effect AI
150
151 ```typescript
152 const gateway = yield* Neon.AIGateway("AI", { branch });
153 // Inside a Function's initialization Effect:
154 const ai = yield* Neon.QueryAIGateway(gateway);
155 const model = ai.model({ model: "gpt-5-mini", parameters: { maxTokens: 128 } });
156 // Inside its request handler:
157 const reply = yield* LanguageModel.generateText({ prompt: "Say hello." }).pipe(
158 Effect.provide(model),
159 );
160 ```
161
162 Import `LanguageModel` from `effect/ai` and provide
163 `Neon.QueryAIGatewayHttp` on the application. It selects injected or managed
164 credentials automatically and exposes the model layer backed by Neon's
165 OpenAI-compatible Chat Completions API. Model access and prepaid credits are separate account requirements; declaring
166 a gateway never changes billing. Complete [AI Gateway setup](/neon/guides/ai-gateway)
167 for access, credit purchase, and an inference check. See
168 [AI Gateway bindings](/providers/neon/queryaigateway) for credentials, streaming,
169 tools, structured output, and dialect URLs.
170
171 ## Pooled vs direct
172
173 Every project and branch exposes its connection details twice:
174 `origin` points straight at the branch's compute endpoint, while
175 `pooledOrigin` routes through Neon's pgbouncer pooler. Hyperdrive is
176 itself a pooler, so hand it the direct origin — and hand the pooled
177 one to everything that connects without Hyperdrive in front, like
178 local dev, CI jobs, and containers:
179
180 ```typescript
181 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("app-hyperdrive", {
182 origin: branch.origin, // direct — Hyperdrive does the pooling
183 dev: branch.pooledOrigin, // local dev bypasses Hyperdrive
184 });
185 ```
186
187 See [Connections](/neon/data/connections) for the raw URIs, the parsed
188 origin shape, and when each applies.
189
190 ## The Neon path
191
192 On Cloudflare, Neon slots into a four-step path:
193
194 1. [Hyperdrive](/cloudflare/data/hyperdrive) pools the branch's direct
195 origin at the edge
196 2. [Drizzle](/cloudflare/data/drizzle) gives the Worker a typed
197 query layer over that connection
198 3. [Shared database](/cloudflare/data/shared-database) keeps one
199 long-lived project instead of provisioning a cluster per stage
200 4. [Branch from a shared database](/cloudflare/data/branch-from-shared-database)
201 forks a copy-on-write preview branch per PR off that shared
202 project
203
204 ## Reference
205
206 - [Project](/providers/neon/project)
207 - [Branch](/providers/neon/branch)