@supacloud/db 0.7.1 → 0.8.0

package/README.md

@@ -1,5 +1,52 @@
 # @supacloud/db
 
+## Drizzle, Read Queries and SQL Impact
+
+Use `defineDrizzleDatabaseModule` and `createDrizzleCommandDatabase` from
+`@supacloud/db/drizzle`, or `createBunDrizzleCommandDatabase` from
+`@supacloud/db/drizzle-bun`. Authorization, business writes, receipts and audit
+share one transaction connection. Do not use the outer pool for command writes
+or retain `transaction.db` after the transaction. The adapter currently targets
+`drizzle-orm@1.0.0-rc.4`, not a stable 1.0 release.
+
+`executeDecodedSql` keeps SQL results unknown until an explicit decoder validates
+them. Use parameterized templates; `sql<T>` alone does not validate returned data.
+The optional `@supacloud/commands/typebox` contract can use schemas derived through
+`drizzle-orm/typebox-legacy`, selecting public fields rather than accepting
+internal tenant/permission fields.
+
+`defineReadQuery` combines input decoding, authorization, result decoding and
+payload-free observation. `createBunReadDatabase` admits one parsed SELECT and
+runs a PostgreSQL READ ONLY transaction with a statement timeout.
+`createBunDrizzleReadDatabase` provides the read transaction boundary for Drizzle.
+Keep least-privilege roles and RLS; AOP does not replace them.
+
+`supacloud-sql-impact impact.json --check` analyzes ordered, owned migrations:
+
+```json
+{
+  "migrations": [
+    { "id": "001", "owner": "orders", "path": "migrations/001.sql" }
+  ],
+  "baseline": []
+}
+```
+
+Paths are relative to this config. Reports include fingerprints, dependencies,
+transitive impact, review reasons and a digest. Persist applied IDs and SHA-256
+hashes as `baseline`; deleted, reordered or rewritten history fails validation.
+Supply `readSqlDependencyGraph(executor, ["app"])` results as `catalogEdges` and
+`catalogReview`. Import this catalog reader from `@supacloud/db/sql-analysis`.
+
+Dynamic SQL, opaque functions, unqualified names and unsupported semantics require
+review. This is conservative analysis, not proof of arbitrary SQL safety. Approve
+the exact reviewed report via `approvedDigest`; changes invalidate approval, and
+approval never overrides history errors. The tool does not execute migrations.
+
+The focused `tests/drizzle-foundation.test.ts` test needs Docker and starts a
+disposable local PostgreSQL/PGMQ instance. Prepare Commands and Compiler package
+dependencies first using `scripts/build-command-dependencies.ts db`.
+
 ## Durable Commands
 
 `createPostgresCommandStore(database)` implements the protocol's storage ports.
@@ -10,7 +57,8 @@ and input redaction. It does not own a recovery polling queue.
 Execution factories moved to `@supacloud/commands`; pass `store` instead of
 `database`. Errors moved to `CommandError` in `@supacloud/contracts`. Neither
 remote sending nor command orchestration is re-exported here. The DB package
-does not depend on the command runtime, including through its tests.
+does not depend on the command runtime in production. The Drizzle integration
+test uses the command runtime to verify the shared transaction boundary.
 
 Install the existing PGMQ/Workflow runtime and updated commands-public SQL module,
 then `COMMAND_PERSISTENCE_SQL` through a privileged application migration.

package/dist/command-adapter.d.ts

@@ -2,8 +2,8 @@ import type { CommandStore, CommandRetentionStore } from "@supacloud/contracts";
 export interface CommandTransaction {
     query(sql: string, parameters?: readonly (string | number | boolean | null)[]): Promise<unknown>;
 }
