cloudflare-next-intl 0.7.8 → 0.8.0

package/README.md

@@ -13,6 +13,10 @@ and Cloudflare environment.
 - **Tree-shaking**: Properly architected for optimal tree-shaking.
 - **Error handling**: shared, opt-in `console.error` override and
   `reportError`/`withErrorHandling` helpers, GDPR-aware (consent-gated).
+- **Database**: optional Postgres/Drizzle data-access layer, reachable either
+  directly (Cloudflare Hyperdrive or a connection string) or through the
+  Supabase Data API (project URL + anon key only), with request-scoped
+  public/user contexts and RLS wiring in both modes.
 
 ## Installation
 
@@ -384,6 +388,143 @@ server-side resolution) on `ErrorHandlingParams` — reporting is skipped
 whenever `consent` is set and not `true`, since sending error reports to a
 third party without consent can itself be GDPR-relevant.
 
+### Database (`db`)
+
+Thin Postgres/Drizzle data-access layer over a Cloudflare Hyperdrive binding
+(or a plain connection string). `pg` and `drizzle-orm` ship as dependencies of
+this package, so there is nothing extra to install. They are loaded through
+dynamic `import()` inside the `db` exports, so an app that never calls a `db`
+export never pulls them into its bundle. Enable it by setting `db` on your
+`RoutingConfig`:
+
+```typescript
+// src/i18n/intl_config.ts
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+export default setIntlConfig({
+    locales: ["en", "uk"] as const,
+    defaultLocale: "en",
+    generate: { getCloudflareContext },
+    db: { hyperdriveBinding: "HYPERDRIVE" },
+});
+```
+
+`db` fields (all optional):
+
+- `connectionString` — a Postgres connection string. Omit to resolve it from
+  the Hyperdrive binding named by `hyperdriveBinding` instead (the normal
+  production setup); a value here always wins over the binding, which is
+  what makes local dev / build-time evaluation work.
+- `hyperdriveBinding` — name of the Hyperdrive binding on `env` to read a
+  connection string from when `connectionString` is not set. Defaults to
+  `'HYPERDRIVE'`. Requires `generate.getCloudflareContext` to be configured.
+- `disconnectAfterRequest` — whether the pooled client is closed once the
+  last in-flight `withPublicDb`/`withUserDb` call of the request
+  finishes. Defaults to `true` (one connection per request, released to
+  Hyperdrive immediately). Set `false` to keep the connection open for the
+  lifetime of the isolate — faster for a long-lived server, but it holds a
+  Hyperdrive connection slot between requests.
+- `authenticatedRole` — Postgres role assumed inside `withUserDb`'s
+  transaction. Defaults to `'authenticated'` (the Supabase RLS convention).
+- `getUserId` — resolves the user id injected as
+  `request.jwt.claims->>'sub'` inside `withUserDb`. Omit when
+  `firebaseAuth` is configured — the uid then comes from this package's own
+  `getAuthUser()` automatically. Provide it to use a different auth source
+  (or when `firebaseAuth` is absent).
+- `disconnectTimeoutMs` — milliseconds `disconnectPostgres` waits for
+  `client.end()` before giving up. Defaults to `2000`.
+
+#### Choosing a transport
+
+`db` reaches Postgres one of two ways, decided by which fields you set. The
+query code is identical either way — switching is a config change only.
+
+| Config | Transport | Use when |
+|---|---|---|
+| `connectionString` or `hyperdriveBinding` | Direct Postgres via `pg` | You have a Postgres password or a Hyperdrive binding. |
+| `supabase` | Supabase Data API (PostgREST) | You only have `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY`. |
+
+A direct connection always wins if both are configured, so adding a `supabase`
+block cannot silently reroute live traffic.
+
+```typescript
+export default setIntlConfig({
+    locales: ["en", "uk"] as const,
+    defaultLocale: "en",
+    // reads NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY
+    db: { supabase: {} },
+});
+```
+
+```typescript
+// unchanged in both modes
+const rows = await withPublicDb((db) => db.select().from(bonds).limit(10));
+```
+
+Supabase mode requires one function in your database, shipped at
+`node_modules/cloudflare-next-intl/supabase/cfni_exec.sql`. Run it once (via
+`supabase db push`, a migration, or the SQL editor). It is `security invoker`,
+so statements execute with the caller's own privileges and RLS applies exactly
+as it does over the REST API. `@supabase/supabase-js` ships as a dependency of
+this package and is loaded through dynamic `import()` inside the `db` exports,
+same as `pg`/`drizzle-orm` — an app that never calls a `db` export never
+bundles any of them.
+
+`db.supabase` fields (all optional):
+
+- `url` — project URL. Defaults to `NEXT_PUBLIC_SUPABASE_URL`.
+- `anonKey` — anon/publishable key. Defaults to `NEXT_PUBLIC_SUPABASE_ANON_KEY`.
+  Never put a service-role key here.
+- `execFunction` — name of the exec function. Defaults to `'cfni_exec'`.
+
+`db.getAccessToken` resolves the JWT `withUserDb` sends as
+`Authorization: Bearer`, which is what makes PostgREST resolve the caller as
+`authenticated`. Omit it when `firebaseAuth` is configured — the signed-in
+user's Firebase ID token is used automatically.
+
+**Two differences to know about in Supabase mode:**
+
+- **Per-statement transactions.** Each statement in a `withUserDb` callback is
+  its own round-trip, so it is its own implicit transaction. Multi-statement
+  atomicity is available in connection-string mode only.
+- **Wider SQL surface.** `cfni_exec` runs statements your app generates, so any
+  role that can execute it can run arbitrary SQL *within that role's own
+  privileges* — a broader surface than PostgREST's normal verbs, though still
+  bounded by RLS and your grants. If your app only uses `withUserDb`, drop the
+  anon grant: `revoke execute on function public.cfni_exec(text, jsonb) from anon;`
+
+Two query wrappers, both from `cloudflare-next-intl/db`. Choose by who is
+allowed to see the rows:
+
+- `withPublicDb(fn)` — runs `fn` as the anonymous role: a pooled connection
+  with no transaction/role switch in connection-string mode, or the anon key
+  as the PostgREST bearer token in Supabase mode. No user id is attached
+  either way, so RLS policies that test `auth.jwt()->>'sub'` will deny access
+  — use `withUserDb` for user-owned rows.
+- `withUserDb(fn, uid?)` — runs `fn` as the signed-in user. In
+  connection-string mode this opens a transaction where Postgres sees the
+  resolved user id as `auth.jwt()->>'sub'` under `db.authenticatedRole`; in
+  Supabase mode identity instead rides on the JWT from `getAccessToken`/
+  Firebase, sent as `Authorization: Bearer` (see the atomicity caveat above).
+  Either way RLS behaves as it does for a PostgREST-issued call. `uid`
+  overrides the user id in connection-string mode only; when omitted there,
+  the id comes from `db.getUserId()` if set, otherwise automatically from the
+  signed-in Firebase user when `firebaseAuth` is configured — you rarely need
+  to pass it explicitly.
+
+```typescript
+// anywhere on the server
+import { withPublicDb } from "cloudflare-next-intl/db";
+
+const rows = await withPublicDb((db) => db.select().from(bonds).limit(10));
+```
+
+`cloudflare-next-intl/dbHelpers` also exports a set of generic Drizzle SQL
+helpers (`excluded`, `onConflictSet`, `ago`, `currentDate`, `windowCount`,
+`unnestLateral`, `ascNullsLast`, `alwaysTrue`, `lateral`, `aliasColumn`,
+`minOf`, `maxOf`, `roundReal`, `multiply`, `scalarFromCte`) for building
+upsert/window/lateral-join queries without dropping to raw SQL.
+
 ## License
 
 MIT

