cloudflare-next-intl 0.8.22 → 0.8.24

package/README.md

@@ -461,23 +461,21 @@ export default setIntlConfig({
   returning one (resolved on each connect). The function form is how you reach
   a value that isn't available at module scope — a Cloudflare Hyperdrive
   binding, or a secret store — as in the example above.
-- `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 `withUserDb` switches the shared
-  session to for the duration of your callback (`set role`, reset once it
-  settles — no transaction involved). Defaults to `'authenticated'` (the
-  Supabase RLS convention).
+- `disconnectAfterRequest` — **deprecated, ignored since 0.8.23.** Every
+  `withPublicDb`/`withUserDb` call now opens and closes its own client, so
+  there is no surviving connection to keep open. Hyperdrive pools the
+  server-side connection.
+- `authenticatedRole` — Postgres role `withUserDb` switches its
+  call-scoped session to for the duration of your callback (`set role`, no
+  transaction involved; the session is closed when the call ends). 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`.
+- `disconnectTimeoutMs` — **deprecated, ignored since 0.8.23.** Client
+  teardown is awaited or deferred to `ctx.waitUntil` without a timeout.
 
 #### Choosing a transport
 

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

@@ -2,63 +2,38 @@ import type { Client } from 'pg';
 import type { LocalePrefixMode, Locales, RoutingConfig } from '../types/types';
 export type DbConfig = RoutingConfig<Locales, LocalePrefixMode>;
 /**
- * Runs `fn` exclusively against the shared client: no other
- * `withSessionLock` caller's queries can interleave with `fn`'s until it
- * settles. `serializeQueries` alone only orders individual `.query()` calls —
- * it does nothing to stop a *different* concurrent request's queries from
- * landing between, say, `set role`/`set_config(...)` and the query that
- * depends on it, on the one `pg.Client` every request in the isolate shares.
- * That gap let one request's role/RLS identity leak into another's queries
- * whenever two requests overlapped in the same Worker isolate — and, when
- * `withUserDb` used to wrap its call in a real `BEGIN`/`COMMIT` transaction,
- * interleaved transaction boundaries from two overlapping callers made
- * Postgres itself reject statements ("already a transaction in progress").
- * `withUserDb` no longer opens a transaction on this shared client for
- * exactly that reason (session-scoped `set role`/`set_config(..., false)`
- * need no transaction to apply) — but every caller that still depends on
- * session-scoped state on the shared client MUST run inside this lock.
+ * Runs `queryFn` on a Postgres client scoped to this single call: one
+ * `connect()`, your callback, then a guaranteed `end()`. Each call gets its own
+ * client, so concurrent renders in the same isolate can never share session
+ * state (role, `request.jwt.claims`, an open transaction) with each other.
+ * Hyperdrive pools the server-side connection behind this.
  */
-export declare function withSessionLock<T>(fn: () => Promise<T>): Promise<T>;
+export declare function withDbClient<T>(config: DbConfig, queryFn: (client: Client) => Promise<T>): Promise<T>;
 /**
- * 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.
+ * No-op kept for backward compatibility. There is no cached connection state
+ * to reset now that every {@link withDbClient} call owns its client.
  *
- * 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.
+ * @deprecated Connection state is per-call; this does nothing.
  */
 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.
+ * Runs `fn` directly. Kept for backward compatibility: session state can no
+ * longer leak between callers, so there is nothing left to serialize.
  *
- * @param config Your routing config; `config.db` must be set.
- * @param resolved A connection string already resolved by the caller (e.g.
- * `resolveDbMode`, which has to call `db.connectionString` itself to decide
- * the transport) — pass it to skip resolving `db.connectionString` a second
- * time. Omit it to have this function resolve it itself, as before.
- * @returns The connected, shared client.
- * @throws If `db` is not set, or no connection string can be resolved from
- * `db.connectionString`.
+ * @deprecated Clients are per-call now; no lock is needed.
  */
-export default function connectToPostgres(config: DbConfig, resolved?: string | undefined): Promise<Client>;
+export declare function withSessionLock<T>(fn: () => Promise<T>): Promise<T>;
 /**
- * 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.
+ * Opens a Postgres client the caller owns and must close with
+ * {@link disconnectPostgres}. Prefer {@link withDbClient}, which closes the
+ * client for you even when the callback throws.
  *
- * 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.
+ * @deprecated Use {@link withDbClient} instead.
+ */
+export declare function connectToPostgres(config: DbConfig): Promise<Client>;
+/**
+ * Closes a client from {@link connectToPostgres}.
  *
- * @param config Your routing config; safe to call when `config.db` is unset.
+ * @deprecated Use {@link withDbClient} instead.
  */
-export declare function disconnectPostgres(config: DbConfig): void;
+export declare function disconnectPostgres(client?: Client): Promise<void>;

package/dist/src/db/connection.js

@@ -1,63 +1,16 @@
 import reportError from '../error_handling/report_error';
 import requireDbConfig from './require_config';
 import resolveConfigValue from './resolve_config_value';
-const DEFAULT_DISCONNECT_TIMEOUT_MS = 2000;
-let connectionString = null;
-let client = null;
-let connectionPromise = null;
-let disconnectionPromise = null;
-let activeUsers = 0;
-let sessionLock = Promise.resolve();
+let pgModule;
 /**
- * Runs `fn` exclusively against the shared client: no other
- * `withSessionLock` caller's queries can interleave with `fn`'s until it
- * settles. `serializeQueries` alone only orders individual `.query()` calls —
- * it does nothing to stop a *different* concurrent request's queries from
- * landing between, say, `set role`/`set_config(...)` and the query that
- * depends on it, on the one `pg.Client` every request in the isolate shares.
- * That gap let one request's role/RLS identity leak into another's queries
- * whenever two requests overlapped in the same Worker isolate — and, when
- * `withUserDb` used to wrap its call in a real `BEGIN`/`COMMIT` transaction,
- * interleaved transaction boundaries from two overlapping callers made
- * Postgres itself reject statements ("already a transaction in progress").
- * `withUserDb` no longer opens a transaction on this shared client for
- * exactly that reason (session-scoped `set role`/`set_config(..., false)`
- * need no transaction to apply) — but every caller that still depends on
- * session-scoped state on the shared client MUST run inside this lock.
+ * Loads `pg` lazily, so an app that never touches the Postgres transport never
+ * bundles it, and caches the module promise so concurrent callers share one
+ * resolution instead of racing separate `import()` calls.
  */
-export async function withSessionLock(fn) {
-    const previous = sessionLock;
-    let release;
-    sessionLock = new Promise((resolve) => { release = resolve; });
-    await previous;
-    try {
-        return await fn();
-    }
-    finally {
-        release();
-    }
-}
-/**
- * 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;
-    disconnectionPromise = null;
-    activeUsers = 0;
-    sessionLock = Promise.resolve();
+function loadPg() {
+    pgModule ?? (pgModule = import('pg'));
+    return pgModule;
 }
-/**
- * Resolves the connection string from `db.connectionString`, awaiting it when
- * it was given as a function.
- */
 async function resolveConnectionString(db) {
     const configured = await resolveConfigValue(db.connectionString);
     if (configured)
@@ -66,165 +19,100 @@ async function resolveConnectionString(db) {
         'to a connection string, or to a function returning one (e.g. reading a ' +
         'Hyperdrive binding off `getCloudflareContext().env`).');
 }
-// 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.
- * @param resolved A connection string already resolved by the caller (e.g.
- * `resolveDbMode`, which has to call `db.connectionString` itself to decide
- * the transport) — pass it to skip resolving `db.connectionString` a second
- * time. Omit it to have this function resolve it itself, as before.
- * @returns The connected, shared client.
- * @throws If `db` is not set, or no connection string can be resolved from
- * `db.connectionString`.
+ * Runs `queryFn` on a Postgres client scoped to this single call: one
+ * `connect()`, your callback, then a guaranteed `end()`. Each call gets its own
+ * client, so concurrent renders in the same isolate can never share session
+ * state (role, `request.jwt.claims`, an open transaction) with each other.
+ * Hyperdrive pools the server-side connection behind this.
  */
-export default async function connectToPostgres(config, resolved) {
+export async function withDbClient(config, queryFn) {
     const db = config.db;
     requireDbConfig(db);
-    await disconnectionPromise;
-    // Guards the race between concurrent callers that both see `client ===
-    // null` before either has awaited anything: `connectionPromise` is set
-    // synchronously (before the `await`s below) so every caller in the same
-    // microtask tick shares the one client being created instead of each
-    // starting its own.
-    if (connectionPromise === null) {
-        connectionPromise = (async () => {
-            connectionString = resolved ?? await resolveConnectionString(db);
-            const { Client } = await import('pg');
-            const created = serializeQueries(new Client({ connectionString }));
-            // The shared client outlives a single request (see the module doc)
-            // and Hyperdrive/Postgres can close its idle socket at any time. `pg`
-            // surfaces that as an `'error'` event on the `Client`, which is an
-            // `EventEmitter` — with no listener, Node treats it as unhandled and
-            // throws, crashing whatever unrelated request happens to be running
-            // in the isolate at that moment. Listening here converts it into a
-            // clean reset so the next call reconnects instead.
-            created.on('error', (error) => {
-                if (client === created) {
-                    client = null;
-                    connectionString = null;
-                    connectionPromise = null;
-                }
-                // `pg` emits "Connection terminated"/"Connection terminated
-                // unexpectedly" (lib/client.js) — never "Connection closed" —
-                // when the idle socket dies outside a query. That's the
-                // expected shape of this event (Hyperdrive/Postgres recycling
-                // the connection, not a query failure): swallow it entirely,
-                // don't report or log it.
-                if (/(connection terminated|connection closed)/i.test(error.message))
-                    return;
-                void reportError({ errorHandling: config.errorHandling, generate: config.generate }, { error, classOrMethodName: 'db.connectToPostgres.clientError' });
-            });
-            client = created;
-            await created.connect();
-            return created;
-        })();
-    }
-    activeUsers++;
+    const connectionString = await resolveConnectionString(db);
+    const { Client: PgClient } = await loadPg();
+    const client = new PgClient({ connectionString });
+    let result;
+    let connected = false;
     try {
-        return await connectionPromise;
+        try {
+            await client.connect();
+            connected = true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error ?? '');
+            if (!/(connection terminated|connection closed|socket closed|unexpected eof)/i.test(message)) {
+                void reportError({ errorHandling: config.errorHandling, generate: config.generate }, { error, classOrMethodName: 'db.withDbClient.connectError' });
+            }
+            throw error;
+        }
+        result = await queryFn(client);
     }
-    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.
-        activeUsers = Math.max(0, activeUsers - 1);
-        connectionString = null;
-        client = null;
-        connectionPromise = null;
-        throw error;
+    finally {
+        const endPromise = connected ? client.end() : Promise.resolve();
+        const getContext = config.generate?.getCloudflareContext;
+        if (!getContext || db.disconnectAfterRequest === false) {
+            await endPromise.catch(() => undefined);
+        }
+        else {
+            try {
+                const context = await getContext({ async: true });
+                if (typeof context?.ctx?.waitUntil === 'function') {
+                    context.ctx.waitUntil(endPromise.catch(() => undefined));
+                }
+                else {
+                    await endPromise.catch(() => undefined);
+                }
+            }
+            catch {
+                await endPromise.catch(() => undefined);
+            }
+        }
     }
+    return result;
 }
 /**
- * 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.
+ * No-op kept for backward compatibility. There is no cached connection state
+ * to reset now that every {@link withDbClient} call owns its client.
  *
- * 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.
+ * @deprecated Connection state is per-call; this does nothing.
+ */
+export function resetConnectionState() {
+    // no cached state to reset
+}
+/**
+ * Runs `fn` directly. Kept for backward compatibility: session state can no
+ * longer leak between callers, so there is nothing left to serialize.
  *
- * @param config Your routing config; safe to call when `config.db` is unset.
+ * @deprecated Clients are per-call now; no lock is needed.
  */
-export function disconnectPostgres(config) {
+export async function withSessionLock(fn) {
+    return await fn();
+}
+/**
+ * Opens a Postgres client the caller owns and must close with
+ * {@link disconnectPostgres}. Prefer {@link withDbClient}, which closes the
+ * client for you even when the callback throws.
+ *
+ * @deprecated Use {@link withDbClient} instead.
+ */
+export async function connectToPostgres(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;
-    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();
-    })();
+    requireDbConfig(db);
+    const connectionString = await resolveConnectionString(db);
+    const { Client: PgClient } = await loadPg();
+    const client = new PgClient({ connectionString });
+    client.on('error', (error) => {
+        void reportError({ errorHandling: config.errorHandling, generate: config.generate }, { error, classOrMethodName: 'db.connectToPostgres.clientError' });
+    });
+    await client.connect();
+    return client;
+}
+/**
+ * Closes a client from {@link connectToPostgres}.
+ *
+ * @deprecated Use {@link withDbClient} instead.
+ */
+export async function disconnectPostgres(client) {
+    await client?.end().catch(() => undefined);
 }

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

@@ -9,64 +9,20 @@ 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. Either way, call
- * `.transaction(...)` on the handle `fn` receives for atomicity across more
- * than one statement — see the module doc for the shape that takes in each mode.
- *
  * @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**.
+ * Runs a query as the **signed-in user**, with `request.jwt.claims` and the
+ * authenticated role set on the session so RLS policies apply to their id.
  *
- * In connection-string mode this sets the resolved user id as
- * `auth.jwt()->>'sub'` and switches to `db.authenticatedRole` on the
- * request's shared session (via `set_config(..., false)`/`set role`, reset
- * once `fn` settles), so RLS policies behave exactly as they do for a
- * PostgREST-issued call — but it does NOT open a `BEGIN`/`COMMIT`
- * transaction: that client is shared across every concurrent caller in the
- * isolate (see `connection.ts`), and a live transaction is itself
- * session-scoped state that a second overlapping caller's transaction would
- * collide with. Call `fn`'s own `.transaction(...)` (below) for atomicity
- * across statements instead. 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 unless
- * you call `.transaction(...)` on the handle (the Postgres proxy Drizzle
- * uses in this mode cannot open a real session, so that runs as one atomic
- * `cfni_exec_batch` call instead — see the module doc). Either way this is
- * the wrapper to use for anything user-owned.
- *
- * @param fn Receives the Drizzle handle, scoped to the caller's identity/role
- * but not wrapped in a transaction — call its own `.transaction(...)` for
- * atomicity across statements (build-and-return shape in both modes, not a
- * live session — see the module doc).
- * @param uid Connection-string mode only: overrides the user id. Omit it, or
- * pass `null`, in normal use — either way the id then comes from
- * `db.getUserId()` when set, otherwise from the signed-in Firebase user when
- * `firebaseAuth` is configured. `null` is accepted alongside `undefined` so a
- * caller's own lookup (which may itself come back empty) can be passed
- * straight through without an extra check. 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.
+ * The session lives on a client scoped to this call and closed when it ends,
+ * so the role and claims can never be observed by another caller.
  *
