cloudflare-next-intl 0.8.5 → 0.8.7

package/README.md

@@ -74,6 +74,48 @@ export default nextConfig;
 If this alias is missing, any import from `cloudflare-next-intl` throws an
 error naming the missing `@intl-config` alias at startup.
 
+### 2b. Deploying to Cloudflare Workers: alias it in `wrangler.toml` too
+
+`wrangler deploy`/`wrangler dev` bundle the Worker with their own esbuild
+pass, separate from Next's webpack/Turbopack build — the `next.config`
+alias above doesn't apply to it. Without this, `wrangler deploy` fails with
+`Could not resolve "@intl-config"`. Path is relative to `wrangler.toml`.
+
+```toml
+# wrangler.toml
+[alias]
+"@intl-config" = "./src/i18n/intl_config.ts"
+```
+
+Put `[alias]` after all top-level scalar keys (`name`, `main`,
+`compatibility_date`, `compatibility_flags`, etc.) and before any other
+`[table]`/`[[array_of_tables]]` header — TOML assigns every key that follows
+a table header to that table until the next header, so an `[alias]` placed
+earlier silently swallows the keys meant for the top level.
+
+**In a monorepo, give every Worker its own alias target — never point two
+Workers' `[alias]` at the same shared config file.** Declaring `[alias]`
+makes Wrangler eagerly resolve and bundle whatever it points to, even if
+nothing in that Worker's own code imports `@intl-config`. If a second,
+smaller Worker (e.g. a cron/background worker) points its alias at the main
+app's config file, it inherits that file's whole import graph — every
+package the main app's config touches (Firebase, a DB client, `zod`, etc.)
+must then be a dependency of the small Worker too, or the build fails with
+`Could not resolve "<package>"` for packages that Worker never actually
+uses. Give it its own minimal file instead:
+
+```typescript
+// backend/src/i18n/intl_config.ts — deliberately minimal, not the main
+// app's config: aliasing it there would drag in every dependency that
+// config touches, even ones this Worker never imports.
+import { setIntlConfig } from "cloudflare-next-intl";
+
+export default setIntlConfig({
+    locales: ["en"],
+    defaultLocale: "en",
+});
+```
+
 ### 3. Wire up the middleware
 
 ```typescript
@@ -464,12 +506,15 @@ 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.
+`supabase db push`, a migration, or the SQL editor) — the file starts with a
+`drop function if exists` so re-running it to upgrade is always safe. It is
+`security invoker`, so statements execute with the caller's own privileges and
+RLS applies exactly as it does over the REST API; **never** change this to
+`security definer` — that would let any caller (anon included) bypass RLS
+through the function, regardless of the role PostgREST resolved them as.
+`@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):
 
@@ -479,6 +524,10 @@ bundles any of them.
   Defaults to `NEXT_PUBLIC_SUPABASE_ANON_KEY`. Never put a service-role key
   here.
 - `execFunction` — name of the exec function. Defaults to `'cfni_exec'`.