-export interface CommandDatabase {
-    transaction<T>(run: (transaction: CommandTransaction) => Promise<T>): Promise<T>;
+export interface CommandDatabase<Transaction extends CommandTransaction = CommandTransaction> {
+    transaction<T>(run: (transaction: Transaction) => Promise<T>): Promise<T>;
 }
 export interface CommandSubmissionBinding {
     commandId: string;
@@ -13,6 +13,6 @@ export interface CommandSubmissionBinding {
     workerId: string;
 }
 /** PostgreSQL only: no remote sending, domain matching or recovery policy lives here. */
-export declare function createPostgresCommandStore(database: CommandDatabase, options?: {
+export declare function createPostgresCommandStore<Transaction extends CommandTransaction>(database: CommandDatabase<Transaction>, options?: {
     submission?: CommandSubmissionBinding;
-}): CommandStore<CommandTransaction> & CommandRetentionStore;
+}): CommandStore<Transaction> & CommandRetentionStore;

package/dist/command-bun.d.ts

@@ -2,3 +2,7 @@ import type { SQL } from "bun";
 import type { CommandDatabase } from "./command-adapter";
 /** The SQL pool owns one connection from BEGIN through COMMIT/ROLLBACK. */
 export declare function createBunCommandDatabase(sql: SQL): CommandDatabase;
+/** The driver owns a read-only transaction and enforces its statement timeout. */
+export declare function createBunReadDatabase(pool: SQL, timeoutMs?: number): Readonly<{
+    query(text: string, parameters?: readonly (string | number | boolean | null)[], signal?: AbortSignal): Promise<unknown>;
+}>;

package/dist/command-bun.js

@@ -1,3 +1,287 @@
+var __esm = (fn, res, err) => () => {
+  if (fn)
+    try {
+      res = fn(fn = 0);
+    } catch (e) {
+      err = [e];
+    }
+  if (err)
+    throw err[0];
+  return res;
+};
+
+// src/sql-analysis.ts
+import { createHash } from "node:crypto";
+import { fingerprint, parse } from "libpg-query";
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function walk(value, visit) {
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walk(item, visit);
+  } else if (record(value)) {
+    visit(value);
+    for (const item of Object.values(value))
+      walk(item, visit);
+  }
+}
+function names(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.flatMap((part) => record(part) && record(part["String"]) && typeof part["String"]["sval"] === "string" ? [part["String"]["sval"]] : []);
+}
+async function analyzeSql(sql) {
+  const result = await parse(sql);
+  const defines = new Set, touches = new Set, references = new Set, review = new Set;
+  const qualified = (kind, parts) => {
+    if (parts.length !== 2) {
+      review.add(`Resolve unqualified or unsupported ${kind} name: ${parts.join(".")}`);
+      return;
+    }
+    return objectId(kind, parts);
+  };
+  const relation = (value) => {
+    if (!record(value) || typeof value["relname"] !== "string")
+      return;
+    return qualified("relation", typeof value["schemaname"] === "string" ? [value["schemaname"], value["relname"]] : [value["relname"]]);
+  };
+  walk(result, (node) => {
+    if (record(node["RangeVar"])) {
+      const name = relation(node["RangeVar"]);
+      if (name)
+        references.add(name);
+    }
+    if (record(node["FuncCall"])) {
+      const name = qualified("function", names(node["FuncCall"]["funcname"]));
+      if (name)
+        references.add(name);
+    }
+    if (record(node["Constraint"])) {
+      const name = relation(node["Constraint"]["pktable"]);
+      if (name)
+        references.add(name);
+    }
+  });
+  const statements = record(result) && Array.isArray(result["stmts"]) ? result["stmts"] : [];
+  for (const raw of statements) {
+    if (!record(raw) || !record(raw["stmt"]))
+      throw new Error("Invalid PostgreSQL parse tree");
+    const [kind, node] = Object.entries(raw["stmt"])[0] ?? [];
+    if (!kind || !record(node))
+      throw new Error("Invalid SQL statement");
+    const target = relation(node["relation"] ?? node["view"] ?? node["table"]);
+    if (target) {
+      touches.add(target);
+      if (kind === "CreateStmt" || kind === "ViewStmt")
+        defines.add(target);
+    }
+    if (kind === "DropStmt") {
+      for (const item of Array.isArray(node["objects"]) ? node["objects"] : []) {
+        const name = record(item) && record(item["List"]) ? qualified(node["removeType"] === "OBJECT_TABLE" || node["removeType"] === "OBJECT_VIEW" ? "relation" : "object", names(item["List"]["items"])) : undefined;
+        if (name)
+          touches.add(name);
+        else
+          review.add("Review dropped object identity and dependencies");
+      }
+      review.add("Destructive DROP requires review");
+    } else if (kind === "CreateFunctionStmt") {
+      const name = qualified("function", names(node["funcname"]));
+      if (name) {
+        defines.add(name);
+        touches.add(name);
+      }
+      let language, body;
+      for (const item of Array.isArray(node["options"]) ? node["options"] : []) {
+        if (!record(item) || !record(item["DefElem"]))
+          continue;
+        const option = item["DefElem"];
+        if (option["defname"] === "language")
+          language = names([option["arg"]])[0];
+        if (option["defname"] === "as" && record(option["arg"]) && record(option["arg"]["List"]))
+          body = names(option["arg"]["List"]["items"])[0];
+      }
+      if (language === "sql" && body !== undefined) {
+        const nested = await analyzeSql(body);
+        for (const name of [...nested.references, ...nested.touches])
+          references.add(name);
+        for (const item of nested.review)
+          review.add(item);
+      } else {
+        review.add("Function body dependencies require catalog verification or explicit reviewed dependencies");
+      }
+      review.add("Review function security, grants and overloads");
+    } else if (![
+      "SelectStmt",
+      "CreateStmt",
+      "ViewStmt",
+      "AlterTableStmt",
+      "IndexStmt",
+      "InsertStmt",
+      "UpdateStmt",
+      "DeleteStmt",
+      "CreatePolicyStmt",
+      "AlterPolicyStmt",
+      "CreateTrigStmt"
+    ].includes(kind)) {
+      review.add(`Review unsupported dependency semantics: ${kind}`);
+    }
+    if (["AlterTableStmt", "CreatePolicyStmt", "AlterPolicyStmt", "CreateTrigStmt"].includes(kind)) {
+      review.add(`Review schema/access impact: ${kind}`);
+    }
+  }
+  return {
+    fingerprint: await fingerprint(sql),
+    defines: [...defines].sort(),
+    touches: [...touches].sort(),
+    references: [...references].sort(),
+    review: [...review].sort()
+  };
+}
+async function assertReadSql(sql) {
+  const tree = await parse(sql);
+  if (!record(tree) || !Array.isArray(tree["stmts"]) || tree["stmts"].length !== 1)
+    throw new Error("Expected one read statement");
+  const entry = tree["stmts"][0];
+  if (!record(entry) || !record(entry["stmt"]) || !record(entry["stmt"]["SelectStmt"]))
+    throw new Error("Expected SELECT");
+  walk(tree, (node) => {
+    if (["InsertStmt", "UpdateStmt", "DeleteStmt", "MergeStmt", "IntoClause", "intoClause", "LockingClause"].some((name) => (name in node))) {
+      throw new Error("Mutating or locking SQL is not a read query");
+    }
+  });
+  return fingerprint(sql);
+}
+async function readSqlDependencyGraph(executor, schemas) {
+  if (!schemas.length || schemas.some((schema) => !schema.trim()))
+    throw new TypeError("Select explicit application schemas");
+  const schemaParameters = schemas.map((_, index) => `$${index + 1}::text`).join(", ");
+  const rows = await executor.query(`
+WITH objects AS (
+  SELECT 'pg_class'::regclass::oid AS classid, c.oid AS objid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text AS identity
+  FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
+  UNION ALL
+  SELECT 'pg_proc'::regclass::oid, p.oid, n.nspname,
+    'function:' || to_json(n.nspname)::text || '.' || to_json(p.proname)::text
+  FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace
+  UNION ALL
+  SELECT 'pg_rewrite'::regclass::oid, r.oid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text
+  FROM pg_rewrite r JOIN pg_class c ON c.oid=r.ev_class JOIN pg_namespace n ON n.oid=c.relnamespace
+  UNION ALL
+  SELECT 'pg_policy'::regclass::oid, p.oid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text
+  FROM pg_policy p JOIN pg_class c ON c.oid=p.polrelid JOIN pg_namespace n ON n.oid=c.relnamespace
+  UNION ALL
+  SELECT 'pg_trigger'::regclass::oid, t.oid, n.nspname,
+    'relation:' || to_json(n.nspname)::text || '.' || to_json(c.relname)::text
+  FROM pg_trigger t JOIN pg_class c ON c.oid=t.tgrelid JOIN pg_namespace n ON n.oid=c.relnamespace
+)
+SELECT DISTINCT a.identity AS dependent, b.identity AS dependency
+FROM pg_depend d
+JOIN objects a ON a.classid=d.classid AND a.objid=d.objid
+JOIN objects b ON b.classid=d.refclassid AND b.objid=d.refobjid
+WHERE a.nspname IN (${schemaParameters})
+  AND b.nspname IN (${schemaParameters}) AND a.identity<>b.identity
+ORDER BY dependent, dependency`, [...schemas]);
+  if (!Array.isArray(rows))
+    throw new TypeError("Invalid PostgreSQL dependency rows");
+  const edges = rows.map((row) => {
+    if (!record(row) || typeof row["dependent"] !== "string" || typeof row["dependency"] !== "string")
+      throw new TypeError("Invalid PostgreSQL dependency edge");
+    return { dependent: row["dependent"], dependency: row["dependency"] };
+  });
+  const functions = await executor.query(`
+SELECT DISTINCT n.nspname AS schema, p.proname AS name
+FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace
+JOIN pg_language l ON l.oid=p.prolang
+WHERE n.nspname IN (${schemaParameters})
+  AND (l.lanname='plpgsql' OR (l.lanname='sql' AND p.prosqlbody IS NULL))
+ORDER BY schema, name`, [...schemas]);
+  if (!Array.isArray(functions))
+    throw new TypeError("Invalid PostgreSQL function rows");
+  return {
+    edges,
+    review: functions.map((row) => {
+      if (!record(row) || typeof row["schema"] !== "string" || typeof row["name"] !== "string")
+        throw new TypeError("Invalid function identity");
+      return `Catalog cannot prove function-body dependencies: ${objectId("function", [row["schema"], row["name"]])}`;
+    })
+  };
+}
+async function planSqlImpact(sources, baseline = [], catalogEdges = []) {
+  const ids = new Set;
+  const migrations = [];
+  const edges = new Map;
+  const addEdge = (dependent, dependency) => {
+    if (dependent !== dependency)
+      edges.set(JSON.stringify([dependent, dependency]), { dependent, dependency });
+  };
+  for (const edge of catalogEdges)
+    addEdge(edge["dependent"], edge["dependency"]);
+  for (const source of sources) {
+    if (!source.id.trim() || !source.owner.trim() || ids.has(source.id))
+      throw new Error("Migration IDs must be unique and each migration must have an owner");
+    ids.add(source.id);
+    const analysis = await analyzeSql(source.sql);
+    const references = [...new Set([...analysis.references, ...source.dependencies ?? []])].sort();
+    for (const target of analysis.touches)
+      for (const reference of references)
+        addEdge(target, reference);
+    migrations.push({
+      id: source.id,
+      owner: source.owner,
+      sha256: createHash("sha256").update(source.sql).digest("hex"),
+      analysis: { ...analysis, references }
+    });
+  }
+  const current = new Map(migrations.map((entry) => [entry.id, entry]));
+  const previous = new Map(baseline.map((entry) => [entry.id, entry]));
+  const errors = [];
+  if (previous.size !== baseline.length)
+    errors.push("Duplicate migration in baseline");
+  for (const [index, old] of baseline.entries()) {
+    if (current.get(old.id)?.sha256 !== old.sha256 || migrations[index]?.id !== old.id) {
+      errors.push(`Applied migration removed, reordered or rewritten: ${old.id}`);
+    }
+  }
+  const changed = migrations.filter((entry) => previous.get(entry.id)?.sha256 !== entry.sha256);
+  const affected = new Set(changed.flatMap((entry) => entry.analysis.touches));
+  const reverse = new Map;
+  for (const edge of edges.values()) {
+    const values = reverse.get(edge["dependency"]) ?? [];
+    values.push(edge["dependent"]);
+    reverse.set(edge["dependency"], values);
+  }
+  for (const object of affected)
+    for (const dependent of reverse.get(object) ?? [])
+      affected.add(dependent);
+  const definitions = new Map;
+  migrations.forEach((entry, index) => {
+    for (const object of entry.analysis.defines)
+      if (!definitions.has(object))
+        definitions.set(object, index);
+  });
+  migrations.forEach((entry, index) => {
+    for (const reference of entry.analysis.references) {
+      if ((definitions.get(reference) ?? -1) > index)
+        errors.push(`${entry.id} references an object defined by a later migration: ${reference}`);
+    }
+  });
+  return {
+    migrations,
+    edges: [...edges.values()].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+    changed: changed.map((entry) => entry.id),
+    affectedObjects: [...affected].sort(),
+    affectedMigrations: migrations.filter((entry) => [...entry.analysis.touches, ...entry.analysis.references].some((object) => affected.has(object))).map((entry) => entry.id),
+    errors,
+    review: changed.flatMap((entry) => entry.analysis.review.map((note) => `${entry.id}: ${note}`))
+  };
+}
+var objectId = (kind, parts) => `${kind}:${parts.map((part) => JSON.stringify(part)).join(".")}`;
+var init_sql_analysis = () => {};
+
 // src/command-bun.ts
 function createBunCommandDatabase(sql) {
   return {
@@ -14,6 +298,53 @@ function createBunCommandDatabase(sql) {
     }
   };
 }
+function createBunReadDatabase(pool, timeoutMs = 5000) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+    throw new TypeError("Invalid read statement timeout");
+  }
+  const admitted = new Map;
+  return Object.freeze({
+    async query(text, parameters = [], signal) {
+      if (signal?.aborted)
+        throw new Error("Read aborted");
+      await Promise.resolve().then(() => init_sql_analysis());
+      let admission = admitted.get(text);
+      if (!admission) {
+        admission = assertReadSql(text);
+        if (admitted.size >= 256) {
+          const oldest = admitted.keys().next().value;
+          if (oldest !== undefined)
+            admitted.delete(oldest);
+        }
+        admitted.set(text, admission);
+      }
+      try {
+        await admission;
+      } catch (error) {
+        admitted.delete(text);
+        throw error;
+      }
+      return pool.begin(async (connection) => {
+        await connection.unsafe("SET TRANSACTION READ ONLY");
+        await connection`SELECT set_config('statement_timeout', ${String(timeoutMs)}, true)`;
+        if (signal?.aborted)
+          throw new Error("Read aborted");
+        const pending = connection.unsafe(text, [...parameters]);
+        const abort = () => pending.cancel();
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+          const rows = await pending;
+          if (signal?.aborted)
+            throw new Error("Read aborted");
+          return rows;
+        } finally {
+          signal?.removeEventListener("abort", abort);
+        }
+      });
+    }
+  });
+}
 export {
-  createBunCommandDatabase
+  createBunCommandDatabase,
+  createBunReadDatabase
 };