- * @example
- * const mine = await withUserDb((db) => db.select().from(orders));
+ * @param fn Receives the Drizzle handle
+ * @param uid Overrides the user ID for authenticated calls
  */
 export declare function withUserDb<T>(fn: (db: DrizzleDb) => Promise<T>, uid?: string | null): Promise<T>;
 /** One statement's `{rows, rowCount}` result from a Supabase-mode `db.transaction()` batch. */

package/dist/src/db/context.js

@@ -1,6 +1,6 @@
 import config from '../config/intl_config';
 import requireDbConfig from './require_config';
-import connectToPostgres, { disconnectPostgres, withSessionLock } from './connection';
+import { withDbClient } from './connection';
 import resolveDbMode from './resolve_mode';
 import resolveSupabaseEndpoint from './supabase_config';
 import createSupabaseTransport from './supabase_transport';
@@ -73,11 +73,8 @@ async function postgresDb(drizzleHandle, rawClient) {
  * via an inline-parameterised `query()` call, wrapped in a real
  * `BEGIN`/`COMMIT` for atomicity, and returns `ExecResult[]`.
  *
- * Safe to open a transaction here — unlike `withUserDb`'s own body, this
- * only ever runs from inside `fn`, which `withUserDb`/`withPublicDb` already
- * call from within `withSessionLock` (`connection.ts`). That lock is what
- * keeps this `BEGIN`...`COMMIT` from overlapping with another caller's on the
- * same shared client, so nothing here needs to reason about interleaving.
+ * The client is scoped to one `withDbClient` call, so no other caller can
+ * interleave statements into this transaction.
  */
 async function runPostgresTransaction(rawClient, build) {
     const queries = await build(buildOnlyDb());
@@ -93,7 +90,7 @@ async function runPostgresTransaction(rawClient, build) {
         return results;
     }
     catch (error) {
-        await rawClient.query('rollback');
+        await rawClient.query('rollback').catch(() => undefined);
         throw error;
     }
 }
@@ -118,23 +115,9 @@ function buildOnlyDb() {
  * 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. Either way, call
- * `.transaction(...)` on the handle `fn` receives for atomicity across more
- * than one statement — see the module doc for the shape that takes in each mode.
- *
  * @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 async function withPublicDb(fn) {
     const db = config.db;
@@ -144,58 +127,22 @@ export async function withPublicDb(fn) {
         const { anonKey } = await resolveSupabaseEndpoint(resolved.supabase);
         return fn(await supabaseDb(resolved.supabase, anonKey));
     }
-    const client = await connectToPostgres(config, resolved.connectionString);
-    try {
-        return await withSessionLock(async () => {
-            const { drizzle } = await import('drizzle-orm/node-postgres');
-            const drizzleHandle = drizzle(client);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            return await fn(await postgresDb(drizzleHandle, client));
-        });
-    }
-    finally {
-        disconnectPostgres(config);
-    }
+    return await withDbClient(config, async (client) => {
+        const { drizzle } = await import('drizzle-orm/node-postgres');
+        const drizzleHandle = drizzle(client);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await fn(await postgresDb(drizzleHandle, client));
+    });
 }
 /**
- * Runs a query as the **signed-in user**.
+ * Runs a query as the **signed-in user**, with `request.jwt.claims` and the
+ * authenticated role set on the session so RLS policies apply to their id.
  *
- * In connection-string mode this sets the resolved user id as
- * `auth.jwt()->>'sub'` and switches to `db.authenticatedRole` on the
- * request's shared session (via `set_config(..., false)`/`set role`, reset
- * once `fn` settles), so RLS policies behave exactly as they do for a
- * PostgREST-issued call — but it does NOT open a `BEGIN`/`COMMIT`
- * transaction: that client is shared across every concurrent caller in the
- * isolate (see `connection.ts`), and a live transaction is itself
- * session-scoped state that a second overlapping caller's transaction would
- * collide with. Call `fn`'s own `.transaction(...)` (below) for atomicity
- * across statements instead. 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 unless
- * you call `.transaction(...)` on the handle (the Postgres proxy Drizzle
- * uses in this mode cannot open a real session, so that runs as one atomic
- * `cfni_exec_batch` call instead — see the module doc). Either way this is
- * the wrapper to use for anything user-owned.
+ * The session lives on a client scoped to this call and closed when it ends,
+ * so the role and claims can never be observed by another caller.
  *
- * @param fn Receives the Drizzle handle, scoped to the caller's identity/role
- * but not wrapped in a transaction — call its own `.transaction(...)` for
- * atomicity across statements (build-and-return shape in both modes, not a
- * live session — see the module doc).
- * @param uid Connection-string mode only: overrides the user id. Omit it, or
- * pass `null`, in normal use — either way the id then comes from
- * `db.getUserId()` when set, otherwise from the signed-in Firebase user when
- * `firebaseAuth` is configured. `null` is accepted alongside `undefined` so a
- * caller's own lookup (which may itself come back empty) can be passed
- * straight through without an extra check. 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));
+ * @param fn Receives the Drizzle handle
+ * @param uid Overrides the user ID for authenticated calls
  */
 export async function withUserDb(fn, uid) {
     const db = config.db;
@@ -206,59 +153,19 @@ export async function withUserDb(fn, uid) {
         return fn(await supabaseDb(resolved.supabase, token));
     }
     const userId = await resolveUserId(uid);
-    const client = await connectToPostgres(config, resolved.connectionString);
     const role = db.authenticatedRole ?? DEFAULT_ROLE;
-    try {
-        return await withSessionLock(async () => {
-            // No `db.transaction()`/BEGIN here on purpose: this client is shared
-            // across every concurrent caller in the isolate (see connection.ts),
-            // and a live Postgres transaction is session state — `BEGIN`,
-            // `SET LOCAL ROLE`, and `COMMIT`/`ROLLBACK` all apply to whichever
-            // statement runs next on the socket, not to `fn`'s call site. Two
-            // overlapping `withUserDb` calls each opening their own transaction
-            // interleaved their BEGIN/SET LOCAL/COMMIT on one socket — Postgres
-            // then rejected the interleaved statements ("already a transaction
-            // in progress", "no transaction in progress"), which is exactly the
-            // bug `withSessionLock` alone could not fully close. Session-scoped
-            // `set_config(..., true)` (`true` = for the rest of the session, not
-            // just a transaction) and a plain `set role` need no transaction to
-            // apply, and `withSessionLock` already keeps this whole block
-            // exclusive against every other caller, so atomicity is unaffected.
-            const rawClient = client;
-            await rawClient.query(`select set_config('request.jwt.claims', $1, false)`, [JSON.stringify({ sub: userId })]);
-            await rawClient.query(`set role "${role}"`);
-            const { drizzle } = await import('drizzle-orm/node-postgres');
-            const drizzleHandle = drizzle(client);
-            try {
-                return await fn(await postgresDb(drizzleHandle, rawClient));
-            }
-            finally {
-                // Always hand the shared socket back to the default role —
-                // otherwise the next caller (public or a different user) could
-                // inherit this request's elevated/authenticated role.
-                await rawClient.query('reset role');
-            }
-        });
-    }
-    finally {
-        disconnectPostgres(config);
-    }
+    return await withDbClient(config, async (client) => {
+        const rawClient = client;
+        await rawClient.query(`select set_config('request.jwt.claims', $1, false)`, [JSON.stringify({ sub: userId })]);
+        await rawClient.query(`set role "${role}"`);
+        const { drizzle } = await import('drizzle-orm/node-postgres');
+        const drizzleHandle = drizzle(client);
+        return await fn(await postgresDb(drizzleHandle, rawClient));
+    });
 }
 /**
  * Runs several statements atomically over `cfni_exec_batch`, backing
- * Supabase-mode `db.transaction()`. `build` does not execute its queries —
- * it **builds** them and returns the array; call `.toSQL()` on each Drizzle
- * query instead of `await`ing it (`await`ing throws immediately; see
- * {@link buildOnlyDb}). Every query is inlined and sent as one round trip:
- * the Postgres function runs them in order inside a single plpgsql call,
- * which is itself an implicit transaction, so a failure on any statement
- * rolls back every statement before it.
- *
- * @param supabase The `db.supabase` config block.
- * @param bearerToken The anon key or user JWT.
- * @param build Returns the queries to run, via `.toSQL()` — never executes them directly.
- * @returns One result per query, in the same order as `build`'s array.
- * @throws If `db.supabase.rawSql` is `false` — `cfni_exec_batch` needs `cfni_exec`, which is disabled too.
+ * Supabase-mode `db.transaction()`.
  */
 async function runTransaction(supabase, bearerToken, build) {
     if (supabase.rawSql === false) {

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

@@ -38,5 +38,5 @@
  */
 export { withPublicDb, withUserDb } from './context';
 export type { DrizzleDb, TransactionResult } from './context';
-export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
+export { withDbClient, connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
 export type { DbRoutingConfig } from '../types/types';

package/dist/src/db/index.js

@@ -37,4 +37,4 @@
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */
 export { withPublicDb, withUserDb } from './context';
-export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
+export { withDbClient, connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';

package/dist/src/types/types.d.ts

@@ -884,10 +884,12 @@ export interface DbRoutingConfig {
     /**
      * 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.
+     *
+     * @deprecated Ignored since 0.8.23. Every `withPublicDb`/`withUserDb` call
+     * now opens and closes its own client, so no connection survives a call to
+     * be kept open. `true` and `false` behave identically; the only difference
+     * is that `false` awaits the close instead of deferring it to
+     * `ctx.waitUntil`. Hyperdrive pools the server-side connection.
      */
     disconnectAfterRequest?: boolean;
     /**
@@ -902,7 +904,12 @@ export interface DbRoutingConfig {
      * to use a different auth source (or when `firebaseAuth` is absent).
      */
     getUserId?: () => Promise<string | null> | string | null;
-    /** Milliseconds `disconnectPostgres` waits for `client.end()` before giving up. Defaults to `2000`. */
+    /**
+     * Milliseconds `disconnectPostgres` waits for `client.end()` before giving up.
+     *
+     * @deprecated Ignored since 0.8.23. Client teardown is awaited or deferred
+     * to `ctx.waitUntil` without a timeout.
+     */
     disconnectTimeoutMs?: number;
     /**
      * Reaches Postgres through the Supabase Data API instead of a direct

package/llms.txt

@@ -53,11 +53,11 @@ Two transports, picked by which `db` fields are set — `pg`/`drizzle-orm`/`@sup
 
 - Direct Postgres (wins if configured): `db.connectionString` — Postgres connection string, or a sync/async function returning one (resolved on each connect). The function form is the way to read a value unavailable at module scope, e.g. a Cloudflare Hyperdrive binding: `connectionString: async () => (await getCloudflareContext({ async: true })).env.HYPERDRIVE.connectionString`. There is no separate `hyperdriveBinding` option.
 - Supabase Data API (used only when neither of the above is set): `db.supabase` — `{ url?, anonKey?, execFunction?, rawSql? }` where `url`/`anonKey` each accept a string or a sync/async function returning one, defaulting `url`/`anonKey` to `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`. Statements are translated to PostgREST REST calls first; unsupported statements fall back to `supabase/cfni_exec.sql` (a `security invoker` SQL-exec function) in your database — `cfni-db-codegen`/`cfni-db-install-exec` can install it for you (see below). No multi-statement transactions — each statement in a `withUserDb` callback is its own round-trip; `.transaction()` throws instead of running non-atomically. `rawSql: false` disables `cfni_exec` fallback, throwing an informative error when a query cannot be served over REST.
-- `db.disconnectAfterRequest` — direct-Postgres mode only: closes the pooled client once the last in-flight `withPublicDb`/`withUserDb` call of the request finishes. Defaults to `true`; set `false` to keep the connection open for the isolate's lifetime (holds a Hyperdrive slot between requests).
+- `db.disconnectAfterRequest` — deprecated, ignored since 0.8.23. Each `withPublicDb`/`withUserDb` call opens and closes its own client; Hyperdrive pools the server-side connection.
 - `db.authenticatedRole` — direct-Postgres mode only: Postgres role assumed inside `withUserDb`'s transaction. Defaults to `'authenticated'` (Supabase RLS convention).
 - `db.getUserId` — direct-Postgres mode only: resolves the user id injected as `request.jwt.claims->>'sub'` in `withUserDb`. Omit when `firebaseAuth` is configured — the uid is then taken automatically from the signed-in Firebase user via this package's own `getAuthUser()`.
 - `db.getAccessToken` — Supabase mode only: resolves the JWT sent as `Authorization: Bearer` in `withUserDb`, which is what makes PostgREST resolve `authenticated` and apply RLS. Omit when `firebaseAuth` is configured — the signed-in user's Firebase ID token is used automatically.
-- `db.disconnectTimeoutMs` — direct-Postgres mode only: ms `disconnectPostgres` waits for `client.end()` before giving up. Defaults to `2000`.
+- `db.disconnectTimeoutMs` — deprecated, ignored since 0.8.23. Teardown is awaited or deferred to `ctx.waitUntil` without a timeout.
 - `withPublicDb(fn)` — anonymous role. Direct-Postgres mode: the request's pooled connection, no transaction, no role switch. Supabase mode: the anon key as the PostgREST bearer token. Either way, no user id is attached — RLS keyed on `auth.jwt()` denies access.
 - `withUserDb(fn, uid?)` — signed-in-user role. Direct-Postgres mode: a transaction with `set_config('request.jwt.claims', ...)` + `set local role`, `uid` resolution order explicit arg → `db.getUserId()` → Firebase auth uid → throws. Supabase mode: identity rides on the JWT from `db.getAccessToken`/Firebase instead (`uid` param is ignored), no transaction wraps the call.
 - `./dbHelpers` functions are plain Drizzle `sql`-building utilities with no config dependency — usable standalone.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cloudflare-next-intl",
-	"version": "0.8.22",
+	"version": "0.8.24",
 	"description": "Optimized Next Intl Package Special for App Router and Cloudflare",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",