cloudflare-next-intl 0.8.4 → 0.8.6

package/README.md

@@ -464,12 +464,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 +482,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 +523,94 @@ 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 without `cfni_exec`
+
+If you don't want to install `cfni_exec` at all, set `db.supabase.rawSql:
+false`. `withPublicDb`/`withUserDb` then throw immediately in Supabase mode
+instead of failing later against PostgREST, and you reach Postgres instead
+through a set of helpers that call `@supabase/supabase-js`'s `.from()`/`.rpc()`
+API directly — the same REST surface the Supabase client itself uses, no raw
+SQL involved:
+
+```typescript
+import { supabaseSelect, supabaseInsert, supabaseUpdate, supabaseDelete, supabaseUpsert, supabaseRpc } from "cloudflare-next-intl/db";
+
+const { rows } = await supabaseSelect("bonds", {
+    where: { active: true, yield: ["gte", 5] },
+    orderBy: { column: "yield", ascending: false },
+    limit: 10,
+});
+
+await supabaseInsert("bonds", { name: "10Y", yield: 4.2 });
+await supabaseUpsert("bonds", { id: 1, yield: 4.5 }, { onConflict: "id" });
+await supabaseUpdate("bonds", { yield: 4.3 }, { where: { id: 1 } });
+await supabaseDelete("bonds", { where: { id: 1 } });
+
+// Anything a plain select/insert/update/delete/upsert can't express (joins,
+// aggregates, custom logic) — write a Postgres function, `grant execute` to
+// `anon`/`authenticated`, and call it by name. No cfni_exec needed for this
+// either, since PostgREST always supports calling a named function you own.
+const total = await supabaseRpc("total_yield", { bond_ids: [1, 2, 3] });
+```
+
+Each has a `*AsUser` counterpart (`supabaseSelectAsUser`,
+`supabaseInsertAsUser`, `supabaseUpsertAsUser`, `supabaseUpdateAsUser`,
+`supabaseDeleteAsUser`, `supabaseRpcAsUser`) that authenticates as the
+signed-in user instead of anon — same token resolution as `withUserDb`
+(`db.getAccessToken`, or the signed-in Firebase user's ID token), so RLS
+applies the same way.
+
+`supabaseSelect`/`supabaseSelectAsUser` accept:
+
+- `columns` — PostgREST column-list syntax. Defaults to `'*'`. Supports an
+  embedded resource for a foreign-key join in one round-trip, e.g.
+  `'*, author(name)'`.
+- `where` — filters, ANDed together. A bare value (`{ id: 5 }`) is shorthand
+  for `eq`; use `{ column: [operator, value] }` for any other operator —
+  `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `likeAllOf`, `likeAnyOf`, `ilike`,
+  `ilikeAllOf`, `ilikeAnyOf`, `regexMatch`, `regexIMatch`, `is`,
+  `isDistinct`, `in`, `contains`, `containedBy`, `overlaps`, `rangeGt`,
+  `rangeGte`, `rangeLt`, `rangeLte`, or `rangeAdjacent` — or
+  `{ column: ['not', operator, value] }` to negate any of them. This is the
+  complete operator set `@supabase/supabase-js`'s `.from()` builder exposes
+  (it *is* a `postgrest-js` builder — there's no separate, larger "Supabase
+  client" query surface on top of it).
+- `match` — shorthand for several `eq` filters at once (`{ status: 'active',
+  archived: false }`). ANDed with `where`.
+- `or` — a raw PostgREST `or()` filter string (e.g.
+  `'age.gt.18,status.eq.active'`) for filters spanning multiple columns in
+  one clause; ANDed with `where`/`match`.
+- `textSearch` — `{ column, query, type?, config? }` for full-text search via
+  PostgREST's `@@` operators.
+- `orderBy` — one `{ column, ascending?, nullsFirst? }`, or an array for
+  multiple `order by` clauses.
+- `limit` / `range` — row limit, or a `[from, to]` PostgREST pagination range.
+- `single` / `maybeSingle` — resolve to one row (erroring if there isn't
+  exactly one), or one row or `null` (erroring if there's more than one).
+- `count` — also return the total matching row count (`'exact'`, `'planned'`,
+  or `'estimated'`).
+
+`supabaseUpdate`/`supabaseDelete` (and their `*AsUser` forms) accept `where`/
+`match`/`or` the same way, and require at least one of them — an unfiltered
+update/delete would otherwise touch every row.
+
+This mode trades capability for not needing `cfni_exec`: everything the
+Supabase JS client itself can express against a single table (including an
+embedded-resource join) works; multi-table joins beyond that, aggregates,
+window functions, and raw SQL of any kind do not — those need `cfni_exec`, or
+a Postgres function called via `supabaseRpc`.
 
 Two query wrappers, both from `cloudflare-next-intl/db`. Choose by who is
 allowed to see the rows:
@@ -551,12 +645,94 @@ 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`)
+
+The package ships a `cfni-db-codegen` binary that regenerates Drizzle models by
+introspecting a live Postgres with `drizzle-kit pull`, patches drizzle-kit's
+bare function-call defaults into raw-SQL-wrapped ones, and writes a
+`manifest.json` next to the schema so `--check` can fail CI when the DDL
+changed without regenerating.
+
+```bash
+npx cfni-db-codegen
+npx cfni-db-codegen --check
+```
+
+| Flag | Env | Default |
+| --- | --- | --- |
+| `--ddl-dir=` | `CFNI_DB_DDL_DIR` | `supabase/data-base` |
+| `--out-dir=` | `CFNI_DB_OUT_DIR` | `src/shared/db/generated` |
+| `--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
+same schema into several projects in one run (`CFNI_DB_OUT_DIR` accepts a
+comma-separated list too). The database is introspected once and the identical
+schema plus manifest is written to every target; `--check` verifies all of
+them and fails naming the first one that is stale.
+
+```bash
+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`
 
@@ -581,6 +757,35 @@ 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`.
+
 ## License
 
 MIT

package/bin/db_codegen.mjs

@@ -1,6 +1,11 @@
 #!/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
+// comma-separated list too).
 //
 // Needs a reachable Postgres to introspect — any Postgres, not specifically
 // a Docker one. Set CODEGEN_DATABASE_URL to point at whichever you have:
@@ -9,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());
 
@@ -55,9 +71,10 @@ function ddlHash() {
 const hash = ddlHash();
 
 if (paths.check) {
-    const previous = existsSync(paths.manifest) ? JSON.parse(readFileSync(paths.manifest, "utf8")).ddlHash : null;
-    if (previous !== hash) {
-        console.error(`❌ ${relative(process.cwd(), paths.ddlDir)} changed without regenerating models. Run: npm run db:codegen`);
+    for (const target of paths.targets) {
+        const previous = existsSync(target.manifest) ? JSON.parse(readFileSync(target.manifest, "utf8")).ddlHash : null;
+        if (previous === hash) continue;
+        console.error(`❌ ${relative(process.cwd(), paths.ddlDir)} changed without regenerating models in ${relative(process.cwd(), target.outDir)}. Run: npm run db:codegen`);
         process.exit(1);
     }
     console.log(`✅ Drizzle models are in sync with ${relative(process.cwd(), paths.ddlDir)}`);
@@ -69,7 +86,6 @@ await assertReachable(paths.dbUrl);
 rmSync(paths.pullDir, { recursive: true, force: true });
 execFileSync('npx', ['drizzle-kit', 'pull', ...(paths.drizzleConfig ? [`--config=${paths.drizzleConfig}`] : [])], { stdio: 'inherit' });
 
-mkdirSync(paths.outDir, { recursive: true });
 const pulled = join(paths.pullDir, "schema.ts");
 if (!existsSync(pulled)) {
     console.error(`❌ drizzle-kit pull produced no schema at ${pulled}`);
@@ -102,9 +118,43 @@ 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"));
-writeFileSync(paths.outFile, banner + pulledSource);
+const pulledSource = retargetDrizzleImports(
+    patchBareFunctionCallDefaults(readFileSync(pulled, "utf8")),
+);
 rmSync(paths.pullDir, { recursive: true, force: true });
-writeFileSync(paths.manifest, `${JSON.stringify({ ddlHash: hash }, null, 2)}\n`);
-console.log(`✅ Generated ${relative(process.cwd(), paths.outFile)}`);
+for (const target of paths.targets) {
+    mkdirSync(target.outDir, { recursive: true });
+    writeFileSync(target.outFile, banner + pulledSource);
+    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

@@ -1,5 +1,11 @@
+export interface CodegenTarget {
+    outDir: string;
+    outFile: string;
+    manifest: string;
+}
 export interface CodegenPaths {
     ddlDir: string;
+    targets: CodegenTarget[];
     outDir: string;
     outFile: string;
     pullDir: string;
@@ -8,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,18 @@
-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));
+}
+function list(value) {
+    return value.split(',').map((part) => part.trim()).filter(Boolean);
+}
 function flag(argv, name) {
     const prefix = `--${name}=`;
     const hit = argv.find((arg) => arg.startsWith(prefix));
@@ -15,11 +24,27 @@ function abs(cwd, value) {
 /** Resolves every codegen path from flags, then env, then the documented defaults. */
 export default function resolveCodegenPaths(argv, env, cwd) {
     const ddlDir = abs(cwd, flag(argv, 'ddl-dir') ?? env.CFNI_DB_DDL_DIR ?? DEFAULT_DDL_DIR);
-    const outDir = abs(cwd, flag(argv, 'out-dir') ?? env.CFNI_DB_OUT_DIR ?? DEFAULT_OUT_DIR);
+    const outDirArgs = flags(argv, 'out-dir').flatMap(list);
+    const outDirs = (outDirArgs.length > 0
+        ? outDirArgs
+        : list(env.CFNI_DB_OUT_DIR ?? '')).map((dir) => abs(cwd, dir));
+    if (outDirs.length === 0)
+        outDirs.push(abs(cwd, DEFAULT_OUT_DIR));
+    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) => ({
+            outDir: dir,
+            outFile: join(dir, outFileName),
+            manifest: join(dir, 'manifest.json'),
+        })),
         outDir,
         outFile: join(outDir, outFileName),
         pullDir: resolve(outDir, '..', '.drizzle-pull'),
@@ -28,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

@@ -27,13 +27,31 @@ async function resolveUserId(uid) {
     throw new Error('db: withUserDb could not resolve a user id. Pass one explicitly, set ' +
         '`db.getUserId`, or configure `firebaseAuth` so the signed-in Firebase uid is used.');
 }
+function requireRawSql(supabase) {
+    if (supabase.rawSql === false) {
+        throw new Error('db: withPublicDb/withUserDb need `cfni_exec` to run SQL in Supabase mode, but ' +
+            '`db.supabase.rawSql` is set to `false`. Use `supabaseSelect`/`supabaseInsert`/' +
+            '`supabaseUpdate`/`supabaseDelete` instead, which call the Supabase REST API directly.');
+    }
+}
 /**
  * Builds a Drizzle handle backed by PostgREST. `bearerToken` decides the role
  * Postgres sees: the anon key for public access, a user JWT for `withUserDb`.
  */
 async function supabaseDb(supabase, bearerToken) {
+    requireRawSql(supabase);
     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/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.
  *