package/dist/drizzle-bun.d.ts

@@ -0,0 +1,10 @@
+import type { SQL } from "bun";
+import { type BunSQLDatabase } from "drizzle-orm/bun-sql/postgres";
+import type { AnyRelations, EmptyRelations } from "drizzle-orm/relations";
+import type { DrizzlePgConfig } from "drizzle-orm/pg-core";
+/** Drizzle is bound to Bun's pinned transaction client, not the application pool. */
+export declare function createBunDrizzleCommandDatabase<Relations extends AnyRelations = EmptyRelations>(pool: SQL, config?: DrizzlePgConfig<Relations>): import("./command-adapter").CommandDatabase<import("./drizzle").DrizzleCommandTransaction<BunSQLDatabase<Relations>>>;
+/** Explicit read-only unit of work; use a least-privilege pool with the intended RLS identity. */
+export declare function createBunDrizzleReadDatabase<Relations extends AnyRelations = EmptyRelations>(pool: SQL, config?: DrizzlePgConfig<Relations>, timeoutMs?: number): Readonly<{
+    read<Result>(work: (db: BunSQLDatabase<Relations>) => Promise<Result>): Promise<Result>;
+}>;

package/dist/drizzle-bun.js

@@ -0,0 +1,93 @@
+// src/drizzle-bun.ts
+import { drizzle } from "drizzle-orm/bun-sql/postgres";
+
+// src/drizzle.ts
+import { is } from "drizzle-orm";
+import { getTableConfig, PgTable } from "drizzle-orm/pg-core";
+
+// src/module.ts
+function normalizeTable(ref) {
+  if (typeof ref === "string")
+    return ref;
+  const schema = ref._.schema ?? "public";
+  return `${schema}.${ref._.name}`;
+}
+function defineDatabaseModule(options) {
+  return {
+    name: options.name,
+    tables: (options.tables ?? []).map(normalizeTable),
+    policies: options.policies ?? [],
+    functions: options.functions ?? [],
+    triggers: options.triggers ?? [],
+    grants: options.grants ?? []
+  };
+}
+
+// src/drizzle.ts
+function defineDrizzleDatabaseModule(tables, options) {
+  const names = new Set;
+  for (const table of Object.values(tables)) {
+    if (!is(table, PgTable))
+      throw new TypeError("Expected a PostgreSQL Drizzle table");
+    const config = getTableConfig(table);
+    names.add(`${config.schema ?? "public"}.${config.name}`);
+  }
+  return defineDatabaseModule({ ...options, tables: [...names].sort() });
+}
+function createDrizzleCommandDatabase(options) {
+  return {
+    transaction: (work) => options.transaction(async (connection) => {
+      const db = options.bind(connection);
+      let active = true;
+      try {
+        return await work({
+          db,
+          query: async (text, parameters = []) => {
+            if (!active)
+              throw new Error("Command transaction is closed");
+            return options.query(connection, text, parameters);
+          }
+        });
+      } finally {
+        active = false;
+      }
+    })
+  };
+}
+async function executeDecodedSql(executor, query, decode) {
+  return decode(await executor.execute(query));
+}
+
+// src/drizzle-bun.ts
+function createBunDrizzleCommandDatabase(pool, config = {}) {
+  return createDrizzleCommandDatabase({
+    transaction: async (work) => {
+      const result = await pool.begin(async (connection) => ({ value: await work(connection) }));
+      return result.value;
+    },
+    bind: (connection) => drizzle({ ...config, client: connection }),
+    query: async (connection, text, parameters) => {
+      const rows = await connection.unsafe(text, [...parameters]);
+      return rows;
+    }
+  });
+}
+function createBunDrizzleReadDatabase(pool, config = {}, timeoutMs = 5000) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+    throw new TypeError("Invalid read statement timeout");
+  }
+  return Object.freeze({
+    async read(work) {
+      const result = await pool.begin(async (connection) => {
+        await connection.unsafe("SET TRANSACTION READ ONLY");
+        await connection`SELECT set_config('statement_timeout', ${String(timeoutMs)}, true)`;
+        return { value: await work(drizzle({ ...config, client: connection })) };
+      });
+      return result.value;
+    }
+  });
+}
+export {
+  createBunDrizzleCommandDatabase,
+  createBunDrizzleReadDatabase
+};