+- `rawSql` — whether `withPublicDb`/`withUserDb` may run arbitrary SQL
+  through `cfni_exec`. Defaults to `true`. Set `false` if you don't want to
+  (or can't) install `cfni_exec` — see
+  [Supabase mode without `cfni_exec`](#supabase-mode-without-cfni_exec) below.
 
 Any of `connectionString`, `supabase.url`, and `supabase.anonKey` may be a
 function instead of a string, resolved (and awaited) at use time rather than
@@ -516,7 +565,72 @@ user's Firebase ID token is used automatically.
   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;`
+  anon grant: `revoke execute on function public.cfni_exec(text) from anon;`
+
+**What `cfni_exec` actually supports:** plain `SELECT` (including joins with
+duplicate column names, CTEs, window functions), `INSERT`/`UPDATE`/`DELETE`
+with or without `RETURNING` (including `ON CONFLICT ... DO UPDATE` via
+`excluded`/`onConflictSet` from `cloudflare-next-intl/dbHelpers`), and
+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).
+
+#### Supabase mode and REST translation
+
+You write the exact same Drizzle code with `withPublicDb`/`withUserDb` in Supabase mode as in connection-string mode. Behind the scenes, the transport translates each statement into `@supabase/supabase-js` `.from()` PostgREST calls whenever possible:
+
+```typescript
+import { withPublicDb, withUserDb } from "cloudflare-next-intl/db";
+import { eq, gte, desc } from "cloudflare-next-intl/dbHelpers";
+
+// Automatically translated to PostgREST REST calls:
+const rows = await withPublicDb((db) =>
+    db.select({ id: bonds.id, name: bonds.name, yield: bonds.yield })
+        .from(bonds)
+        .where(gte(bonds.yield, 5))
+        .orderBy(desc(bonds.yield))
+        .limit(10)
+);
+
+await withPublicDb((db) => db.insert(bonds).values({ name: "10Y", yield: 4.2 }));
+await withPublicDb((db) =>
+    db.insert(bonds)
+        .values({ id: 1, name: "10Y", yield: 4.5 })
+        .onConflictDoUpdate({ target: bonds.id, set: { yield: 4.5 } })
+);
+await withPublicDb((db) => db.update(bonds).set({ yield: 4.3 }).where(eq(bonds.id, 1)));
+await withPublicDb((db) => db.delete(bonds).where(eq(bonds.id, 1)));
+```
+
+**Transport routing:**
+1. **REST translation first:** Single-table `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `on conflict`, and `returning` are mapped to `@supabase/supabase-js` `.from()` calls.
+2. **`cfni_exec` fallback:** Statements PostgREST cannot express (joins, CTEs, complex subqueries) fall back to the `cfni_exec` SQL-exec function.
+3. **`rawSql: false` mode:** If `db.supabase.rawSql: false` is configured (when `cfni_exec` is not installed), any statement requiring raw SQL throws an error explaining the limitation and how to resolve it.
+
+| Operation | REST API | `cfni_exec` fallback |
+| --- | --- | --- |
+| Single-table `SELECT` (projections, `count(*)`, `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`) | Supported | Used if untranslatable |
+| Single-table `INSERT` / `UPDATE` / `DELETE` | Supported | Used if untranslatable |
+| `ON CONFLICT DO NOTHING / UPDATE` | Supported | Supported |
+| `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) |
+
+#### Enforcing single API via ESLint (`cloudflare-next-intl/dbEslint`)
+
+To prevent application code from bypassing the single `db` API with direct driver imports (`@supabase/supabase-js`, `pg`, `postgres`, or deep `dist/` paths), spread the shipped flat-config fragment in your `eslint.config.js`:
+
+```typescript
+import dbEslint from "cloudflare-next-intl/dbEslint";
+
+export default [
+    ...dbEslint,
+    // your other configs...
+];
+```
 
 Two query wrappers, both from `cloudflare-next-intl/db`. Choose by who is
 allowed to see the rows:
@@ -551,12 +665,22 @@ helpers (`excluded`, `onConflictSet`, `ago`, `currentDate`, `windowCount`,
 upsert/window/lateral-join queries without dropping to raw SQL, plus a
 re-export of `drizzle-orm`'s common query-building primitives (`eq`, `and`,
 `or`, `asc`, `desc`, `gte`, `gt`, `lte`, `lt`, `isNull`, `isNotNull`, `count`,
-`sum`, `max`, `min`, `sql`) — so code that only builds queries against the
+`sum`, `max`, `min`, `sql`, `inArray`, `notInArray`, `ne`, `like`, `ilike`,
+`between`, `not`, `exists`) — so code that only builds queries against the
 `DrizzleDb` handle from `withPublicDb`/`withUserDb` doesn't need its own
-`drizzle-orm` import for these. Anything not listed here (schema definitions,
-`drizzle-orm/pg-core` column builders, relations) still comes from
-`drizzle-orm` directly — this package re-exports the query-operator surface
-only, not the whole library.
+`drizzle-orm` import for these.
+
+For schema definitions, `cloudflare-next-intl/dbSchema` re-exports the
+`drizzle-orm/pg-core` table and column builders (`pgTable`, `varchar`,
+`integer`, `index`, `pgEnum`, …) alongside the `sql` tag, so generated schema
+files can import from this package too:
+
+```ts
+import { pgTable, varchar, integer } from 'cloudflare-next-intl/dbSchema';
+```
+
+Relations and any other advanced Drizzle surface still come from `drizzle-orm`
+directly.
 
 #### Schema codegen (`cfni-db-codegen`)
 
@@ -578,6 +702,10 @@ npx cfni-db-codegen --check
 | `--out-file=` | `CFNI_DB_OUT_FILE` | `schema.ts` |
 | `--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` |
+| `--tests-dir=` | `CFNI_DB_TESTS_DIR` | sibling of `--ddl-dir`, e.g. `supabase/tests` |
+| `--force` | `CFNI_DB_FORCE_EXEC=true` | off |
+| `--skip-exec` | `CFNI_DB_SKIP_EXEC=true` | off |
 | `--check` | — | off |
 
 `--out-dir` may be repeated, or given a comma-separated list, to generate the
@@ -590,6 +718,42 @@ 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`)
+
+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.
+
+This step is gated on `db.supabase.rawSql` (see
+[Supabase mode without `cfni_exec`](#supabase-mode-without-cfni_exec)):
+codegen reads your `next.config.*`'s `@intl-config` alias, opens the intl
+config file it points at, and looks for a literal `rawSql: true`/`rawSql:
+false`. If it's explicitly `false`, the copy is skipped entirely — no
+`supabase/rpc`/`supabase/tests` folders are created. If it can't be
+determined (no `next.config.*` found, no alias, or `rawSql` isn't a plain
+`true`/`false` literal in the source), a warning is printed and codegen
+assumes `true`, matching `withPublicDb`/`withUserDb`'s own default.
+
+An existing target file that already matches is left untouched; one that
+exists with **different** content (a customization, or a stale version) is
+skipped with a warning rather than silently overwritten — pass `--force` (or
+set `CFNI_DB_FORCE_EXEC=true`) to overwrite it anyway. Pass `--skip-exec` (or
+set `CFNI_DB_SKIP_EXEC=true`) to turn this whole step off, independent of
+`rawSql`.
+
+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:
+
+```bash
+npx cfni-db-install-exec
+npx cfni-db-install-exec --force
+```
+
 #### Testing code that calls `withPublicDb`/`withUserDb`
 
 `cloudflare-next-intl/dbTesting` exports a fake `DrizzleDb` so repository/unit
@@ -613,6 +777,45 @@ just "select was called" but "the second select's `.where(...)` argument was
 X". Handles `db.$with(name).as(builder)` / `db.with(...).select(...)`
 CTE-style queries the same way the real Drizzle client does.
 
+#### Testing `cfni_exec.sql` itself
+
+Because `cfni_exec.sql` runs real SQL — statement classification (SELECT vs.
+DML, writable CTEs), literal-encoding of parameters, and RLS behavior — it's
+tested two ways in this package's own repo, and both are shipped so you can
+reuse them against your own database rather than trusting the function
+untested:
+
+- `supabase/tests/cfni_exec.sql` — a [pgTAP](https://pgtap.org/) suite,
+  runnable with `supabase test db` (or `pg_prove`) once both this file and
+  `cfni_exec.sql` are installed in a database. It checks the SQL function
+  directly: every statement shape `cfni_exec` classifies (plain `SELECT`,
+  `INSERT`/`UPDATE`/`DELETE` with and without `RETURNING`, writable CTEs,
+  `ON CONFLICT DO UPDATE`), value fidelity (arrays/booleans/`numeric`/`NULL`
+  round-tripping through pg's own text form, not JSON), and that
+  `SECURITY INVOKER` really does make RLS apply per-role (`anon` vs.
+  `authenticated` see different rows under the same policy). `cfni-db-codegen`
+  and `cfni-db-install-exec` copy this file into your project the same way
+  they copy `cfni_exec.sql` itself, so it's there to run against your own
+  schema whenever you want the same confidence.
+- `src/db/cfni_exec.integration.test.ts` (in this package's source, not
+  something copied into your project) — a Vitest suite that drives the exact
+  same scenarios through the real TypeScript transport path:
+  `inlineParams` → `cfni_exec` → `parseComposite`, over an actual Postgres
+  connection. It's skipped automatically unless `CFNI_TEST_DATABASE_URL` is
+  set (e.g. to a throwaway `docker run -d -e POSTGRES_PASSWORD=postgres -p
+  55432:5432 postgres:15`), so it never runs — and never needs a database —
+  during a normal `npm test`.
+
+## AI Agent Setup & Conventions
+
+When using AI coding assistants (Claude Code, Cursor, Copilot, Antigravity) with `cloudflare-next-intl`:
+
+- **One Database API**: Always use `withPublicDb` or `withUserDb` from `cloudflare-next-intl/db`. Never import `@supabase/supabase-js`, `pg`, or `postgres` in application code.
+- **Drizzle Schema & Helpers**: Always import schema definitions from `cloudflare-next-intl/dbSchema` (`pgTable`, `text`, `timestamp`, `uuid`, etc.) and query operators from `cloudflare-next-intl/dbHelpers` (`eq`, `and`, `or`, `inArray`, `count`, etc.).
+- **Lint Enforcement**: Spread `...dbEslint` from `cloudflare-next-intl/dbEslint` in `eslint.config.js` to catch accidental driver imports.
+- **Reference Document**: Direct AI tools to `llms.txt` in this package for concise rules and subpath exports.
+
 ## License
 
 MIT
+

package/bin/db_codegen.mjs

@@ -1,6 +1,7 @@
 #!/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]
 //
 // --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
@@ -13,12 +14,23 @@
 // 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.
+//
+// After a successful (non-`--check`) run, also installs `cfni_exec.sql` (and
+// its pgTAP test file) into `--rpc-dir`/`--tests-dir` (default siblings of
+// `--ddl-dir`, e.g. `supabase/rpc`/`supabase/tests`) — but only when the
+// project's `db.supabase.rawSql` isn't explicitly `false` (read from
+// `next.config.*`'s `@intl-config` alias; a warning is printed if it can't
+// be determined). An existing, differing file is left alone unless
+// `--force`/CFNI_DB_FORCE_EXEC=true is set. Pass `--skip-exec`/
+// CFNI_DB_SKIP_EXEC=true to turn this step off entirely, or use the
+// standalone `cfni-db-install-exec` command to run only this step.
 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';
+import { runInstallExecStep } from './install_exec_step.mjs';
 
 const paths = resolveCodegenPaths(process.argv.slice(2), process.env, process.cwd());
 
@@ -106,8 +118,37 @@ function patchBareFunctionCallDefaults(source) {
     );
 }
 
+// drizzle-kit emits imports from `drizzle-orm/pg-core` and `drizzle-orm`.
+// Point them at this package's re-exports so consuming projects don't need a
+// direct `drizzle-orm` dependency just to load their generated schema.
+function retargetDrizzleImports(source) {
+    const coreMatch = source.match(
+        /^import \{([^}]*)\} from "drizzle-orm\/pg-core";?$/m,
+    );
+    const rootMatch = source.match(/^import \{([^}]*)\} from "drizzle-orm";?$/m);
+    if (!coreMatch && !rootMatch) return source;
+
+    const names = [...(coreMatch ? [coreMatch[1]] : []), ...(rootMatch ? [rootMatch[1]] : [])]
+        .flatMap((group) => group.split(","))
+        .map((name) => name.trim())
+        .filter(Boolean);
+    const merged = `import { ${[...new Set(names)].join(", ")} } from "cloudflare-next-intl/dbSchema"`;
+
+    let seen = false;
+    return source.replace(
+        /^import \{[^}]*\} from "drizzle-orm(?:\/pg-core)?";?$/gm,
+        () => {
+            if (seen) return "";
+            seen = true;
+            return merged;
+        },
+    ).replace(/\n{3,}/g, "\n\n");
+}
+
 const banner = `// GENERATED by cfni-db-codegen from ${relative(process.cwd(), paths.ddlDir)} — do not edit.\n`;
-const pulledSource = patchBareFunctionCallDefaults(readFileSync(pulled, "utf8"));
+const pulledSource = retargetDrizzleImports(
+    patchBareFunctionCallDefaults(readFileSync(pulled, "utf8")),
+);
 rmSync(paths.pullDir, { recursive: true, force: true });
 for (const target of paths.targets) {
     mkdirSync(target.outDir, { recursive: true });
@@ -115,3 +156,5 @@ for (const target of paths.targets) {
     writeFileSync(target.manifest, `${JSON.stringify({ ddlHash: hash }, null, 2)}\n`);
     console.log(`✅ Generated ${relative(process.cwd(), target.outFile)}`);
 }
+
+runInstallExecStep(paths, process.cwd());

package/bin/db_install_exec.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Installs cfni_exec.sql (and its pgTAP test file) into the consuming
+// project — the same step cfni-db-codegen runs after a successful
+// 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]
+//
+// 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
+// `--force`/CFNI_DB_FORCE_EXEC=true to overwrite an existing, differing file.
+import resolveCodegenPaths from '../dist/src/db/codegen_paths.js';
+import { runInstallExecStep } from './install_exec_step.mjs';
+
+const paths = resolveCodegenPaths(process.argv.slice(2), process.env, process.cwd());
+runInstallExecStep(paths, process.cwd());

package/bin/install_exec_step.mjs

@@ -0,0 +1,39 @@
+// Shared by cfni-db-codegen and cfni-db-install-exec: copies cfni_exec.sql
+// (and its pgTAP test file) from this package's own `supabase/` folder into
+// the consuming project, gated on the project's `db.supabase.rawSql` setting.
+import { join } from 'node:path';
+import resolveRawSql from '../dist/src/db/resolve_raw_sql.js';
+import { installExecFile } from '../dist/src/db/install_exec.js';
+
+const PACKAGE_ROOT = new URL('..', import.meta.url).pathname;
+
+/**
+ * @param {import('../dist/src/db/codegen_paths.js').CodegenPaths} paths
+ * @param {string} cwd
+ */
+export function runInstallExecStep(paths, cwd) {
+    if (paths.skipExec) {
+        console.log('ℹ️  Skipping cfni_exec install — --skip-exec passed.');
+        return;
+    }
+
+    const rawSql = resolveRawSql(cwd);
+    if (rawSql.status === 'false') {
+        console.log(`ℹ️  Skipping cfni_exec install — db.supabase.rawSql is false (${rawSql.reason}).`);
+        return;
+    }
+    if (rawSql.status === 'unknown') {
+        console.warn(`⚠️  Could not determine db.supabase.rawSql (${rawSql.reason}) — assuming true and installing cfni_exec. Pass --skip-exec, or set db.supabase.rawSql: false, to turn this off.`);
+    }
+
+    const files = [
+        { sourcePath: join(PACKAGE_ROOT, 'supabase/cfni_exec.sql'), targetPath: paths.rpcFile },
+        { sourcePath: join(PACKAGE_ROOT, 'supabase/tests/cfni_exec.sql'), targetPath: paths.testsFile },
+    ];
+
+    for (const file of files) {
+        const result = installExecFile(file, paths.force);
+        const icon = { created: '✅', updated: '✅', unchanged: 'ℹ️', 'skipped-differs': '⚠️', 'skipped-missing-source': '⚠️' }[result.action];
+        console.log(`${icon} ${result.targetPath}: ${result.message}`);
+    }
+}

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

@@ -14,6 +14,12 @@ export interface CodegenPaths {
     check: boolean;
     timeoutMs: number;
     drizzleConfig: string | null;
+    rpcDir: string;
+    rpcFile: string;
+    testsDir: string;
+    testsFile: string;
+    force: boolean;
+    skipExec: boolean;
 }
 /** 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

@@ -1,9 +1,11 @@
-import { isAbsolute, join, resolve } from 'node:path';
+import { dirname, 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;
+const DEFAULT_RPC_FILE_NAME = 'cfni_exec.sql';
+const DEFAULT_TESTS_FILE_NAME = 'cfni_exec.sql';
 function flags(argv, name) {
     const prefix = `--${name}=`;
     return argv.filter((arg) => arg.startsWith(prefix)).map((arg) => arg.slice(prefix.length));
@@ -31,6 +33,11 @@ export default function resolveCodegenPaths(argv, env, cwd) {
     const outDir = outDirs[0];
     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;
+    // Sibling of ddlDir (default `supabase/data-base` → `supabase`), matching
+    // where `cfni_exec.sql` ships in this package's own `supabase/` folder.
+    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'));
     return {
         ddlDir,
         targets: outDirs.map((dir) => ({
@@ -46,5 +53,11 @@ export default function resolveCodegenPaths(argv, env, cwd) {
         check: argv.includes('--check'),
         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),
+        testsDir,
+        testsFile: join(testsDir, DEFAULT_TESTS_FILE_NAME),
+        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.js

@@ -33,7 +33,17 @@ async function resolveUserId(uid) {
  */
 async function supabaseDb(supabase, bearerToken) {
     const { drizzle } = await import('drizzle-orm/pg-proxy');
-    return drizzle(createSupabaseTransport(supabase, bearerToken));
+    const db = drizzle(createSupabaseTransport(supabase, bearerToken));
+    return Object.assign(db, {
+        // pg-proxy has no session to open a real transaction over — every
+        // statement is its own PostgREST round-trip — so failing loudly here
+        // beats silently running the callback non-atomically.
+        transaction() {
+            throw new Error('db: transactions are not available in Supabase mode. Each statement runs as its ' +
+                'own PostgREST round-trip with no shared session, so `.transaction()` cannot provide ' +
+                'atomicity. Use connection-string mode (`db.connectionString`) if you need it.');
+        },
+    });
 }
 /**
  * Runs a query as the **anonymous** role: no transaction, no role switch, no

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

@@ -0,0 +1,10 @@
+/**
+ * Serialises a JS value to a Postgres literal, mirroring how `pg` sends
+ * values over the wire so an inlined literal type-infers the same way a
+ * bound parameter would.
+ *
+ * Used to substitute `$n` placeholders client-side in Supabase mode, where
+ * `cfni_exec` takes a single already-complete statement — see
+ * {@link inlineParams}.
+ */
+export default function encodeParam(value: unknown): string;

package/dist/src/db/encode_param.js

@@ -0,0 +1,60 @@
+/**
+ * Serialises a JS value to a Postgres literal, mirroring how `pg` sends
+ * values over the wire so an inlined literal type-infers the same way a
+ * bound parameter would.
+ *
+ * Used to substitute `$n` placeholders client-side in Supabase mode, where
+ * `cfni_exec` takes a single already-complete statement — see
+ * {@link inlineParams}.
+ */
+export default function encodeParam(value) {
+    if (value === null || value === undefined)
+        return 'NULL';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (Number.isNaN(value))
+            return "'NaN'";
+        if (value === Infinity)
+            return "'Infinity'";
+        if (value === -Infinity)
+            return "'-Infinity'";
+        return String(value);
+    }
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value instanceof Date)
+        return quoteLiteral(value.toISOString());
+    if (value instanceof Uint8Array)
+        return quoteLiteral(`\\x${bytesToHex(value)}`);
+    if (Array.isArray(value))
+        return quoteLiteral(encodeArray(value));
+    if (typeof value === 'string')
+        return quoteLiteral(value);
+    // Plain objects (jsonb columns) — pg sends these JSON-stringified.
+    return quoteLiteral(JSON.stringify(value));
+}
+function quoteLiteral(text) {
+    return `'${text.replace(/'/g, "''")}'`;
+}
+function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** Encodes a JS array as a Postgres array literal body, e.g. `{1,2,"a,b"}`. */
+function encodeArray(value) {
+    const items = value.map((item) => {
+        if (item === null || item === undefined)
+            return 'NULL';
+        if (Array.isArray(item))
+            return encodeArray(item);
+        if (item instanceof Date)
+            return quoteArrayElement(item.toISOString());
+        if (typeof item === 'number' || typeof item === 'bigint' || typeof item === 'boolean')
+            return String(item);
+        return quoteArrayElement(typeof item === 'string' ? item : JSON.stringify(item));
+    });
+    return `{${items.join(',')}}`;
+}
+function quoteArrayElement(text) {
+    return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * A flat-config fragment consumers can spread into their `eslint.config.*` to
+ * keep application code on the single `db` API.
+ *
+ * The runtime already refuses to give out a raw client, but an import of
+ * `@supabase/supabase-js` or a deep `dist/` path is how that guarantee gets
+ * bypassed in practice, so it is worth failing at lint time where the fix is
+ * cheap.
+ */
+declare const dbEslintConfig: {
+    rules: {
+        'no-restricted-imports': (string | {
+            paths: {
+                name: string;
+                message: string;
+            }[];
+            patterns: string[];
+        })[];
+    };
+}[];
+export default dbEslintConfig;

package/dist/src/db/eslint_config.js

@@ -0,0 +1,29 @@
+const MESSAGE = 'Query the database through `withPublicDb`/`withUserDb` from cloudflare-next-intl/db. ' +
+    'The package picks the transport (direct Postgres, cfni_exec, or PostgREST) for you.';
+/**
+ * A flat-config fragment consumers can spread into their `eslint.config.*` to
+ * keep application code on the single `db` API.
+ *
+ * The runtime already refuses to give out a raw client, but an import of
+ * `@supabase/supabase-js` or a deep `dist/` path is how that guarantee gets
+ * bypassed in practice, so it is worth failing at lint time where the fix is
+ * cheap.
+ */
+const dbEslintConfig = [
+    {
+        rules: {
+            'no-restricted-imports': [
+                'error',
+                {
+                    paths: [
+                        { name: '@supabase/supabase-js', message: MESSAGE },
+                        { name: 'pg', message: MESSAGE },
+                        { name: 'postgres', message: MESSAGE },
+                    ],
+                    patterns: ['cloudflare-next-intl/dist/*'],
+                },
+            ],
+        },
+    },
+];
+export default dbEslintConfig;

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

@@ -1,11 +1,11 @@
-import { sql, eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, type SQL, type Table } from 'drizzle-orm';
+import { sql, eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, inArray, notInArray, ne, like, ilike, between, not, exists, type SQL, type Table } from 'drizzle-orm';
 /**
  * Re-exported `drizzle-orm` query-building primitives, so code that only
  * calls `withPublicDb`/`withUserDb` and builds queries against the returned
  * `DrizzleDb` never needs its own `drizzle-orm` import for common predicates,
  * ordering, and aggregates.
  */
-export { eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, sql };
+export { eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, sql, inArray, notInArray, ne, like, ilike, between, not, exists };
 /**
  * Type-safe helper returning `excluded.<db_column_name>` SQL expressions for a Drizzle table.
  *

package/dist/src/db/helpers.js

@@ -1,11 +1,11 @@
-import { getTableColumns, getTableName, sql, eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, } from 'drizzle-orm';
+import { getTableColumns, getTableName, sql, eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, inArray, notInArray, ne, like, ilike, between, not, exists, } from 'drizzle-orm';
 /**
  * Re-exported `drizzle-orm` query-building primitives, so code that only
  * calls `withPublicDb`/`withUserDb` and builds queries against the returned
  * `DrizzleDb` never needs its own `drizzle-orm` import for common predicates,
  * ordering, and aggregates.
  */
-export { eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, sql };
+export { eq, and, or, asc, desc, gte, gt, lte, lt, isNull, isNotNull, count, sum, max, min, sql, inArray, notInArray, ne, like, ilike, between, not, exists };
 /**
  * Type-safe helper returning `excluded.<db_column_name>` SQL expressions for a Drizzle table.
  *

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

@@ -14,6 +14,12 @@
  * load through dynamic `import()` inside these functions, so an app that
  * never calls a `db` export never bundles any of them.
  *
+ * You write the same Drizzle code either way. In Supabase mode each generated
+ * 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.
+ *
  * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
  * the separate `cloudflare-next-intl/dbHelpers` entry point.
  */