cloudflare-next-intl 0.8.8 → 0.8.9

package/README.md

@@ -558,9 +558,11 @@ 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.
+- **Per-statement transactions in `withUserDb`/`withPublicDb`.** Each
+  statement in one of their callbacks is its own round-trip, so it is its own
+  implicit transaction — `.transaction()` throws there instead of running
+  non-atomically. Reach for `withUserTransaction`/`withPublicTransaction`
+  (below) when you need more than one statement to succeed or fail together.
 - **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
@@ -574,8 +576,55 @@ with or without `RETURNING` (including `ON CONFLICT ... DO UPDATE` via
 writable CTEs (`with x as (update ... returning ...) select ... from x`).
 Every value round-trips through Postgres' own text representation, not JSON,
 so arrays/`numeric`/timestamps/`bytea` decode the same way they do in
-connection-string mode. Not supported: multi-statement transactions (each
-call is its own PostgREST round-trip — see above).
+connection-string mode. `withUserDb`/`withPublicDb` do not run multiple
+statements atomically (each call is its own PostgREST round-trip) — see
+[Multi-statement transactions](#multi-statement-transactions-withusertransaction-withpublictransaction)
+below for the API that does.
+
+#### Multi-statement transactions (`withUserTransaction`/`withPublicTransaction`)
+
+`withUserDb`/`withPublicDb` cannot provide atomicity across statements in
+Supabase mode — there is no shared session for `.transaction()` to open, so
+it throws there instead of silently running non-atomically. Reach for
+`withUserTransaction`/`withPublicTransaction` (also from
+`cloudflare-next-intl/db`) whenever a write needs more than one statement to
+succeed or fail together.
+
+They take a `build` callback that **builds** queries instead of executing
+them — call `.toSQL()` on each Drizzle query and return the array, rather
+than `await`ing the query directly:
+
+```typescript
+import { withUserTransaction } from "cloudflare-next-intl/db";
+import { invitations, contractorAccessGrants } from "@/shared/db/generated/schema";
+
+const [invitationResult, grantResult] = await withUserTransaction((db) => [
+    db.insert(invitations).values({ email: "a@b.com" }).returning().toSQL(),
+    db.insert(contractorAccessGrants).values({ propertyId: 1 }).toSQL(),
+]);
+```
+
+Every query in the array is rendered and sent to Postgres as **one**
+`cfni_exec_batch` call: the function runs each statement in order inside a
+single plpgsql call, which is itself an implicit transaction, so a failure on
+any statement rolls back every statement that ran before it in the same
+batch. `cfni_exec_batch` ships alongside `cfni_exec` in the same
+`supabase/cfni_exec.sql` file (installed the same way — see
+[Schema codegen](#schema-codegen-cfni-db-codegen) below) and is available
+whenever `cfni_exec` is: there is no separate config flag, and
+`db.supabase.rawSql: false` turns off both.
+
+Each result is the same `{ rows, rowCount }` shape a single `cfni_exec` call
+returns — decode rows the same way you would from `db.execute(sql\`...\`)`.
+
+`await`ing a query directly inside `build` (instead of calling `.toSQL()`)
+throws immediately, naming the mistake, rather than hanging or silently
+running that one statement outside the batch with no atomicity.
+
+In connection-string mode, use `withUserDb`/`withPublicDb`'s own
+`.transaction()` instead — it already provides real atomicity there, so
+`withUserTransaction`/`withPublicTransaction` throw rather than duplicate
+that path.
 
 #### Supabase mode and REST translation
 
@@ -617,7 +666,8 @@ await withPublicDb((db) => db.delete(bonds).where(eq(bonds.id, 1)));
 | `RETURNING` clauses | Supported | Supported |
 | Operators: `=`, `<>`, `!=`, `>`, `>=`, `<`, `<=`, `like`, `ilike`, `is [not] null`, `[not] in`, `is [not] distinct from`, `~`, `~*`, `@>`, `<@`, `&&`, `>>`, `<<`, `&>`, `&<`, `-|-`, `@@` | Supported | Supported |
 | Multi-table joins, CTEs, non-count aggregates, `GROUP BY`, `UNION`, `DISTINCT`, raw SQL | Not supported by REST | Supported |
-| Multi-statement transactions | Not supported | Not supported (Postgres connection only) |
+| Multi-statement transactions in `withUserDb`/`withPublicDb` | Not supported | Not supported (each call is its own round-trip) |
+| Multi-statement transactions via `withUserTransaction`/`withPublicTransaction` | N/A — batch-only API | Supported (`cfni_exec_batch`, one round-trip) |
 
 #### Enforcing single API via ESLint (`cloudflare-next-intl/dbEslint`)
 
@@ -632,8 +682,9 @@ export default [
 ];
 ```
 
-Two query wrappers, both from `cloudflare-next-intl/db`. Choose by who is
-allowed to see the rows:
+Four query wrappers, all from `cloudflare-next-intl/db`. Choose by who is
+allowed to see the rows, then by whether you need more than one statement to
+succeed or fail together:
 
 - `withPublicDb(fn)` — runs `fn` as the anonymous role: a pooled connection
   with no transaction/role switch in connection-string mode, or the anon key
@@ -650,6 +701,13 @@ allowed to see the rows:
   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.
+- `withPublicTransaction(build)` / `withUserTransaction(build)` — same role
+  split as above, but for a write that needs more than one statement to
+  succeed or fail together. See
+  [Multi-statement transactions](#multi-statement-transactions-withusertransaction-withpublictransaction)
+  above — `build` returns built (`.toSQL()`) queries rather than executing
+  them, and these two are currently Supabase-mode only (connection-string
+  mode already has real atomicity via `withUserDb`/`withPublicDb`).
 
 ```typescript
 // anywhere on the server
@@ -703,7 +761,9 @@ npx cfni-db-codegen --check
 | `--db-url=` | `CODEGEN_DATABASE_URL` | `postgresql://postgres:postgres@127.0.0.1:54322/postgres` |
 | `--drizzle-config=` | `CFNI_DB_DRIZZLE_CONFIG` | none |
 | `--rpc-dir=` | `CFNI_DB_RPC_DIR` | sibling of `--ddl-dir`, e.g. `supabase/rpc` |
+| `--rpc-file-name=` | `CFNI_DB_RPC_FILE_NAME` | `cfni_exec.sql` |
 | `--tests-dir=` | `CFNI_DB_TESTS_DIR` | sibling of `--ddl-dir`, e.g. `supabase/tests` |
+| `--tests-file-name=` | `CFNI_DB_TESTS_FILE_NAME` | `cfni_exec.sql` |
 | `--force` | `CFNI_DB_FORCE_EXEC=true` | off |
 | `--skip-exec` | `CFNI_DB_SKIP_EXEC=true` | off |
 | `--check` | — | off |
@@ -718,15 +778,21 @@ them and fails naming the first one that is stale.
 npx cfni-db-codegen --out-dir=src/shared/db/generated --out-dir=../other-app/src/db/generated
 ```
 
-##### Keeping `cfni_exec.sql` in sync (`--rpc-dir`/`--tests-dir`/`--force`/`--skip-exec`)
+##### Keeping `cfni_exec.sql` in sync (`--rpc-dir`/`--rpc-file-name`/`--tests-dir`/`--tests-file-name`/`--force`/`--skip-exec`)
 
 After a successful (non-`--check`) run, `cfni-db-codegen` also copies
 `supabase/cfni_exec.sql` and its pgTAP test file (see
 [Testing `cfni_exec.sql` itself](#testing-cfni_execsql-itself) below) into
 your project — `--rpc-dir`/`--tests-dir` (defaulting to sibling folders of
-`--ddl-dir`, so `rpc`/`tests` next to `data-base`). This keeps a project that
-enables Supabase mode's raw-SQL path always holding the current version of the
-function, without a manual copy-paste step.
+`--ddl-dir`, so `rpc`/`tests` next to `data-base`), each named `cfni_exec.sql`
+by default. This keeps a project that enables Supabase mode's raw-SQL path
+always holding the current version of the function, without a manual
+copy-paste step. Since the file now ships both `cfni_exec` and
+`cfni_exec_batch` (see
+[Multi-statement transactions](#multi-statement-transactions-withusertransaction-withpublictransaction)
+above), pass `--rpc-file-name=`/`--tests-file-name=` (or
+`CFNI_DB_RPC_FILE_NAME`/`CFNI_DB_TESTS_FILE_NAME`) if you'd rather install it
+under a name that reflects that, e.g. `cfni_exec_and_batch.sql`.
 
 This step is gated on `db.supabase.rawSql` (see
 [Supabase mode without `cfni_exec`](#supabase-mode-without-cfni_exec)):
@@ -747,7 +813,8 @@ set `CFNI_DB_SKIP_EXEC=true`) to turn this whole step off, independent of
 
 To run only this step — no `drizzle-kit pull`, no live Postgres needed — use
 the standalone `cfni-db-install-exec` binary instead, which accepts the same
-`--rpc-dir`/`--tests-dir`/`--force` flags:
+`--rpc-dir`/`--rpc-file-name`/`--tests-dir`/`--tests-file-name`/`--force`
+flags:
 
 ```bash
 npx cfni-db-install-exec

package/bin/db_codegen.mjs

@@ -1,7 +1,13 @@
 #!/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=…]
-//                        [--rpc-dir=…] [--tests-dir=…] [--force] [--skip-exec]
+//                        [--rpc-dir=…] [--rpc-file-name=…] [--tests-dir=…] [--tests-file-name=…] [--force] [--skip-exec]
+//
+// --rpc-file-name/--tests-file-name (also CFNI_DB_RPC_FILE_NAME/
+// CFNI_DB_TESTS_FILE_NAME) rename the installed cfni_exec.sql/its pgTAP test
+// file in the consuming project — e.g. if a project prefers a name that
+// reflects the file now ships both `cfni_exec` and `cfni_exec_batch`. Default
+// to `cfni_exec.sql` for both, unchanged from before.
 //
 // --out-dir may be repeated, or given a comma-separated list, to generate the
 // same schema into several projects at once (CFNI_DB_OUT_DIR accepts a

package/bin/db_install_exec.mjs

@@ -4,7 +4,7 @@
 // generation, exposed standalone for when you only want this and nothing
 // else (no drizzle-kit pull, no live Postgres needed).
 //
-// Usage: cfni-db-install-exec [--rpc-dir=…] [--tests-dir=…] [--force]
+// Usage: cfni-db-install-exec [--rpc-dir=…] [--rpc-file-name=…] [--tests-dir=…] [--tests-file-name=…] [--force]
 //
 // Gated on the project's `db.supabase.rawSql` (read from `next.config.*`'s
 // `@intl-config` alias) the same way cfni-db-codegen's step is — pass

package/dist/src/db/codegen_paths.js

@@ -38,6 +38,8 @@ export default function resolveCodegenPaths(argv, env, cwd) {
     const supabaseRoot = dirname(ddlDir);
     const rpcDir = abs(cwd, flag(argv, 'rpc-dir') ?? env.CFNI_DB_RPC_DIR ?? join(supabaseRoot, 'rpc'));
     const testsDir = abs(cwd, flag(argv, 'tests-dir') ?? env.CFNI_DB_TESTS_DIR ?? join(supabaseRoot, 'tests'));
+    const rpcFileName = flag(argv, 'rpc-file-name') ?? env.CFNI_DB_RPC_FILE_NAME ?? DEFAULT_RPC_FILE_NAME;
+    const testsFileName = flag(argv, 'tests-file-name') ?? env.CFNI_DB_TESTS_FILE_NAME ?? DEFAULT_TESTS_FILE_NAME;
     return {
         ddlDir,
         targets: outDirs.map((dir) => ({
@@ -54,9 +56,9 @@ export default function resolveCodegenPaths(argv, env, cwd) {
         timeoutMs: Number(env.CODEGEN_CONNECT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS,
         drizzleConfig: drizzleConfig === null ? null : abs(cwd, drizzleConfig),
         rpcDir,
-        rpcFile: join(rpcDir, DEFAULT_RPC_FILE_NAME),
+        rpcFile: join(rpcDir, rpcFileName),
         testsDir,
-        testsFile: join(testsDir, DEFAULT_TESTS_FILE_NAME),
+        testsFile: join(testsDir, testsFileName),
         force: argv.includes('--force') || env.CFNI_DB_FORCE_EXEC === 'true',
         skipExec: argv.includes('--skip-exec') || env.CFNI_DB_SKIP_EXEC === 'true',
     };

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

@@ -1,4 +1,6 @@
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { Query } from 'drizzle-orm';
+import type { ExecResult } from './supabase_transport';
 /**
  * The Drizzle handle passed to `withPublicDb`/`withUserDb` callbacks. Use it
  * exactly like a normal Drizzle database (`db.select().from(table)`); it is
@@ -55,3 +57,45 @@ export declare function withPublicDb<T>(fn: (db: DrizzleDb) => Promise<T>): Prom
  * const mine = await withUserDb((db) => db.select().from(orders));
  */
 export declare function withUserDb<T>(fn: (db: DrizzleDb) => Promise<T>, uid?: string): Promise<T>;
+/** One statement's `{rows, rowCount}` result from a `withUserTransaction`/`withPublicTransaction` batch. */
+export type { ExecResult as TransactionResult } from './supabase_transport';
+/**
+ * Runs several statements atomically as the **anonymous** role.
+ *
+ * See {@link runTransaction} for the batching mechanism. `build` must not
+ * execute its queries — return their `.toSQL()` form instead.
+ *
+ * @param build Returns the queries to run, in order.
+ * @returns One `{rows, rowCount}` result per query, in the same order.
+ * @throws If `db` is not set, if this isn't Supabase mode (connection-string
+ * mode already has real transactions via `withPublicDb`), or if any
+ * statement in the batch fails — the whole batch is then rolled back.
+ *
+ * @example
+ * const [inserted] = await withPublicTransaction((db) => [
+ *     db.insert(logEntries).values({ event: 'visit' }).toSQL(),
+ * ]);
+ */
+export declare function withPublicTransaction(build: (db: DrizzleDb) => Promise<Query[]> | Query[]): Promise<ExecResult[]>;
+/**
+ * Runs several statements atomically as the **signed-in user**.
+ *
+ * See {@link runTransaction} for the batching mechanism and
+ * {@link withUserDb} for how the caller's identity is resolved. In Supabase
+ * mode this is the wrapper to reach for whenever a user-owned write needs
+ * more than one statement to succeed or fail together — `withUserDb` alone
+ * cannot provide that there.
+ *
+ * @param build Returns the queries to run, in order. Do not execute them —
+ * call `.toSQL()` on each and return the array.
+ * @returns One `{rows, rowCount}` result per query, in the same order.
+ * @throws If `db` is not set, if no access token can be resolved, if this
+ * isn't Supabase mode, or if any statement in the batch fails — the whole
+ * batch is then rolled back.
+ *
+ * @example
+ * const [invitation] = await withUserTransaction((db) => [
+ *     db.insert(invitations).values({ email }).returning().toSQL(),
+ * ]);
+ */
+export declare function withUserTransaction(build: (db: DrizzleDb) => Promise<Query[]> | Query[]): Promise<ExecResult[]>;

package/dist/src/db/context.js

@@ -5,6 +5,7 @@ import resolveDbMode from './resolve_mode';
 import resolveSupabaseEndpoint from './supabase_config';
 import createSupabaseTransport from './supabase_transport';
 import resolveAccessToken from './access_token';
+import runTransactionBatch from './transaction_batch';
 const DEFAULT_ROLE = 'authenticated';
 /**
  * Resolves the user id for `withUserDb`, trying, in order: the explicit `uid`
@@ -45,6 +46,23 @@ async function supabaseDb(supabase, bearerToken) {
         },
     });
 }
+/**
+ * Builds a Drizzle handle with no working transport, for
+ * `withUserTransaction`/`withPublicTransaction` callbacks in Supabase mode.
+ * Query builders' `.toSQL()` never touches the session, so this is safe to
+ * hand out purely for building statements — but `await`ing a query directly
+ * (instead of collecting its `.toSQL()` output) throws immediately here
+ * instead of hanging or silently running outside the batch.
+ */
+function buildOnlyDb() {
+    const throwIfExecuted = () => {
+        throw new Error('db: this Drizzle handle is for building statements only — call `.toSQL()` on each ' +
+            'query and return the array, do not `await`/execute it directly. Awaiting a query ' +
+            'inside a withUserTransaction/withPublicTransaction callback runs it outside the ' +
+            'batch, with no atomicity, which is exactly what these wrappers exist to prevent.');
+    };
+    return new Proxy({}, { get: () => throwIfExecuted });
+}
 /**
  * Runs a query as the **anonymous** role: no transaction, no role switch, no
  * user identity attached. Use this for data any visitor may read.
@@ -133,3 +151,95 @@ export async function withUserDb(fn, uid) {
         disconnectPostgres(config);
     }
 }
+/**
+ * Runs several statements atomically, whichever transport mode is active.
+ *
+ * `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 here; see {@link buildOnlyDb}). This is
+ * only reachable in Supabase mode — connection-string mode already has real
+ * atomicity through `withUserDb`/`withPublicDb`'s own `.transaction()`, so
+ * `withUserTransaction`/`withPublicTransaction` throw there instead of
+ * duplicating that path. In Supabase mode, where `.transaction()` cannot
+ * open a session, every query is inlined and sent as one `cfni_exec_batch`
+ * call: 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 db The already-resolved `db` config.
+ * @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.
+ */
+function requireSupabaseTransactionMode(db) {
+    if (resolveDbMode(db) !== 'supabase') {
+        throw new Error('db: withUserTransaction/withPublicTransaction only run their Supabase-mode batch path ' +
+            'right now. In connection-string mode, use withUserDb/withPublicDb\'s own `.transaction()` ' +
+            '— it already provides real atomicity there.');
+    }
+    const supabase = db.supabase;
+    if (supabase.rawSql === false) {
+        throw new Error('db: withUserTransaction/withPublicTransaction need `cfni_exec_batch`, which runs through ' +
+            '`cfni_exec` — both are unavailable while `db.supabase.rawSql` is `false`. Install ' +
+            'cfni_exec.sql and drop `rawSql: false`, or use `db.connectionString` for a direct ' +
+            'Postgres connection instead.');
+    }
+    return supabase;
+}
+async function runTransaction(supabase, bearerToken, build) {
+    const queries = await build(buildOnlyDb());
+    const batchQueries = queries.map((query) => ({ sql: query.sql, params: query.params }));
+    return runTransactionBatch(supabase, bearerToken, batchQueries);
+}
+/**
+ * Runs several statements atomically as the **anonymous** role.
+ *
+ * See {@link runTransaction} for the batching mechanism. `build` must not
+ * execute its queries — return their `.toSQL()` form instead.
+ *
+ * @param build Returns the queries to run, in order.
+ * @returns One `{rows, rowCount}` result per query, in the same order.
+ * @throws If `db` is not set, if this isn't Supabase mode (connection-string
+ * mode already has real transactions via `withPublicDb`), or if any
+ * statement in the batch fails — the whole batch is then rolled back.
+ *
+ * @example
+ * const [inserted] = await withPublicTransaction((db) => [
+ *     db.insert(logEntries).values({ event: 'visit' }).toSQL(),
+ * ]);
+ */
+export async function withPublicTransaction(build) {
+    const db = config.db;
+    requireDbConfig(db);
+    const supabase = requireSupabaseTransactionMode(db);
+    const { anonKey } = await resolveSupabaseEndpoint(supabase);
+    return runTransaction(supabase, anonKey, build);
+}
+/**
+ * Runs several statements atomically as the **signed-in user**.
+ *
+ * See {@link runTransaction} for the batching mechanism and
+ * {@link withUserDb} for how the caller's identity is resolved. In Supabase
+ * mode this is the wrapper to reach for whenever a user-owned write needs
+ * more than one statement to succeed or fail together — `withUserDb` alone
+ * cannot provide that there.
+ *
+ * @param build Returns the queries to run, in order. Do not execute them —
+ * call `.toSQL()` on each and return the array.
+ * @returns One `{rows, rowCount}` result per query, in the same order.
+ * @throws If `db` is not set, if no access token can be resolved, if this
+ * isn't Supabase mode, or if any statement in the batch fails — the whole
+ * batch is then rolled back.
+ *
+ * @example
+ * const [invitation] = await withUserTransaction((db) => [
+ *     db.insert(invitations).values({ email }).returning().toSQL(),
+ * ]);
+ */
+export async function withUserTransaction(build) {
+    const db = config.db;
+    requireDbConfig(db);
+    const supabase = requireSupabaseTransactionMode(db);
+    const token = await resolveAccessToken(config);
+    return runTransaction(supabase, token, build);
+}

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

@@ -7,6 +7,11 @@
  * - {@link withPublicDb} — anonymous role, for data any visitor may read.
  * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
  *
+ * Need more than one statement to succeed or fail together?
+ * - {@link withPublicTransaction} / {@link withUserTransaction} — build
+ *   queries with `.toSQL()` instead of executing them; every statement then
+ *   runs atomically, whichever transport mode is active.
+ *
  * Two transports reach Postgres behind that same Drizzle query API, chosen by
  * `resolveDbMode` from which `db` config fields are set: `connectionString`
  * for a direct connection (wins if both are configured), or `supabase` for
@@ -18,12 +23,14 @@
  * statement is first translated into `@supabase/supabase-js` `.from()` calls;
  * anything PostgREST cannot express falls back to `cfni_exec`, and if
  * `db.supabase.rawSql` is `false` the call throws naming the construct that
- * needs raw SQL. `.transaction()` is never available in Supabase mode.
+ * needs raw SQL. `withPublicDb`/`withUserDb`'s `.transaction()` is never
+ * available in Supabase mode — reach for `withPublicTransaction`/
+ * `withUserTransaction` there instead.
  *
  * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */
-export { withPublicDb, withUserDb } from './context';
-export type { DrizzleDb } from './context';
+export { withPublicDb, withUserDb, withPublicTransaction, withUserTransaction } from './context';
+export type { DrizzleDb, TransactionResult } from './context';
 export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
 export type { DbRoutingConfig } from '../types/types';

package/dist/src/db/index.js

@@ -7,6 +7,11 @@
  * - {@link withPublicDb} — anonymous role, for data any visitor may read.
  * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
  *
+ * Need more than one statement to succeed or fail together?
+ * - {@link withPublicTransaction} / {@link withUserTransaction} — build
+ *   queries with `.toSQL()` instead of executing them; every statement then
+ *   runs atomically, whichever transport mode is active.
+ *
  * Two transports reach Postgres behind that same Drizzle query API, chosen by
  * `resolveDbMode` from which `db` config fields are set: `connectionString`
  * for a direct connection (wins if both are configured), or `supabase` for
@@ -18,10 +23,12 @@
  * statement is first translated into `@supabase/supabase-js` `.from()` calls;
  * anything PostgREST cannot express falls back to `cfni_exec`, and if
  * `db.supabase.rawSql` is `false` the call throws naming the construct that
- * needs raw SQL. `.transaction()` is never available in Supabase mode.
+ * needs raw SQL. `withPublicDb`/`withUserDb`'s `.transaction()` is never
+ * available in Supabase mode — reach for `withPublicTransaction`/
+ * `withUserTransaction` there instead.
  *
  * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */
-export { withPublicDb, withUserDb } from './context';
+export { withPublicDb, withUserDb, withPublicTransaction, withUserTransaction } from './context';
 export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';

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

@@ -1,4 +1,24 @@
 import type { SupabaseDbConfig } from '../types/types';
+export interface SupabaseRpcError {
+    message: string;
+    code?: string;
+}
+export interface ExecResult {
+    rows: unknown[];
+    rowCount: number | null;
+}
+/**
+ * `cfni_exec` returns each row as a Postgres composite-literal string (see
+ * {@link parseComposite}), so the JSON-decoded `data.rows` array here is a
+ * `string[]`, not already the `(string | null)[][]` `pg-proxy` expects —
+ * that positional-array shape is what this reconstructs.
+ *
+ * Exported for {@link ../transaction_batch}, which decodes each element of
+ * `cfni_exec_batch`'s result array the same way this decodes a single
+ * `cfni_exec` result — the two functions return one `{rows, rowCount}` shape
+ * per statement either way.
+ */
+export declare function parseExecResult(data: unknown): ExecResult;
 /**
  * The executor shape `drizzle-orm/pg-proxy` calls with each generated
  * statement. Declared structurally so this file never imports `drizzle-orm`.
@@ -30,3 +50,8 @@ export type SupabaseRemoteCallback = (sql: string, params: unknown[], method: 'a
  * @returns A callback suitable for `drizzle-orm/pg-proxy`'s `drizzle()`.
  */
 export default function createSupabaseTransport(supabase: SupabaseDbConfig, bearerToken: string): SupabaseRemoteCallback;
+/**
+ * Exported for {@link ../transaction_batch}, which reports `cfni_exec_batch`
+ * RPC failures the same way this reports `cfni_exec` failures.
+ */
+export declare function describeFailure(error: SupabaseRpcError, execFunction: string): string;

package/dist/src/db/supabase_transport.js

@@ -10,8 +10,13 @@ const DEFAULT_EXEC_FUNCTION = 'cfni_exec';
  * {@link parseComposite}), so the JSON-decoded `data.rows` array here is a
  * `string[]`, not already the `(string | null)[][]` `pg-proxy` expects —
  * that positional-array shape is what this reconstructs.
+ *
+ * Exported for {@link ../transaction_batch}, which decodes each element of
+ * `cfni_exec_batch`'s result array the same way this decodes a single
+ * `cfni_exec` result — the two functions return one `{rows, rowCount}` shape
+ * per statement either way.
  */
-function parseExecResult(data) {
+export function parseExecResult(data) {
     if (Array.isArray(data))
         return { rows: data.map(parseRow), rowCount: null };
     if (data && typeof data === 'object' && 'rows' in data) {
@@ -77,7 +82,11 @@ function unsupportedMessage(error, execFunction) {
         `Install the ${execFunction} function from supabase/cfni_exec.sql and drop \`rawSql: false\`, ` +
         'or use `db.connectionString` for a direct Postgres connection.');
 }
-function describeFailure(error, execFunction) {
+/**
+ * Exported for {@link ../transaction_batch}, which reports `cfni_exec_batch`
+ * RPC failures the same way this reports `cfni_exec` failures.
+ */
+export function describeFailure(error, execFunction) {
     // PGRST202 is PostgREST's "no such function" — by far the most likely
     // first-run failure, so point at the install step instead of the raw code.
     if (error.code === 'PGRST202') {

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

@@ -0,0 +1,31 @@
+import type { SupabaseDbConfig } from '../types/types';
+import { type ExecResult } from './supabase_transport';
+/** One statement to run inside a batch: Drizzle's `.toSQL()` output. */
+export interface BatchQuery {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * Sends every query in `queries` to `cfni_exec_batch` as one PostgREST round
+ * trip. The Postgres function runs them in order inside a single plpgsql
+ * call — itself an implicit transaction — so a failure on any statement
+ * rolls back every statement that ran before it in the same batch, giving
+ * Supabase-mode callers the atomicity `.transaction()` cannot provide there
+ * (see `context.ts`'s `supabaseDb`).
+ *
+ * Each query is rendered with {@link inlineParams} exactly like a normal
+ * `cfni_exec` call, since `cfni_exec_batch` takes pre-rendered statement
+ * text the same way `cfni_exec` does — neither function binds parameters
+ * itself.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @param bearerToken Token resolved as the caller's identity — the anon key
+ * for {@link ../context.withPublicTransaction}, a user JWT for
+ * {@link ../context.withUserTransaction}.
+ * @param queries The statements to run, in order. An empty array is a no-op
+ * that still makes the round trip, matching `cfni_exec_batch(array[]::text[])`.
+ * @returns One `{rows, rowCount}` result per query, in the same order.
+ * @throws If the batch RPC itself fails to reach Postgres, or if any
+ * statement in the batch fails — the whole batch is rolled back either way.
+ */
+export default function runTransactionBatch(supabase: SupabaseDbConfig, bearerToken: string, queries: BatchQuery[]): Promise<ExecResult[]>;

package/dist/src/db/transaction_batch.js

@@ -0,0 +1,45 @@
+import createRestClient from './rest_client';
+import inlineParams from './inline_params';
+import { parseExecResult, describeFailure } from './supabase_transport';
+/**
+ * Fixed, unlike `cfni_exec`'s `execFunction` — `cfni_exec_batch` ships in the
+ * same `supabase/cfni_exec.sql` file and is always available whenever
+ * `cfni_exec` is (there is no separate config for it; `rawSql: false` turns
+ * off both, checked by `context.ts` before this is ever called).
+ */
+const BATCH_FUNCTION = 'cfni_exec_batch';
+/**
+ * Sends every query in `queries` to `cfni_exec_batch` as one PostgREST round
+ * trip. The Postgres function runs them in order inside a single plpgsql
+ * call — itself an implicit transaction — so a failure on any statement
+ * rolls back every statement that ran before it in the same batch, giving
+ * Supabase-mode callers the atomicity `.transaction()` cannot provide there
+ * (see `context.ts`'s `supabaseDb`).
+ *
+ * Each query is rendered with {@link inlineParams} exactly like a normal
+ * `cfni_exec` call, since `cfni_exec_batch` takes pre-rendered statement
+ * text the same way `cfni_exec` does — neither function binds parameters
+ * itself.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @param bearerToken Token resolved as the caller's identity — the anon key
+ * for {@link ../context.withPublicTransaction}, a user JWT for
+ * {@link ../context.withUserTransaction}.
+ * @param queries The statements to run, in order. An empty array is a no-op
+ * that still makes the round trip, matching `cfni_exec_batch(array[]::text[])`.
+ * @returns One `{rows, rowCount}` result per query, in the same order.
+ * @throws If the batch RPC itself fails to reach Postgres, or if any
+ * statement in the batch fails — the whole batch is rolled back either way.
+ */
+export default async function runTransactionBatch(supabase, bearerToken, queries) {
+    const getClient = createRestClient(supabase, bearerToken);
+    const client = await getClient();
+    const statements = queries.map((query) => inlineParams(query.sql, query.params));
+    const { data, error } = await client.rpc(BATCH_FUNCTION, { statements });
+    if (error)
+        throw new Error(describeFailure(error, BATCH_FUNCTION));
+    if (!Array.isArray(data)) {
+        throw new Error(`db: ${BATCH_FUNCTION} returned a non-array result — is it installed from the version of supabase/cfni_exec.sql shipped with this package?`);
+    }
+    return data.map(parseExecResult);
+}

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

@@ -850,6 +850,12 @@ export interface SupabaseDbConfig {
      * conflict`, `returning`) and throw for anything else — joins,
      * aggregates, CTEs, transactions — naming the construct that needs raw
      * SQL. Defaults to `true`.
+     *
+     * Also gates `withUserTransaction`/`withPublicTransaction`: their
+     * `cfni_exec_batch` function ships in the same `supabase/cfni_exec.sql`
+     * file and needs `cfni_exec` itself to run each statement, so batching
+     * is on whenever this is (there is no separate flag for it) and throws
+     * the same install-or-use-`connectionString` error when this is `false`.
      */
     rawSql?: boolean;
 }

package/package.json

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

package/supabase/cfni_exec.sql

@@ -139,12 +139,53 @@ begin
 end;
 $$;
 
+-- Runs several statements as one atomic unit: `execute`d one at a time via
+-- `cfni_exec`, all inside this single function body, so a failure on any
+-- statement rolls back everything the batch already did — a plpgsql function
+-- call is itself an implicit transaction, which is what makes this atomic
+-- even though `pg-proxy` (the Supabase-mode transport) can open no
+-- transaction of its own: each statement it sends is normally its own
+-- independent PostgREST round-trip with no shared session. This is the
+-- explicit batch API for that gap — see `withUserTransaction`/
+-- `withPublicTransaction` on the TypeScript side, which render every query
+-- in the callback with `.toSQL()` up front (nothing executes until the
+-- batch is sent) and pass the resulting array here as one call.
+--
+-- Returns a jsonb array with one `cfni_exec`-shaped `{rows, rowCount}` result
+-- per input statement, in the same order — so the caller can read each
+-- statement's own result the way it would outside a batch.
+--
+-- SECURITY INVOKER for the same reason as `cfni_exec`: the whole batch runs
+-- with the caller's own privileges, so RLS applies per statement exactly as
+-- it would if each ran on its own.
+create or replace function public.cfni_exec_batch(statements text[])
+returns jsonb
+language plpgsql
+security invoker
+set search_path = public
+as $$
+declare
+    results jsonb := '[]'::jsonb;
+    statement text;
+begin
+    foreach statement in array statements loop
+        results := results || jsonb_build_array(public.cfni_exec(statement));
+    end loop;
+    return results;
+end;
+$$;
+
 revoke all on function public.cfni_exec(text) from public;
 grant execute on function public.cfni_exec(text) to authenticated;
 -- Grant to anon only if your app calls withPublicDb:
 grant execute on function public.cfni_exec(text) to anon;
 grant execute on function public.cfni_exec(text) to service_role;
 
+revoke all on function public.cfni_exec_batch(text[]) from public;
+grant execute on function public.cfni_exec_batch(text[]) to authenticated;
+grant execute on function public.cfni_exec_batch(text[]) to anon;
+grant execute on function public.cfni_exec_batch(text[]) to service_role;
+
 revoke all on function public.cfni_top_level_verb(text) from public;
 grant execute on function public.cfni_top_level_verb(text) to authenticated;
 grant execute on function public.cfni_top_level_verb(text) to anon;

package/supabase/tests/cfni_exec.sql

@@ -5,7 +5,7 @@
 -- checks the SQL function itself and its RLS interaction directly in
 -- Postgres, without going through the transport/JS parsing layer.
 begin;
-select plan(20);
+select plan(26);
 
 do $$
 begin
@@ -146,5 +146,48 @@ select is(
 );
 reset role;
 
+-- cfni_exec_batch
+
+select is(
+    cfni_exec_batch(array[
+        'insert into cfni_test_a (id, name) values (30, ''batch1'') returning id, name',
+        'insert into cfni_test_a (id, name) values (31, ''batch2'') returning id, name'
+    ]),
+    '[{"rows": ["(30,batch1)"], "rowCount": 1}, {"rows": ["(31,batch2)"], "rowCount": 1}]'::jsonb,
+    'batch runs every statement and returns one cfni_exec-shaped result per statement, in order'
+);
+
+select is(
+    (select count(*) from cfni_test_a where id in (30, 31)),
+    2::bigint,
+    'both batched inserts committed'
+);
+
+select throws_ok(
+    $$select cfni_exec_batch(array[
+        'insert into cfni_test_a (id, name) values (40, ''ok'')',
+        'insert into cfni_test_a (id, name) values (invalid syntax'
+    ])$$,
+    null, null,
+    'a later statement failing raises out of the batch call'
+);
+
+select is(
+    (select count(*) from cfni_test_a where id = 40),
+    0::bigint,
+    'an earlier statement in a failed batch is rolled back — the batch is atomic'
+);
+
+select is(pg_proc.prosecdef, false, 'cfni_exec_batch is security invoker, not security definer')
+from pg_proc where proname = 'cfni_exec_batch';
+
+set role anon;
+select is(
+    cfni_exec_batch(array['select * from cfni_test_a where id = 30']),
+    '[{"rows": [], "rowCount": 0}]'::jsonb,
+    'cfni_exec_batch applies RLS per statement just like cfni_exec — anon sees no rows here'
+);
+reset role;
+
 select * from finish();
 rollback;