package/dist/drizzle.d.ts

@@ -0,0 +1,26 @@
+import { type SQL } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import type { DatabaseModule, DatabaseModuleOptions } from "./module.js";
+import type { CommandDatabase, CommandTransaction } from "./command-adapter";
+/** Accept explicit table exports, not arbitrary objects or private type-only metadata. */
+export declare function defineDrizzleDatabaseModule(tables: Readonly<Record<string, PgTable>>, options: Omit<DatabaseModuleOptions, "tables">): DatabaseModule;
+export interface DrizzleCommandTransaction<Database> extends CommandTransaction {
+    readonly db: Database;
+}
+export interface DrizzleCommandDatabaseOptions<Connection, Database> {
+    /** Owns BEGIN/COMMIT/ROLLBACK and pins one connection for the callback. */
+    transaction<T>(work: (connection: Connection) => Promise<T>): Promise<T>;
+    /** Construct Drizzle on this connection, never on the outer connection pool. */
+    bind(connection: NoInfer<Connection>): Database;
+    /** Execute parameterized protocol SQL on the same connection; return rows only. */
+    query(connection: NoInfer<Connection>, text: string, parameters: readonly (string | number | boolean | null)[]): Promise<unknown>;
+}
+/**
+ * One native transaction serves Drizzle business writes and SQL receipts.
+ * No SQL placeholder rewriting, hidden second transaction or driver internals.
+ */
+export declare function createDrizzleCommandDatabase<Connection, Database>(options: DrizzleCommandDatabaseOptions<Connection, Database>): CommandDatabase<DrizzleCommandTransaction<Database>>;
+/** Raw SQL results stay unknown until an application-owned decoder validates them. */
+export declare function executeDecodedSql<Result>(executor: {
+    execute(query: SQL): PromiseLike<unknown>;
+}, query: SQL<unknown>, decode: (value: unknown) => Result): Promise<Result>;