package/bin/db_codegen.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Regenerates Drizzle models by introspecting a live Postgres with drizzle-kit.
+// Usage: cfni-db-codegen [--check] [--ddl-dir=…] [--out-dir=…] [--out-file=…] [--db-url=…] [--drizzle-config=…]
+//
+// Needs a reachable Postgres to introspect — any Postgres, not specifically
+// a Docker one. Set CODEGEN_DATABASE_URL to point at whichever you have:
+// local Supabase (./supabase/scripts/db_start.sh --reset, needs Docker), a
+// native Postgres install, or a remote/staging database. With no env var
+// set, it tries the local Supabase default (127.0.0.1:54322).
+// CODEGEN_CONNECT_TIMEOUT_MS overrides the 5s default reachability-check
+// timeout — raise it for a slow/cold-starting remote or serverless target.
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { Client } from 'pg';
+import resolveCodegenPaths from '../dist/src/db/codegen_paths.js';
+
+const paths = resolveCodegenPaths(process.argv.slice(2), process.env, process.cwd());
+
+async function assertReachable(url) {
+    const client = new Client({ connectionString: url, connectionTimeoutMillis: paths.timeoutMs });
+    try {
+        await client.connect();
+        await client.end();
+    } catch (error) {
+        await client.end().catch(() => { /* already failed to connect */ });
+        console.error(`❌ Could not reach Postgres at ${url}\n   (${error.message})`);
+        console.error("\n   drizzle-kit pull needs a live Postgres to introspect — any one works, this script has no Docker dependency of its own. Pick one:");
+        console.error("   - Local Supabase (needs Docker running):  ./supabase/scripts/db_start.sh --reset");
+        console.error("   - A native Postgres you already have:     CODEGEN_DATABASE_URL=postgresql://... npm run db:codegen");
+        console.error("   - A remote/staging database:              CODEGEN_DATABASE_URL=postgresql://... npm run db:codegen");
+        console.error(`   Slow/cold-starting target? Raise the timeout: CODEGEN_CONNECT_TIMEOUT_MS=15000 npm run db:codegen`);
+        process.exit(1);
+    }
+}
+
+function sqlFiles(dir) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) return sqlFiles(path);
+        return entry.name.endsWith(".sql") || entry.name.endsWith(".txt") ? [path] : [];
+    }).sort();
+}
+
+function ddlHash() {
+    const hash = createHash("sha256");
+    for (const file of sqlFiles(paths.ddlDir)) {
+        hash.update(relative(process.cwd(), file));
+        hash.update(readFileSync(file));
+    }
+    return hash.digest("hex");
+}
+
+const hash = ddlHash();
+
+if (paths.check) {
+    const previous = existsSync(paths.manifest) ? JSON.parse(readFileSync(paths.manifest, "utf8")).ddlHash : null;
+    if (previous !== hash) {
+        console.error(`❌ ${relative(process.cwd(), paths.ddlDir)} changed without regenerating models. Run: npm run db:codegen`);
+        process.exit(1);
+    }
+    console.log(`✅ Drizzle models are in sync with ${relative(process.cwd(), paths.ddlDir)}`);
+    process.exit(0);
+}
+
+await assertReachable(paths.dbUrl);
+
+rmSync(paths.pullDir, { recursive: true, force: true });
+execFileSync('npx', ['drizzle-kit', 'pull', ...(paths.drizzleConfig ? [`--config=${paths.drizzleConfig}`] : [])], { stdio: 'inherit' });
+
+mkdirSync(paths.outDir, { recursive: true });
+const pulled = join(paths.pullDir, "schema.ts");
+if (!existsSync(pulled)) {
+    console.error(`❌ drizzle-kit pull produced no schema at ${pulled}`);
+    process.exit(1);
+}
+// Known drizzle-kit 0.31.10 introspection limitation: a column default that
+// is a call to a user-defined Postgres function (e.g. `default
+// public.current_user_id()`) is emitted as a bare, unimported JS identifier
+// call — e.g. `.default(current_user_id())` — instead of being wrapped as a
+// raw SQL expression (`.default(sql\`public.current_user_id()\`)`) the way
+// other non-literal defaults in the same file correctly are (see `sql\`'1000'\``,
+// `sql\`CURRENT_DATE\`` elsewhere in the pulled output). Confirmed via
+// drizzle-kit's own introspection source (node_modules/drizzle-kit/api.js):
+// the Postgres column-default normalizer only flags a default as an
+// expression (`isDefaultAnExpression`) for numeric columns; for
+// text/varchar/uuid columns a non-quoted, non-numeric default string is
+// returned verbatim with no such flag, so the codegen path that decides
+// whether to wrap in sql`` never sees it. There is no newer drizzle-kit
+// release (0.31.10 is already `latest`) and no pull/config flag that
+// changes this. `now()` and `gen_random_uuid()` don't hit this because
+// drizzle-kit special-cases those into `.defaultNow()` / `.defaultRandom()`;
+// any other bare `identifier()` call default does not get that treatment.
+// This patch detects that specific shape and rewrites it into the correct
+// sql`` form so the generated file is importable without throwing
+// `ReferenceError: <fn> is not defined`.
+function patchBareFunctionCallDefaults(source) {
+    return source.replace(
+        /\.default\((?!sql`)([a-zA-Z_][a-zA-Z0-9_]*)\(\)\)/g,
+        (match, fnName) => `.default(sql\`public.${fnName}()\`)`,
+    );
+}
+
+const banner = `// GENERATED by cfni-db-codegen from ${relative(process.cwd(), paths.ddlDir)} — do not edit.\n`;
+const pulledSource = patchBareFunctionCallDefaults(readFileSync(pulled, "utf8"));
+writeFileSync(paths.outFile, banner + pulledSource);
+rmSync(paths.pullDir, { recursive: true, force: true });
+writeFileSync(paths.manifest, `${JSON.stringify({ ddlHash: hash }, null, 2)}\n`);
+console.log(`✅ Generated ${relative(process.cwd(), paths.outFile)}`);

package/dist/src/db/access_token.d.ts

@@ -0,0 +1,14 @@
+import type { DbConfig } from './connection';
+/**
+ * Resolves the JWT that identifies the caller to Supabase, trying
+ * `db.getAccessToken()` first, then the signed-in Firebase user's ID token.
+ *
+ * PostgREST reads this token to pick the caller's role and populate
+ * `request.jwt.claims`, which is what makes RLS behave the same as it does in
+ * connection-string mode.
+ *
+ * @param config Your routing config; `config.db` must be set.
+ * @returns The bearer token to send with the request.
+ * @throws If `db` is not set, or no token can be resolved.
+ */
+export default function resolveAccessToken(config: DbConfig): Promise<string>;

package/dist/src/db/access_token.js

@@ -0,0 +1,30 @@
+import requireDbConfig from './require_config';
+/**
+ * Resolves the JWT that identifies the caller to Supabase, trying
+ * `db.getAccessToken()` first, then the signed-in Firebase user's ID token.
+ *
+ * PostgREST reads this token to pick the caller's role and populate
+ * `request.jwt.claims`, which is what makes RLS behave the same as it does in
+ * connection-string mode.
+ *
+ * @param config Your routing config; `config.db` must be set.
+ * @returns The bearer token to send with the request.
+ * @throws If `db` is not set, or no token can be resolved.
+ */
+export default async function resolveAccessToken(config) {
+    const db = config.db;
+    requireDbConfig(db);
+    const fromConfig = await db.getAccessToken?.();
+    if (fromConfig)
+        return fromConfig;
+    if (config.firebaseAuth) {
+        const { getAuthUser } = await import('../firebase_auth/server/use_auth_user_server');
+        const { user } = await getAuthUser();
+        const token = await user?.getIdToken(false);
+        if (token)
+            return token;
+    }
+    throw new Error('db: withUserDb could not resolve an access token for Supabase. Set ' +
+        '`db.getAccessToken`, or configure `firebaseAuth` so the signed-in ' +
+        'user\'s Firebase ID token is used.');
+}

package/dist/src/db/codegen_paths.d.ts

@@ -0,0 +1,13 @@
+export interface CodegenPaths {
+    ddlDir: string;
+    outDir: string;
+    outFile: string;
+    pullDir: string;
+    manifest: string;
+    dbUrl: string;
+    check: boolean;
+    timeoutMs: number;
+    drizzleConfig: string | null;
+}
+/** Resolves every codegen path from flags, then env, then the documented defaults. */
+export default function resolveCodegenPaths(argv: readonly string[], env: Record<string, string | undefined>, cwd: string): CodegenPaths;

package/dist/src/db/codegen_paths.js

@@ -0,0 +1,32 @@
+import { isAbsolute, join, resolve } from 'node:path';
+const DEFAULT_DDL_DIR = 'supabase/data-base';
+const DEFAULT_OUT_DIR = 'src/shared/db/generated';
+const DEFAULT_OUT_FILE = 'schema.ts';
+const DEFAULT_DB_URL = 'postgresql://postgres:postgres@127.0.0.1:54322/postgres';
+const DEFAULT_TIMEOUT_MS = 5000;
+function flag(argv, name) {
+    const prefix = `--${name}=`;
+    const hit = argv.find((arg) => arg.startsWith(prefix));
+    return hit?.slice(prefix.length);
+}
+function abs(cwd, value) {
+    return isAbsolute(value) ? value : resolve(cwd, value);
+}
+/** Resolves every codegen path from flags, then env, then the documented defaults. */
+export default function resolveCodegenPaths(argv, env, cwd) {
+    const ddlDir = abs(cwd, flag(argv, 'ddl-dir') ?? env.CFNI_DB_DDL_DIR ?? DEFAULT_DDL_DIR);
+    const outDir = abs(cwd, flag(argv, 'out-dir') ?? env.CFNI_DB_OUT_DIR ?? DEFAULT_OUT_DIR);
+    const outFileName = flag(argv, 'out-file') ?? env.CFNI_DB_OUT_FILE ?? DEFAULT_OUT_FILE;
+    const drizzleConfig = flag(argv, 'drizzle-config') ?? env.CFNI_DB_DRIZZLE_CONFIG ?? null;
+    return {
+        ddlDir,
+        outDir,
+        outFile: join(outDir, outFileName),
+        pullDir: resolve(outDir, '..', '.drizzle-pull'),
+        manifest: join(outDir, 'manifest.json'),
+        dbUrl: flag(argv, 'db-url') ?? env.CODEGEN_DATABASE_URL ?? DEFAULT_DB_URL,
+        check: argv.includes('--check'),
+        timeoutMs: Number(env.CODEGEN_CONNECT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS,
+        drizzleConfig: drizzleConfig === null ? null : abs(cwd, drizzleConfig),
+    };
+}

package/dist/src/db/connection.d.ts

@@ -0,0 +1,42 @@
+import type { Client } from 'pg';
+import type { LocalePrefixMode, Locales, RoutingConfig } from '../types/types';
+export type DbConfig = RoutingConfig<Locales, LocalePrefixMode>;
+/**
+ * Forgets the cached client and connection string so the next
+ * `connectToPostgres` call builds both from scratch. Intended for tests and
+ * for after a `db` config change.
+ *
+ * This drops the reference **without closing** an open connection, so only
+ * call it when no query is in flight — otherwise use `disconnectPostgres`,
+ * which closes the client properly.
+ */
+export declare function resetConnectionState(): void;
+/**
+ * Returns the request's shared, already-connected Postgres client, creating it
+ * on first use and reusing it for every later caller in the same request.
+ *
+ * Prefer `withPublicDb`/`withUserDb`, which call this for you and always
+ * release the connection. Reach for this directly only when you need the raw
+ * `pg` client — and then every call **must** be paired with a
+ * `disconnectPostgres` call, or the connection is never released.
+ *
+ * @param config Your routing config; `config.db` must be set.
+ * @returns The connected, shared client.
+ * @throws If `db` is not set, or no connection string can be resolved from
+ * `db.connectionString` or the Hyperdrive binding.
+ */
+export default function connectToPostgres(config: DbConfig): Promise<Client>;
+/**
+ * Releases one caller's hold on the shared client, closing it once the last
+ * holder of the request is done. Call it exactly once per
+ * `connectToPostgres` call.
+ *
+ * Returns immediately and finishes closing in the background (via
+ * `ctx.waitUntil` when a Cloudflare context is available), so it never delays
+ * the response. Closing errors are reported through `errorHandling`, not
+ * thrown. Does nothing when `db.disconnectAfterRequest` is `false`, which
+ * keeps the connection open for the life of the isolate.
+ *
+ * @param config Your routing config; safe to call when `config.db` is unset.
+ */
+export declare function disconnectPostgres(config: DbConfig): void;

package/dist/src/db/connection.js

@@ -0,0 +1,178 @@
+import reportError from '../error_handling/report_error';
+import requireDbConfig from './require_config';
+const DEFAULT_BINDING = 'HYPERDRIVE';
+const DEFAULT_DISCONNECT_TIMEOUT_MS = 2000;
+let connectionString = null;
+let client = null;
+let connectionPromise = null;
+let connectingPromise = null;
+let disconnectionPromise = null;
+let activeUsers = 0;
+/**
+ * Forgets the cached client and connection string so the next
+ * `connectToPostgres` call builds both from scratch. Intended for tests and
+ * for after a `db` config change.
+ *
+ * This drops the reference **without closing** an open connection, so only
+ * call it when no query is in flight — otherwise use `disconnectPostgres`,
+ * which closes the client properly.
+ */
+export function resetConnectionState() {
+    connectionString = null;
+    client = null;
+    connectionPromise = null;
+    connectingPromise = null;
+    disconnectionPromise = null;
+    activeUsers = 0;
+}
+/**
+ * Resolves the connection string from `db.connectionString` first, then the
+ * Cloudflare Hyperdrive binding named by `db.hyperdriveBinding`.
+ */
+async function resolveConnectionString(config, db) {
+    if (db.connectionString)
+        return db.connectionString;
+    const getContext = config.generate?.getCloudflareContext;
+    if (getContext) {
+        const context = await getContext({ async: true });
+        const env = context?.env;
+        const binding = env?.[db.hyperdriveBinding ?? DEFAULT_BINDING];
+        if (binding?.connectionString)
+            return binding.connectionString;
+    }
+    throw new Error('db: could not resolve a Postgres connection string. Set `db.connectionString`, or ' +
+        `configure \`generate.getCloudflareContext\` and a \`${db.hyperdriveBinding ?? DEFAULT_BINDING}\` ` +
+        'Hyperdrive binding on your Worker.');
+}
+// A single `pg.Client` is not safe for concurrent queries; Next.js fires many
+// in parallel per request. Serializing every `query` through one promise chain
+// keeps one connection correct instead of paying for a pool on top of
+// Hyperdrive's own pooling.
+function serializeQueries(raw) {
+    const originalQuery = raw.query;
+    if (typeof originalQuery !== 'function')
+        return raw;
+    let last = Promise.resolve();
+    raw.query = (...args) => {
+        const run = () => originalQuery.apply(raw, args);
+        const next = last.then(run, run);
+        last = next.catch(() => undefined);
+        return next;
+    };
+    return raw;
+}
+/**
+ * Returns the request's shared, already-connected Postgres client, creating it
+ * on first use and reusing it for every later caller in the same request.
+ *
+ * Prefer `withPublicDb`/`withUserDb`, which call this for you and always
+ * release the connection. Reach for this directly only when you need the raw
+ * `pg` client — and then every call **must** be paired with a
+ * `disconnectPostgres` call, or the connection is never released.
+ *
+ * @param config Your routing config; `config.db` must be set.
+ * @returns The connected, shared client.
+ * @throws If `db` is not set, or no connection string can be resolved from
+ * `db.connectionString` or the Hyperdrive binding.
+ */
+export default async function connectToPostgres(config) {
+    const db = config.db;
+    requireDbConfig(db);
+    await disconnectionPromise;
+    if (connectingPromise === null) {
+        connectingPromise = (async () => {
+            try {
+                connectionString ?? (connectionString = await resolveConnectionString(config, db));
+                const { Client } = await import('pg');
+                const created = serializeQueries(new Client({ connectionString }));
+                client = created;
+                connectionPromise = created.connect();
+                await connectionPromise;
+                return created;
+            }
+            catch (error) {
+                // A failed connect must not be cached forever — clear state so the
+                // next call retries instead of replaying the same rejection for the
+                // life of the Worker isolate.
+                connectingPromise = null;
+                connectionString = null;
+                client = null;
+                connectionPromise = null;
+                throw error;
+            }
+        })();
+    }
+    activeUsers++;
+    return connectingPromise;
+}
+/**
+ * Releases one caller's hold on the shared client, closing it once the last
+ * holder of the request is done. Call it exactly once per
+ * `connectToPostgres` call.
+ *
+ * Returns immediately and finishes closing in the background (via
+ * `ctx.waitUntil` when a Cloudflare context is available), so it never delays
+ * the response. Closing errors are reported through `errorHandling`, not
+ * thrown. Does nothing when `db.disconnectAfterRequest` is `false`, which
+ * keeps the connection open for the life of the isolate.
+ *
+ * @param config Your routing config; safe to call when `config.db` is unset.
+ */
+export function disconnectPostgres(config) {
+    const db = config.db;
+    if (!db || db.disconnectAfterRequest === false)
+        return;
+    activeUsers = Math.max(0, activeUsers - 1);
+    if (!client || activeUsers !== 0)
+        return;
+    const closing = client;
+    // Null out synchronously so a concurrent request creates a fresh client
+    // instead of reusing one that is about to close.
+    client = null;
+    connectionPromise = null;
+    connectingPromise = null;
+    const endPromise = closing.end();
+    disconnectionPromise = endPromise;
+    const timeoutMs = db.disconnectTimeoutMs ?? DEFAULT_DISCONNECT_TIMEOUT_MS;
+    const settle = async () => {
+        try {
+            await Promise.race([
+                endPromise,
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout closing postgres client')), timeoutMs)),
+            ]);
+        }
+        catch (error) {
+            await reportError({ errorHandling: config.errorHandling, generate: config.generate }, { error, classOrMethodName: 'db.disconnectPostgres' });
+        }
+        finally {
+            if (disconnectionPromise === endPromise)
+                disconnectionPromise = null;
+        }
+    };
+    const getContext = config.generate?.getCloudflareContext;
+    if (!getContext) {
+        void settle();
+        return;
+    }
+    void (async () => {
+        // No matter what happens resolving the context/waitUntil below,
+        // settle() must always run — it's the only place disconnectionPromise
+        // gets cleared, and connectToPostgres awaits that promise on every
+        // call. A rejected/throwing getContext must still fall through to
+        // settle() directly instead of leaving the disconnect stuck forever.
+        let waitUntil;
+        try {
+            const context = await getContext({ async: true });
+            if (typeof context?.ctx?.waitUntil === 'function') {
+                waitUntil = context.ctx.waitUntil.bind(context.ctx);
+            }
+        }
+        catch {
+            waitUntil = undefined;
+        }
+        if (waitUntil)
+            waitUntil(settle());
+        else
+            await settle();
+    })();
+}

package/dist/src/db/context.d.ts

@@ -0,0 +1,57 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+/**
+ * The Drizzle handle passed to `withPublicDb`/`withUserDb` callbacks. Use it
+ * exactly like a normal Drizzle database (`db.select().from(table)`); it is
+ * typed without a schema because you pass your own generated tables in.
+ */
+export type DrizzleDb = NodePgDatabase<Record<string, never>>;
+/**
+ * Runs a query as the **anonymous** role: no transaction, no role switch, no
+ * user identity attached. Use this for data any visitor may read.
+ *
+ * Because no user id is set, RLS policies that test `auth.jwt()->>'sub'` see
+ * no user and will deny access — reach for {@link withUserDb} whenever the
+ * rows depend on who is asking.
+ *
+ * In connection-string mode the connection is taken from the request's
+ * shared client and released when `fn` settles, even if it throws. In
+ * Supabase mode there is no connection to release — each call is one
+ * PostgREST round-trip authenticated as the anon key.
+ *
+ * @param fn Receives the Drizzle handle; return whatever the caller needs.
+ * @returns Whatever `fn` resolves to.
+ * @throws If `db` is not set on your `RoutingConfig`, or the connection fails.
+ *
+ * @example
+ * const rows = await withPublicDb((db) => db.select().from(bonds).limit(10));
+ */
+export declare function withPublicDb<T>(fn: (db: DrizzleDb) => Promise<T>): Promise<T>;
+/**
+ * Runs a query as the **signed-in user**.
+ *
+ * In connection-string mode this runs inside a transaction where Postgres
+ * sees the resolved user id as `auth.jwt()->>'sub'` under
+ * `db.authenticatedRole`, so RLS policies behave exactly as they do for a
+ * PostgREST-issued call. In Supabase mode identity instead rides on the JWT
+ * sent as `Authorization: Bearer` — PostgREST resolves the `authenticated`
+ * role and populates `request.jwt.claims` itself, and each statement is its
+ * own round-trip with no cross-statement transaction (the Postgres proxy
+ * Drizzle uses in this mode cannot open one). Either way this is the wrapper
+ * to use for anything user-owned.
+ *
+ * @param fn Receives the Drizzle handle. In connection-string mode it is
+ * bound to a transaction; in Supabase mode it is not — do not rely on
+ * multi-statement atomicity there.
+ * @param uid Connection-string mode only: overrides the user id. Omit it in
+ * normal use — the id then comes from `db.getUserId()` when set, otherwise
+ * from the signed-in Firebase user when `firebaseAuth` is configured.
+ * Ignored in Supabase mode, which resolves identity via `db.getAccessToken`/
+ * Firebase instead — see {@link resolveAccessToken}.
+ * @returns Whatever `fn` resolves to.
+ * @throws If `db` is not set on your `RoutingConfig`, if no user id/access
+ * token can be resolved, or the connection fails.
+ *
+ * @example
+ * const mine = await withUserDb((db) => db.select().from(orders));
+ */
+export declare function withUserDb<T>(fn: (db: DrizzleDb) => Promise<T>, uid?: string): Promise<T>;