Skip to content

Commit 80d1f77

Browse files
committed
feat(database): 🚀 add Hyperdrive support for PostgreSQL connections
1 parent 6a4acf2 commit 80d1f77

8 files changed

Lines changed: 137 additions & 43 deletions

File tree

‎apps/web/content/docs/dev/deployments/cloud/cloudflare.mdx‎

Lines changed: 55 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ A VitNode **Single App** builds into one Cloudflare Worker: the site, the Hono A
1414
| ---------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
1515
| The site, SSR, prerendered pages, `/api/*` | ✅ Works | One Worker answers every route; prerendered pages are served as static assets. |
1616
| [WebSockets](/docs/dev/websocket) | ✅ Works | The realtime hub owns the sockets. See [Cloudflare WebSockets](/docs/dev/websocket/cloudflare). |
17-
| Postgres | ✅ Works | Through `scopedDatabase`, one client per request. |
17+
| Postgres | ✅ Works | Through `scopedDatabase`, one client per request, or [Hyperdrive](#connect-through-hyperdrive). |
1818
| [S3 / R2](/docs/dev/storage/s3-r2), Supabase storage | ✅ Works | Uploads go straight to the bucket. |
1919
| [Local file storage](/docs/dev/storage/local) | ❌ No disk | A Worker has no persistent file system. Use a bucket. |
2020
| Image re-encoding (`storage.image`) | ❌ Unsupported | It needs `sharp`, a native module Workers cannot load. Leave `storage.image` out of the Worker build. |
@@ -26,7 +26,7 @@ A VitNode **Single App** builds into one Cloudflare Worker: the site, the Hono A
2626

2727
- A Single App, the one layout `create-vitnode-app` offers for Workers.
2828
- Workers Paid. A VitNode Worker is above the 3 MiB limit of the Free plan; [Shrink the Worker](#shrink-the-worker) keeps it under the 10 MiB Paid limit.
29-
- A PostgreSQL database that Cloudflare can reach over TCP.
29+
- A PostgreSQL database that Cloudflare can reach over TCP. A Worker only trusts certificates from a public CA, so a provider such as Supabase needs [Hyperdrive](#connect-through-hyperdrive).
3030
- Wrangler 4 in the app:
3131

3232
<Tabs groupId='package-manager' persist items={['bun', 'pnpm', 'npm']} label='Install Wrangler'>
@@ -197,6 +197,50 @@ An app made with `--deploy cloudflare` has these commands as its `preview`, `che
197197
</Step>
198198
</Steps>
199199

200+
## Connect through Hyperdrive
201+
202+
A Worker opens its own TLS connection to `POSTGRES_URL` and only accepts a certificate signed by a public CA. Supabase signs its database certificates with its own CA, so every API request fails with `TLS_HANDSHAKE_FAILED`. [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) is Cloudflare's database proxy: it opens that connection for the Worker and pools it across requests.
203+
204+
Create a Hyperdrive config from your app's folder. For Supabase, use the **Direct connection** string, not a pooler one, because Hyperdrive does the pooling:
205+
206+
```bash
207+
npx wrangler hyperdrive create vitnode --connection-string="postgresql://postgres:password@db.your-project.supabase.co:5432/postgres"
208+
```
209+
210+
Add the `id` it prints to `wrangler.jsonc`:
211+
212+
```jsonc title="wrangler.jsonc (excerpt)"
213+
"hyperdrive": [{ "binding": "HYPERDRIVE", "id": "your-hyperdrive-id" }],
214+
```
215+
216+
`scopedDatabase` passes the Worker's bindings to its callback as `env`, and `hyperdriveConnectionString(env)` returns the binding's connection string, or `undefined` on Node and in a Worker without the binding. Fall back to `POSTGRES_URL`, so `vite dev` and `db:migrate` keep using it:
217+
218+
```ts title="src/vitnode.api.config.ts (excerpt)"
219+
import {
220+
hyperdriveConnectionString,
221+
scopedDatabase,
222+
} from '@vitnode/core/cloudflare/database'
223+
224+
dbProvider: scopedDatabase(({ env }) =>
225+
drizzle({
226+
connection: {
227+
url: hyperdriveConnectionString(env) ?? process.env.POSTGRES_URL,
228+
max: 1,
229+
},
230+
relations: coreRelations,
231+
}),
232+
),
233+
```
234+
235+
For `npx wrangler dev`, give the binding a local database in your shell, so the credentials stay out of `wrangler.jsonc`:
236+
237+
```bash
238+
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgresql://user:password@127.0.0.1:5432/vitnode"
239+
npx wrangler dev
240+
```
241+
242+
Pass the binding's name as the second argument, `hyperdriveConnectionString(env, 'DATABASE')`, if you named it something else.
243+
200244
## Shrink the Worker
201245

202246
By default Wrangler uploads every module the build wrote, including chunks nothing imports, without minifying them. A large app, with many plugins or compiled docs, can pass the 10 MiB Paid limit that way. Let Wrangler bundle from the entry and minify:
@@ -218,14 +262,15 @@ With `npx wrangler dev` running, `http://localhost:8787/api/health/ready` answer
218262

219263
## Troubleshooting
220264

221-
| Symptom | Cause and fix |
222-
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
223-
| The Worker ignores `.dev.vars`, and the bindings table lists none of its variables | Wrangler ran with `--config .output/server/wrangler.json`. Run `wrangler dev` from the app's folder without it. |
224-
| A Worker-rendered page fails with `n is not defined` in the browser | The Worker is minified with `keep_names` on. Set `"keep_names": false`. |
225-
| `CONNECTION_CLOSED` or `Cannot perform I/O on behalf of a different request` from the database | The client was created once at module load. Use `scopedDatabase`. |
226-
| Image uploads fail with "The image optimization library (sharp) failed to load" | Remove `storage.image` from the Worker's API config. |
227-
| Deploy fails with `total sourcemap size is too large` (code `10021`) | Set `"upload_source_maps": false` in `wrangler.jsonc`. |
228-
| Deploy fails because the script is too large | [Shrink the Worker](#shrink-the-worker), and check that you are on Workers Paid. |
265+
| Symptom | Cause and fix |
266+
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
267+
| The Worker ignores `.dev.vars`, and the bindings table lists none of its variables | Wrangler ran with `--config .output/server/wrangler.json`. Run `wrangler dev` from the app's folder without it. |
268+
| A Worker-rendered page fails with `n is not defined` in the browser | The Worker is minified with `keep_names` on. Set `"keep_names": false`. |
269+
| `CONNECTION_CLOSED` or `Cannot perform I/O on behalf of a different request` from the database | The client was created once at module load. Use `scopedDatabase`. |
270+
| `TLS_HANDSHAKE_FAILED` from the database, and `/api/health/ready` answers `503` | The database's certificate is not signed by a public CA, as with Supabase. [Connect through Hyperdrive](#connect-through-hyperdrive). |
271+
| Image uploads fail with "The image optimization library (sharp) failed to load" | Remove `storage.image` from the Worker's API config. |
272+
| Deploy fails with `total sourcemap size is too large` (code `10021`) | Set `"upload_source_maps": false` in `wrangler.jsonc`. |
273+
| Deploy fails because the script is too large | [Shrink the Worker](#shrink-the-worker), and check that you are on Workers Paid. |
229274

230275
## Related
231276

‎apps/web/src/vitnode.api.config.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
import { blogApiPlugin } from '@vitnode/blog/config.api'
22
import { FakePaymentAdapter } from '@vitnode/core/api/adapters/payments/fake'
3-
import { scopedDatabase } from '@vitnode/core/cloudflare/database'
3+
import {
4+
hyperdriveConnectionString,
5+
scopedDatabase,
6+
} from '@vitnode/core/cloudflare/database'
47
import { coreRelations } from '@vitnode/core/database/relations'
58
import { buildApiConfig } from '@vitnode/core/vitnode.config'
69
import { forumApiPlugin } from '@vitnode/forum/config.api'
@@ -88,10 +91,10 @@ export const vitNodeApiConfig = buildApiConfig({
8891
// One client per process on Node. On Workers a request cannot reuse a
8992
// connection another request opened, so it gets its own, and the realtime
9093
// hub closes its client when idle so it can hibernate.
91-
dbProvider: scopedDatabase(() =>
94+
dbProvider: scopedDatabase(({ env }) =>
9295
drizzle({
9396
connection: {
94-
url: POSTGRES_URL,
97+
url: hyperdriveConnectionString(env) ?? POSTGRES_URL,
9598
...(ON_WORKERS ? { max: 1 } : {}),
9699
onnotice: () => undefined,
97100
},

‎apps/web/wrangler.jsonc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
// SQLite-backed, so the hub keeps its rooms while it hibernates.
2828
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["VitNodeRealtimeHub"] }],
2929
"vars": {
30+
"CLOUDFLARE_TURNSTILE_SITE_KEY": "0x4AAAAAABi06L36gFn13BlF",
3031
"SUPABASE_URL": "https://wvmvsazvuzfvwydifigd.supabase.co",
3132
"VITNODE_INSTALLATION_ID": "default"
3233
},

‎packages/create-vitnode-app/copy-of-vitnode-app/cloudflare/src/vitnode.api.config.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
import { scopedDatabase } from "@vitnode/core/cloudflare/database";
1+
import {
2+
hyperdriveConnectionString,
3+
scopedDatabase,
4+
} from "@vitnode/core/cloudflare/database";
25
import { coreRelations } from "@vitnode/core/database/relations";
36
import { buildApiConfig } from "@vitnode/core/vitnode.config";
47
import { drizzle } from "drizzle-orm/postgres-js";
@@ -23,10 +26,10 @@ export const vitNodeApiConfig = buildApiConfig({
2326
// opened, so the client is created per request - and per busy period of the
2427
// realtime hub, which closes it when idle so it can hibernate. On Node
2528
// (`dev`, migrations) it is one client per process.
26-
dbProvider: scopedDatabase(() =>
29+
dbProvider: scopedDatabase(({ env }) =>
2730
drizzle({
2831
connection: {
29-
url: POSTGRES_URL,
32+
url: hyperdriveConnectionString(env) ?? POSTGRES_URL,
3033
max: 1,
3134
onnotice: () => undefined,
3235
},

‎packages/vitnode/src/cloudflare/database.ts‎

Lines changed: 62 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,65 @@ import {
55
realtimeScopeRequirement,
66
} from "@/ws/runtime";
77

8+
/**
9+
* Closes a Drizzle client's driver at once: `end({ timeout: 0 })` drops
10+
* postgres.js connections without waiting, which also ends their pending
11+
* socket reads. A client without `$client.end` is left alone.
12+
*/
13+
const closeDriverClient = async (instance: object): Promise<void> => {
14+
const client: unknown = Reflect.get(instance, "$client");
15+
if (typeof client !== "object" && typeof client !== "function") return;
16+
if (client === null) return;
17+
const end: unknown = Reflect.get(client, "end");
18+
if (typeof end === "function") {
19+
await (end as (options: { timeout: number }) => Promise<void>).call(
20+
client,
21+
{ timeout: 0 },
22+
);
23+
}
24+
};
25+
26+
/** What `scopedDatabase` passes to `create`. */
27+
export interface ScopedDatabaseContext {
28+
/** The Cloudflare Worker bindings of the scope; undefined on Node/Bun. */
29+
env: Record<string, unknown> | undefined;
30+
}
31+
32+
/**
33+
* The connection string of a Cloudflare Hyperdrive binding in `env`, or
34+
* `undefined` when there is none (Node/Bun, or a Worker without the binding).
35+
* Hyperdrive opens the TLS connection to the database itself, so it reaches
36+
* providers whose certificate is not signed by a public CA, such as the
37+
* Supabase pooler, which a Worker's own TCP socket refuses.
38+
*
39+
* @param binding The binding's name in `wrangler.jsonc`. Defaults to
40+
* `HYPERDRIVE`.
41+
*/
42+
export const hyperdriveConnectionString = (
43+
env: Record<string, unknown> | undefined,
44+
binding = "HYPERDRIVE",
45+
): string | undefined => {
46+
const hyperdrive: unknown = env?.[binding];
47+
if (typeof hyperdrive !== "object" || hyperdrive === null) return undefined;
48+
const connectionString: unknown = Reflect.get(hyperdrive, "connectionString");
49+
50+
return typeof connectionString === "string" ? connectionString : undefined;
51+
};
52+
853
/**
954
* A database client (or any I/O-bound object) whose real instance belongs to
1055
* the scope that uses it. Use it for `dbProvider` in an app deployed to
1156
* Cloudflare Workers, where a TCP connection opened by one request cannot be
1257
* used by another:
1358
*
1459
* - in a Worker request (or `runWithVitNodeCloudflare`), `create` runs once per
15-
* invocation;
60+
* invocation and receives the Worker's `env`, so it can read a binding such
61+
* as Hyperdrive (see {@link hyperdriveConnectionString});
1662
* - in the realtime hub, once per busy period: the hub keeps its client
1763
* across socket events and closes it (`dispose`) when it goes idle, so an
1864
* open connection never keeps it from hibernating;
1965
* - on Node/Bun, outside any scope, once per process, exactly like a client
20-
* created at module load.
66+
* created at module load, with `env` undefined.
2167
*
2268
* Returns a stand-in with the client's own type: every property access is
2369
* forwarded to the instance of the current scope, so code that captured it
@@ -29,38 +75,26 @@ import {
2975
*
3076
* @example
3177
* ```ts
32-
* import { scopedDatabase } from "@vitnode/core/cloudflare/database";
78+
* import {
79+
* hyperdriveConnectionString,
80+
* scopedDatabase,
81+
* } from "@vitnode/core/cloudflare/database";
3382
* import { coreRelations } from "@vitnode/core/database/relations";
3483
* import { drizzle } from "drizzle-orm/postgres-js";
3584
*
36-
* dbProvider: scopedDatabase(() =>
85+
* dbProvider: scopedDatabase(({ env }) =>
3786
* drizzle({
38-
* connection: { url: process.env.POSTGRES_URL, max: 1 },
87+
* connection: {
88+
* url: hyperdriveConnectionString(env) ?? process.env.POSTGRES_URL,
89+
* max: 1,
90+
* },
3991
* relations: coreRelations,
4092
* }),
4193
* ),
4294
* ```
4395
*/
44-
/**
45-
* Closes a Drizzle client's driver at once: `end({ timeout: 0 })` drops
46-
* postgres.js connections without waiting, which also ends their pending
47-
* socket reads. A client without `$client.end` is left alone.
48-
*/
49-
const closeDriverClient = async (instance: object): Promise<void> => {
50-
const client: unknown = Reflect.get(instance, "$client");
51-
if (typeof client !== "object" && typeof client !== "function") return;
52-
if (client === null) return;
53-
const end: unknown = Reflect.get(client, "end");
54-
if (typeof end === "function") {
55-
await (end as (options: { timeout: number }) => Promise<void>).call(
56-
client,
57-
{ timeout: 0 },
58-
);
59-
}
60-
};
61-
6296
export const scopedDatabase = <T extends object>(
63-
create: () => T,
97+
create: (context: ScopedDatabaseContext) => T,
6498
{
6599
dispose = closeDriverClient,
66100
}: {
@@ -77,11 +111,12 @@ export const scopedDatabase = <T extends object>(
77111
let processInstance: T | undefined;
78112

79113
const resolve = (): T => {
80-
const resources = currentRealtimeScope()?.resources;
114+
const scope = currentRealtimeScope();
115+
const resources = scope?.resources;
81116
if (resources) {
82117
const existing = resources.get(key);
83118
if (existing) return existing.instance as T;
84-
const instance = create();
119+
const instance = create({ env: scope?.env });
85120
resources.set(key, {
86121
dispose: async () => {
87122
await dispose(instance);
@@ -99,7 +134,7 @@ export const scopedDatabase = <T extends object>(
99134
);
100135
}
101136

102-
return (processInstance ??= create());
137+
return (processInstance ??= create({ env: undefined }));
103138
};
104139

105140
return new Proxy({} as T, {

‎packages/vitnode/src/cloudflare/edge.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,7 @@ export const createCloudflareEdgeScope = ({
194194
};
195195

196196
return {
197+
env,
197198
keepAlive,
198199
resources: new Map<unknown, ScopedResource>(),
199200
runtime: createCloudflareEdgeRuntime({ env, keepAlive }),

‎packages/vitnode/src/cloudflare/hub.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -774,6 +774,7 @@ export const createVitNodeRealtimeHub = ({
774774
/** A fresh scope for one event, bound to this hub's state. */
775775
#scope(): RealtimeScope {
776776
return {
777+
env: this.env,
777778
keepAlive: this.#keepAlive,
778779
resources: this.#resources,
779780
runtime: this.#runtime,

‎packages/vitnode/src/ws/runtime.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,11 @@ export interface RealtimeRuntime {
8080

8181
/** What {@link runInRealtimeScope} makes current for the code it runs. */
8282
export interface RealtimeScope {
83+
/**
84+
* The Cloudflare Worker bindings of this invocation or hub, such as a
85+
* Hyperdrive binding. Set by the Cloudflare scopes only.
86+
*/
87+
env?: Record<string, unknown>;
8388
/**
8489
* Keeps work started in this scope alive past the response: a request's
8590
* `waitUntil`. Every realtime message that leaves the process is passed to

0 commit comments

Comments
 (0)