package/dist/drizzle.js

@@ -0,0 +1,61 @@
+// src/drizzle.ts
+import { is } from "drizzle-orm";
+import { getTableConfig, PgTable } from "drizzle-orm/pg-core";
+
+// src/module.ts
+function normalizeTable(ref) {
+  if (typeof ref === "string")
+    return ref;
+  const schema = ref._.schema ?? "public";
+  return `${schema}.${ref._.name}`;
+}
+function defineDatabaseModule(options) {
+  return {
+    name: options.name,
+    tables: (options.tables ?? []).map(normalizeTable),
+    policies: options.policies ?? [],
+    functions: options.functions ?? [],
+    triggers: options.triggers ?? [],
+    grants: options.grants ?? []
+  };
+}
+
+// src/drizzle.ts
+function defineDrizzleDatabaseModule(tables, options) {
+  const names = new Set;
+  for (const table of Object.values(tables)) {
+    if (!is(table, PgTable))
+      throw new TypeError("Expected a PostgreSQL Drizzle table");
+    const config = getTableConfig(table);
+    names.add(`${config.schema ?? "public"}.${config.name}`);
+  }
+  return defineDatabaseModule({ ...options, tables: [...names].sort() });
+}
+function createDrizzleCommandDatabase(options) {
+  return {
+    transaction: (work) => options.transaction(async (connection) => {
+      const db = options.bind(connection);
+      let active = true;
+      try {
+        return await work({
+          db,
+          query: async (text, parameters = []) => {
+            if (!active)
+              throw new Error("Command transaction is closed");
+            return options.query(connection, text, parameters);
+          }
+        });
+      } finally {
+        active = false;
+      }
+    })
+  };
+}
+async function executeDecodedSql(executor, query, decode) {
+  return decode(await executor.execute(query));
+}
+export {
+  createDrizzleCommandDatabase,
+  defineDrizzleDatabaseModule,
+  executeDecodedSql
+};

package/dist/index.d.ts

@@ -9,4 +9,5 @@ export { buildDatabaseManifest, explainObject, type DatabaseManifest, type Datab
 export { createDatabaseAccessBoundary, DatabaseAccessError, type AuthenticatedDatabaseIdentity, type DatabaseAccessBoundary, type DatabaseAccessBoundaryOptions, type DatabaseAccessErrorCode, } from './access.js';
 export { createRpcClient, defineRpcContract, RpcContractError, type RpcArgs, type RpcCallResult, type RpcContract, type RpcDecoder, type RpcResult, type RpcTransport, } from './rpc.js';
 export { COMMAND_PERSISTENCE_SQL, COMMAND_PERSISTENCE_UPGRADE_SQL } from "./command-schema";
+export { defineReadQuery, decodePostgrestQuery, QueryBoundaryError, type QueryEvent, type QueryObserver, type ReadQueryDefinition } from "./query";
 export { createPostgresCommandStore, type CommandDatabase, type CommandTransaction, type CommandSubmissionBinding, } from "./command-adapter";