@vertz/db 0.2.0

package/dist/index.js

@@ -0,0 +1,2010 @@
+import {
+  buildDelete,
+  buildInsert,
+  buildSelect,
+  buildUpdate,
+  buildWhere
+} from "./shared/chunk-3f2grpak.js";
+import {
+  CheckConstraintError,
+  ConnectionError,
+  ConnectionPoolExhaustedError,
+  DbError,
+  ForeignKeyError,
+  NotFoundError,
+  NotNullError,
+  UniqueConstraintError,
+  executeQuery,
+  getPrimaryKeyColumns,
+  getTimestampColumns,
+  mapRow,
+  mapRows,
+  parsePgError,
+  resolveSelectColumns
+} from "./shared/chunk-xp022dyp.js";
+import {
+  camelToSnake
+} from "./shared/chunk-hrfdj0rr.js";
+import {
+  diagnoseError,
+  explainError,
+  formatDiagnostic
+} from "./shared/chunk-wj026daz.js";
+
+// src/migration/differ.ts
+function columnSimilarity(a, b) {
+  let score = 0;
+  let total = 0;
+  total += 3;
+  if (a.type === b.type)
+    score += 3;
+  total += 1;
+  if (a.nullable === b.nullable)
+    score += 1;
+  total += 1;
+  if (a.primary === b.primary)
+    score += 1;
+  total += 1;
+  if (a.unique === b.unique)
+    score += 1;
+  return score / total;
+}
+function indexKey(columns) {
+  return columns.join(",");
+}
+function computeDiff(before, after) {
+  const changes = [];
+  for (const tableName of Object.keys(after.tables)) {
+    if (!(tableName in before.tables)) {
+      changes.push({ type: "table_added", table: tableName });
+    }
+  }
+  for (const tableName of Object.keys(before.tables)) {
+    if (!(tableName in after.tables)) {
+      changes.push({ type: "table_removed", table: tableName });
+    }
+  }
+  for (const tableName of Object.keys(after.tables)) {
+    if (!(tableName in before.tables))
+      continue;
+    const beforeTable = before.tables[tableName];
+    const afterTable = after.tables[tableName];
+    if (!beforeTable || !afterTable)
+      continue;
+    const removedCols = Object.keys(beforeTable.columns).filter((c) => !(c in afterTable.columns));
+    const addedCols = Object.keys(afterTable.columns).filter((c) => !(c in beforeTable.columns));
+    const renames = [];
+    const matchedRemoved = new Set;
+    const matchedAdded = new Set;
+    for (const removed of removedCols) {
+      const removedSnap = beforeTable.columns[removed];
+      if (!removedSnap)
+        continue;
+      let bestMatch = null;
+      let bestScore = 0;
+      for (const added of addedCols) {
+        if (matchedAdded.has(added))
+          continue;
+        const addedSnap = afterTable.columns[added];
+        if (!addedSnap)
+          continue;
+        const score = columnSimilarity(removedSnap, addedSnap);
+        if (score > bestScore) {
+          bestScore = score;
+          bestMatch = added;
+        }
+      }
+      if (bestMatch && bestScore >= 0.7) {
+        renames.push({ oldCol: removed, newCol: bestMatch, confidence: bestScore });
+        matchedRemoved.add(removed);
+        matchedAdded.add(bestMatch);
+      }
+    }
+    for (const rename of renames) {
+      changes.push({
+        type: "column_renamed",
+        table: tableName,
+        oldColumn: rename.oldCol,
+        newColumn: rename.newCol,
+        confidence: rename.confidence
+      });
+    }
+    for (const colName of addedCols) {
+      if (!matchedAdded.has(colName)) {
+        changes.push({ type: "column_added", table: tableName, column: colName });
+      }
+    }
+    for (const colName of removedCols) {
+      if (!matchedRemoved.has(colName)) {
+        changes.push({ type: "column_removed", table: tableName, column: colName });
+      }
+    }
+    for (const colName of Object.keys(afterTable.columns)) {
+      if (!(colName in beforeTable.columns))
+        continue;
+      const beforeCol = beforeTable.columns[colName];
+      const afterCol = afterTable.columns[colName];
+      if (!beforeCol || !afterCol)
+        continue;
+      if (beforeCol.type !== afterCol.type || beforeCol.nullable !== afterCol.nullable || beforeCol.default !== afterCol.default) {
+        const change = {
+          type: "column_altered",
+          table: tableName,
+          column: colName
+        };
+        if (beforeCol.type !== afterCol.type) {
+          change.oldType = beforeCol.type;
+          change.newType = afterCol.type;
+        }
+        if (beforeCol.nullable !== afterCol.nullable) {
+          change.oldNullable = beforeCol.nullable;
+          change.newNullable = afterCol.nullable;
+        }
+        if (beforeCol.default !== afterCol.default) {
+          change.oldDefault = beforeCol.default;
+          change.newDefault = afterCol.default;
+        }
+        changes.push(change);
+      }
+    }
+    const beforeIndexKeys = new Set(beforeTable.indexes.map((i) => indexKey(i.columns)));
+    const afterIndexKeys = new Set(afterTable.indexes.map((i) => indexKey(i.columns)));
+    for (const idx of afterTable.indexes) {
+      const key = indexKey(idx.columns);
+      if (!beforeIndexKeys.has(key)) {
+        changes.push({ type: "index_added", table: tableName, columns: [...idx.columns] });
+      }
+    }
+    for (const idx of beforeTable.indexes) {
+      const key = indexKey(idx.columns);
+      if (!afterIndexKeys.has(key)) {
+        changes.push({ type: "index_removed", table: tableName, columns: [...idx.columns] });
+      }
+    }
+  }
+  for (const enumName of Object.keys(after.enums)) {
+    if (!(enumName in before.enums)) {
+      changes.push({ type: "enum_added", enumName });
+    }
+  }
+  for (const enumName of Object.keys(before.enums)) {
+    if (!(enumName in after.enums)) {
+      changes.push({ type: "enum_removed", enumName });
+    }
+  }
+  for (const enumName of Object.keys(after.enums)) {
+    if (!(enumName in before.enums))
+      continue;
+    const beforeVals = before.enums[enumName];
+    const afterVals = after.enums[enumName];
+    if (!beforeVals || !afterVals)
+      continue;
+    const beforeSet = new Set(beforeVals);
+    const afterSet = new Set(afterVals);
+    const addedValues = afterVals.filter((v) => !beforeSet.has(v));
+    const removedValues = beforeVals.filter((v) => !afterSet.has(v));
+    if (addedValues.length > 0 || removedValues.length > 0) {
+      changes.push({ type: "enum_altered", enumName, addedValues, removedValues });
+    }
+  }
+  return { changes };
+}
+// src/migration/runner.ts
+import { createHash } from "node:crypto";
+var HISTORY_TABLE = "_vertz_migrations";
+var CREATE_HISTORY_SQL = `
+CREATE TABLE IF NOT EXISTS "${HISTORY_TABLE}" (
+  "id" serial PRIMARY KEY,
+  "name" text NOT NULL UNIQUE,
+  "checksum" text NOT NULL,
+  "applied_at" timestamp with time zone NOT NULL DEFAULT now()
+);
+`;
+function computeChecksum(sql) {
+  return createHash("sha256").update(sql).digest("hex");
+}
+function parseMigrationName(filename) {
+  const match = filename.match(/^(\d+)_(.+)\.sql$/);
+  if (!match?.[1] || !match[2])
+    return null;
+  return {
+    timestamp: Number.parseInt(match[1], 10),
+    name: filename
+  };
+}
+function createMigrationRunner() {
+  return {
+    async createHistoryTable(queryFn) {
+      await queryFn(CREATE_HISTORY_SQL, []);
+    },
+    async apply(queryFn, sql, name, options) {
+      const checksum = computeChecksum(sql);
+      const recordSql = `INSERT INTO "${HISTORY_TABLE}" ("name", "checksum") VALUES ($1, $2)`;
+      const statements = [sql, recordSql];
+      if (options?.dryRun) {
+        return {
+          name,
+          sql,
+          checksum,
+          dryRun: true,
+          statements
+        };
+      }
+      await queryFn(sql, []);
+      await queryFn(recordSql, [name, checksum]);
+      return {
+        name,
+        sql,
+        checksum,
+        dryRun: false,
+        statements
+      };
+    },
+    async getApplied(queryFn) {
+      const result = await queryFn(`SELECT "name", "checksum", "applied_at" FROM "${HISTORY_TABLE}" ORDER BY "id" ASC`, []);
+      return result.rows.map((row) => ({
+        name: row.name,
+        checksum: row.checksum,
+        appliedAt: new Date(row.applied_at)
+      }));
+    },
+    getPending(files, applied) {
+      const appliedNames = new Set(applied.map((a) => a.name));
+      return files.filter((f) => !appliedNames.has(f.name)).sort((a, b) => a.timestamp - b.timestamp);
+    },
+    detectDrift(files, applied) {
+      const drifted = [];
+      const appliedMap = new Map(applied.map((a) => [a.name, a.checksum]));
+      for (const file of files) {
+        const appliedChecksum = appliedMap.get(file.name);
+        if (appliedChecksum && appliedChecksum !== computeChecksum(file.sql)) {
+          drifted.push(file.name);
+        }
+      }
+      return drifted;
+    },
+    detectOutOfOrder(files, applied) {
+      if (applied.length === 0)
+        return [];
+      const appliedNames = new Set(applied.map((a) => a.name));
+      const lastApplied = applied[applied.length - 1];
+      if (!lastApplied)
+        return [];
+      const lastAppliedFile = files.find((f) => f.name === lastApplied.name);
+      if (!lastAppliedFile)
+        return [];
+      return files.filter((f) => !appliedNames.has(f.name) && f.timestamp < lastAppliedFile.timestamp).map((f) => f.name);
+    }
+  };
+}
+
+// src/migration/files.ts
+function formatMigrationFilename(num, description) {
+  return `${String(num).padStart(4, "0")}_${description}.sql`;
+}
+function nextMigrationNumber(existingFiles) {
+  let max = 0;
+  for (const file of existingFiles) {
+    const parsed = parseMigrationName(file);
+    if (parsed && parsed.timestamp > max) {
+      max = parsed.timestamp;
+    }
+  }
+  return max + 1;
+}
+// src/migration/sql-generator.ts
+function escapeSqlString(value) {
+  return value.replace(/'/g, "''");
+}
+function columnDef(name, col) {
+  const snakeName = camelToSnake(name);
+  const parts = [`"${snakeName}" ${col.type}`];
+  if (!col.nullable) {
+    parts.push("NOT NULL");
+  }
+  if (col.unique) {
+    parts.push("UNIQUE");
+  }
+  if (col.default !== undefined) {
+    parts.push(`DEFAULT ${col.default}`);
+  }
+  return parts.join(" ");
+}
+function generateMigrationSql(changes, ctx) {
+  const statements = [];
+  const tables = ctx?.tables;
+  const enums = ctx?.enums;
+  for (const change of changes) {
+    switch (change.type) {
+      case "table_added": {
+        if (!change.table)
+          break;
+        const table = tables?.[change.table];
+        if (!table)
+          break;
+        const tableName = camelToSnake(change.table);
+        const cols = [];
+        const primaryKeys = [];
+        for (const [colName, col] of Object.entries(table.columns)) {
+          cols.push(`  ${columnDef(colName, col)}`);
+          if (col.primary) {
+            primaryKeys.push(`"${camelToSnake(colName)}"`);
+          }
+        }
+        if (primaryKeys.length > 0) {
+          cols.push(`  PRIMARY KEY (${primaryKeys.join(", ")})`);
+        }
+        for (const fk of table.foreignKeys) {
+          const fkCol = camelToSnake(fk.column);
+          const fkTarget = camelToSnake(fk.targetTable);
+          const fkTargetCol = camelToSnake(fk.targetColumn);
+          cols.push(`  FOREIGN KEY ("${fkCol}") REFERENCES "${fkTarget}" ("${fkTargetCol}")`);
+        }
+        statements.push(`CREATE TABLE "${tableName}" (
+${cols.join(`,
+`)}
+);`);
+        for (const idx of table.indexes) {
+          const idxCols = idx.columns.map((c) => `"${camelToSnake(c)}"`).join(", ");
+          const idxName = `idx_${tableName}_${idx.columns.map(camelToSnake).join("_")}`;
+          statements.push(`CREATE INDEX "${idxName}" ON "${tableName}" (${idxCols});`);
+        }
+        break;
+      }
+      case "table_removed": {
+        if (!change.table)
+          break;
+        statements.push(`DROP TABLE "${camelToSnake(change.table)}";`);
+        break;
+      }
+      case "column_added": {
+        if (!change.table || !change.column)
+          break;
+        const col = tables?.[change.table]?.columns[change.column];
+        if (!col)
+          break;
+        statements.push(`ALTER TABLE "${camelToSnake(change.table)}" ADD COLUMN ${columnDef(change.column, col)};`);
+        break;
+      }
+      case "column_removed": {
+        if (!change.table || !change.column)
+          break;
+        statements.push(`ALTER TABLE "${camelToSnake(change.table)}" DROP COLUMN "${camelToSnake(change.column)}";`);
+        break;
+      }
+      case "column_altered": {
+        if (!change.table || !change.column)
+          break;
+        const snakeTable = camelToSnake(change.table);
+        const snakeCol = camelToSnake(change.column);
+        if (change.newType !== undefined) {
+          statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" TYPE ${change.newType};`);
+        }
+        if (change.newNullable !== undefined) {
+          if (change.newNullable) {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" DROP NOT NULL;`);
+          } else {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" SET NOT NULL;`);
+          }
+        }
+        if (change.newDefault !== undefined) {
+          if (change.newDefault) {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" SET DEFAULT ${change.newDefault};`);
+          } else {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" DROP DEFAULT;`);
+          }
+        }
+        break;
+      }
+      case "column_renamed": {
+        if (!change.table || !change.oldColumn || !change.newColumn)
+          break;
+        statements.push(`ALTER TABLE "${camelToSnake(change.table)}" RENAME COLUMN "${camelToSnake(change.oldColumn)}" TO "${camelToSnake(change.newColumn)}";`);
+        break;
+      }
+      case "index_added": {
+        if (!change.table || !change.columns)
+          break;
+        const snakeTable = camelToSnake(change.table);
+        const idxCols = change.columns.map((c) => `"${camelToSnake(c)}"`).join(", ");
+        const idxName = `idx_${snakeTable}_${change.columns.map(camelToSnake).join("_")}`;
+        statements.push(`CREATE INDEX "${idxName}" ON "${snakeTable}" (${idxCols});`);
+        break;
+      }
+      case "index_removed": {
+        if (!change.table || !change.columns)
+          break;
+        const snakeTable = camelToSnake(change.table);
+        const idxName = `idx_${snakeTable}_${change.columns.map(camelToSnake).join("_")}`;
+        statements.push(`DROP INDEX "${idxName}";`);
+        break;
+      }
+      case "enum_added": {
+        if (!change.enumName)
+          break;
+        const values = enums?.[change.enumName];
+        if (!values || values.length === 0)
+          break;
+        const enumSnakeName = camelToSnake(change.enumName);
+        const valuesStr = values.map((v) => `'${escapeSqlString(v)}'`).join(", ");
+        statements.push(`CREATE TYPE "${enumSnakeName}" AS ENUM (${valuesStr});`);
+        break;
+      }
+      case "enum_removed": {
+        if (!change.enumName)
+          break;
+        statements.push(`DROP TYPE "${camelToSnake(change.enumName)}";`);
+        break;
+      }
+      case "enum_altered": {
+        if (!change.enumName || !change.addedValues)
+          break;
+        const enumSnakeName = camelToSnake(change.enumName);
+        for (const val of change.addedValues) {
+          statements.push(`ALTER TYPE "${enumSnakeName}" ADD VALUE '${escapeSqlString(val)}';`);
+        }
+        break;
+      }
+    }
+  }
+  return statements.join(`
+
+`);
+}
+// src/cli/migrate-deploy.ts
+async function migrateDeploy(options) {
+  const runner = createMigrationRunner();
+  const isDryRun = options.dryRun ?? false;
+  if (!isDryRun) {
+    await runner.createHistoryTable(options.queryFn);
+  }
+  let applied;
+  if (isDryRun) {
+    try {
+      applied = await runner.getApplied(options.queryFn);
+    } catch {
+      applied = [];
+    }
+  } else {
+    applied = await runner.getApplied(options.queryFn);
+  }
+  const pending = runner.getPending(options.migrationFiles, applied);
+  const appliedNames = [];
+  const migrationResults = [];
+  for (const migration of pending) {
+    const result = await runner.apply(options.queryFn, migration.sql, migration.name, {
+      dryRun: isDryRun
+    });
+    appliedNames.push(migration.name);
+    migrationResults.push(result);
+  }
+  return {
+    applied: appliedNames,
+    alreadyApplied: applied.map((a) => a.name),
+    dryRun: isDryRun,
+    migrations: migrationResults.length > 0 ? migrationResults : undefined
+  };
+}
+// src/cli/migrate-dev.ts
+async function migrateDev(options) {
+  const diff = computeDiff(options.previousSnapshot, options.currentSnapshot);
+  const sql = generateMigrationSql(diff.changes, {
+    tables: options.currentSnapshot.tables,
+    enums: options.currentSnapshot.enums
+  });
+  const renames = diff.changes.filter((c) => c.type === "column_renamed").map((c) => ({
+    table: c.table,
+    oldColumn: c.oldColumn,
+    newColumn: c.newColumn,
+    confidence: c.confidence
+  }));
+  const num = nextMigrationNumber(options.existingFiles);
+  const filename = formatMigrationFilename(num, options.migrationName);
+  const filePath = `${options.migrationsDir}/${filename}`;
+  if (options.dryRun) {
+    return {
+      migrationFile: filename,
+      sql,
+      dryRun: true,
+      renames: renames.length > 0 ? renames : undefined,
+      snapshot: options.currentSnapshot
+    };
+  }
+  await options.writeFile(filePath, sql);
+  const runner = createMigrationRunner();
+  await runner.createHistoryTable(options.queryFn);
+  await runner.apply(options.queryFn, sql, filename, { dryRun: false });
+  return {
+    migrationFile: filename,
+    sql,
+    appliedAt: new Date,
+    dryRun: false,
+    renames: renames.length > 0 ? renames : undefined,
+    snapshot: options.currentSnapshot
+  };
+}
+// src/cli/push.ts
+async function push(options) {
+  const diff = computeDiff(options.previousSnapshot, options.currentSnapshot);
+  const sql = generateMigrationSql(diff.changes, {
+    tables: options.currentSnapshot.tables,
+    enums: options.currentSnapshot.enums
+  });
+  if (sql.length > 0) {
+    await options.queryFn(sql, []);
+  }
+  const tablesAffected = [
+    ...new Set(diff.changes.map((c) => c.table).filter((t) => t !== undefined))
+  ];
+  return { sql, tablesAffected };
+}
+// src/cli/status.ts
+async function migrateStatus(options) {
+  const runner = createMigrationRunner();
+  await runner.createHistoryTable(options.queryFn);
+  const applied = await runner.getApplied(options.queryFn);
+  const pending = runner.getPending(options.migrationFiles, applied);
+  return {
+    applied: applied.map((a) => ({
+      name: a.name,
+      checksum: a.checksum,
+      appliedAt: a.appliedAt
+    })),
+    pending: pending.map((p) => p.name)
+  };
+}
+// src/query/aggregate.ts
+async function count(queryFn, table, options) {
+  const allParams = [];
+  let sql = `SELECT COUNT(*) AS "count" FROM "${table._name}"`;
+  if (options?.where) {
+    const whereResult = buildWhere(options.where);
+    if (whereResult.sql.length > 0) {
+      sql += ` WHERE ${whereResult.sql}`;
+      allParams.push(...whereResult.params);
+    }
+  }
+  const res = await executeQuery(queryFn, sql, allParams);
+  const row = res.rows[0];
+  return Number(row?.count ?? 0);
+}
+async function aggregate(queryFn, table, options) {
+  const selectParts = [];
+  const aggFunctions = [];
+  if (options._count !== undefined) {
+    if (options._count === true) {
+      selectParts.push('COUNT(*) AS "_count"');
+      aggFunctions.push({ fn: "count", columns: null, key: "_count" });
+    } else {
+      for (const col of Object.keys(options._count)) {
+        const snakeCol = camelToSnake(col);
+        selectParts.push(`COUNT("${snakeCol}") AS "_count_${snakeCol}"`);
+      }
+    }
+  }
+  for (const [fn, aggOpt] of [
+    ["AVG", options._avg],
+    ["SUM", options._sum],
+    ["MIN", options._min],
+    ["MAX", options._max]
+  ]) {
+    if (!aggOpt)
+      continue;
+    for (const col of Object.keys(aggOpt)) {
+      const snakeCol = camelToSnake(col);
+      const alias = `_${fn.toLowerCase()}_${snakeCol}`;
+      selectParts.push(`${fn}("${snakeCol}") AS "${alias}"`);
+    }
+  }
+  if (selectParts.length === 0) {
+    return {};
+  }
+  const allParams = [];
+  let sql = `SELECT ${selectParts.join(", ")} FROM "${table._name}"`;
+  if (options.where) {
+    const whereResult = buildWhere(options.where);
+    if (whereResult.sql.length > 0) {
+      sql += ` WHERE ${whereResult.sql}`;
+      allParams.push(...whereResult.params);
+    }
+  }
+  const res = await executeQuery(queryFn, sql, allParams);
+  const row = res.rows[0];
+  if (!row)
+    return {};
+  const result = {};
+  if (options._count !== undefined) {
+    if (options._count === true) {
+      result._count = Number(row._count ?? 0);
+    } else {
+      const countObj = {};
+      for (const col of Object.keys(options._count)) {
+        const snakeCol = camelToSnake(col);
+        countObj[col] = Number(row[`_count_${snakeCol}`] ?? 0);
+      }
+      result._count = countObj;
+    }
+  }
+  for (const [fn, aggOpt] of [
+    ["avg", options._avg],
+    ["sum", options._sum],
+    ["min", options._min],
+    ["max", options._max]
+  ]) {
+    if (!aggOpt)
+      continue;
+    const fnObj = {};
+    for (const col of Object.keys(aggOpt)) {
+      const snakeCol = camelToSnake(col);
+      const val = row[`_${fn}_${snakeCol}`];
+      fnObj[col] = val === null || val === undefined ? null : Number(val);
+    }
+    result[`_${fn}`] = fnObj;
+  }
+  return result;
+}
+async function groupBy(queryFn, table, options) {
+  const selectParts = [];
+  const groupCols = [];
+  for (const col of options.by) {
+    const snakeCol = camelToSnake(col);
+    if (snakeCol === col) {
+      selectParts.push(`"${col}"`);
+    } else {
+      selectParts.push(`"${snakeCol}" AS "${col}"`);
+    }
+    groupCols.push(`"${snakeCol}"`);
+  }
+  if (options._count !== undefined) {
+    if (options._count === true) {
+      selectParts.push('COUNT(*) AS "_count"');
+    } else {
+      for (const col of Object.keys(options._count)) {
+        const snakeCol = camelToSnake(col);
+        selectParts.push(`COUNT("${snakeCol}") AS "_count_${snakeCol}"`);
+      }
+    }
+  }
+  for (const [fn, aggOpt] of [
+    ["AVG", options._avg],
+    ["SUM", options._sum],
+    ["MIN", options._min],
+    ["MAX", options._max]
+  ]) {
+    if (!aggOpt)
+      continue;
+    for (const col of Object.keys(aggOpt)) {
+      const snakeCol = camelToSnake(col);
+      const alias = `_${fn.toLowerCase()}_${snakeCol}`;
+      selectParts.push(`${fn}("${snakeCol}") AS "${alias}"`);
+    }
+  }
+  const allParams = [];
+  let sql = `SELECT ${selectParts.join(", ")} FROM "${table._name}"`;
+  if (options.where) {
+    const whereResult = buildWhere(options.where);
+    if (whereResult.sql.length > 0) {
+      sql += ` WHERE ${whereResult.sql}`;
+      allParams.push(...whereResult.params);
+    }
+  }
+  sql += ` GROUP BY ${groupCols.join(", ")}`;
+  if (options.orderBy) {
+    const validAggAliases = new Set;
+    validAggAliases.add("_count");
+    if (options._count !== undefined && options._count !== true) {
+      for (const col of Object.keys(options._count)) {
+        validAggAliases.add(`_count_${camelToSnake(col)}`);
+      }
+    }
+    for (const [fn, aggOpt] of [
+      ["avg", options._avg],
+      ["sum", options._sum],
+      ["min", options._min],
+      ["max", options._max]
+    ]) {
+      if (!aggOpt)
+        continue;
+      for (const col of Object.keys(aggOpt)) {
+        validAggAliases.add(`_${fn}_${camelToSnake(col)}`);
+      }
+    }
+    const orderClauses = [];
+    for (const [col, dir] of Object.entries(options.orderBy)) {
+      const normalizedDir = dir.toLowerCase();
+      if (normalizedDir !== "asc" && normalizedDir !== "desc") {
+        throw new Error(`Invalid orderBy direction "${dir}". Only 'asc' or 'desc' are allowed.`);
+      }
+      const safeDir = normalizedDir === "desc" ? "DESC" : "ASC";
+      if (col === "_count") {
+        orderClauses.push(`COUNT(*) ${safeDir}`);
+      } else if (col.startsWith("_")) {
+        if (!validAggAliases.has(col)) {
+          throw new Error(`Invalid orderBy column "${col}". Underscore-prefixed columns must match a requested aggregation alias.`);
+        }
+        orderClauses.push(`"${col}" ${safeDir}`);
+      } else {
+        orderClauses.push(`"${camelToSnake(col)}" ${safeDir}`);
+      }
+    }
+    if (orderClauses.length > 0) {
+      sql += ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+  }
+  if (options.limit !== undefined) {
+    allParams.push(options.limit);
+    sql += ` LIMIT $${allParams.length}`;
+  }
+  if (options.offset !== undefined) {
+    allParams.push(options.offset);
+    sql += ` OFFSET $${allParams.length}`;
+  }
+  const res = await executeQuery(queryFn, sql, allParams);
+  return res.rows.map((row) => {
+    const result = {};
+    for (const col of options.by) {
+      const snakeCol = camelToSnake(col);
+      result[col] = row[col] ?? row[snakeCol];
+    }
+    if (options._count !== undefined) {
+      if (options._count === true) {
+        result._count = Number(row._count ?? 0);
+      } else {
+        const countObj = {};
+        for (const col of Object.keys(options._count)) {
+          const snakeCol = camelToSnake(col);
+          countObj[col] = Number(row[`_count_${snakeCol}`] ?? 0);
+        }
+        result._count = countObj;
+      }
+    }
+    for (const [fn, aggOpt] of [
+      ["avg", options._avg],
+      ["sum", options._sum],
+      ["min", options._min],
+      ["max", options._max]
+    ]) {
+      if (!aggOpt)
+        continue;
+      const fnObj = {};
+      for (const col of Object.keys(aggOpt)) {
+        const snakeCol = camelToSnake(col);
+        const val = row[`_${fn}_${snakeCol}`];
+        fnObj[col] = val === null || val === undefined ? null : Number(val);
+      }
+      result[`_${fn}`] = fnObj;
+    }
+    return result;
+  });
+}
+
+// src/query/crud.ts
+function assertNonEmptyWhere(where, operation) {
+  if (Object.keys(where).length === 0) {
+    throw new Error(`${operation} requires a non-empty where clause. ` + "Passing an empty where object would affect all rows.");
+  }
+}
+async function get(queryFn, table, options) {
+  const columns = resolveSelectColumns(table, options?.select);
+  const result = buildSelect({
+    table: table._name,
+    columns,
+    where: options?.where,
+    orderBy: options?.orderBy,
+    limit: 1
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  if (res.rows.length === 0) {
+    return null;
+  }
+  return mapRow(res.rows[0]);
+}
+async function getOrThrow(queryFn, table, options) {
+  const row = await get(queryFn, table, options);
+  if (row === null) {
+    throw new NotFoundError(table._name);
+  }
+  return row;
+}
+async function list(queryFn, table, options) {
+  const columns = resolveSelectColumns(table, options?.select);
+  const result = buildSelect({
+    table: table._name,
+    columns,
+    where: options?.where,
+    orderBy: options?.orderBy,
+    limit: options?.limit,
+    offset: options?.offset,
+    cursor: options?.cursor,
+    take: options?.take
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  return mapRows(res.rows);
+}
+async function listAndCount(queryFn, table, options) {
+  const columns = resolveSelectColumns(table, options?.select);
+  const result = buildSelect({
+    table: table._name,
+    columns,
+    where: options?.where,
+    orderBy: options?.orderBy,
+    limit: options?.limit,
+    offset: options?.offset,
+    cursor: options?.cursor,
+    take: options?.take,
+    withCount: true
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  const rows = res.rows;
+  if (rows.length === 0) {
+    return { data: [], total: 0 };
+  }
+  const firstRow = rows[0];
+  const total = Number(firstRow.totalCount ?? 0);
+  const data = rows.map((row) => {
+    const { totalCount: _tc, total_count: _tc2, ...rest } = row;
+    return mapRow(rest);
+  });
+  return { data, total };
+}
+async function create(queryFn, table, options) {
+  const returningColumns = resolveSelectColumns(table, options.select);
+  const nowColumns = getTimestampColumns(table);
+  const result = buildInsert({
+    table: table._name,
+    data: options.data,
+    returning: returningColumns,
+    nowColumns
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  return mapRow(res.rows[0]);
+}
+async function createMany(queryFn, table, options) {
+  if (options.data.length === 0) {
+    return { count: 0 };
+  }
+  const nowColumns = getTimestampColumns(table);
+  const result = buildInsert({
+    table: table._name,
+    data: options.data,
+    nowColumns
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  return { count: res.rowCount };
+}
+async function createManyAndReturn(queryFn, table, options) {
+  if (options.data.length === 0) {
+    return [];
+  }
+  const returningColumns = resolveSelectColumns(table, options.select);
+  const nowColumns = getTimestampColumns(table);
+  const result = buildInsert({
+    table: table._name,
+    data: options.data,
+    returning: returningColumns,
+    nowColumns
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  return mapRows(res.rows);
+}
+async function update(queryFn, table, options) {
+  const returningColumns = resolveSelectColumns(table, options.select);
+  const nowColumns = getTimestampColumns(table);
+  const result = buildUpdate({
+    table: table._name,
+    data: options.data,
+    where: options.where,
+    returning: returningColumns,
+    nowColumns
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  if (res.rows.length === 0) {
+    throw new NotFoundError(table._name);
+  }
+  return mapRow(res.rows[0]);
+}
+async function updateMany(queryFn, table, options) {
+  assertNonEmptyWhere(options.where, "updateMany");
+  const nowColumns = getTimestampColumns(table);
+  const result = buildUpdate({
+    table: table._name,
+    data: options.data,
+    where: options.where,
+    nowColumns
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  return { count: res.rowCount };
+}
+async function upsert(queryFn, table, options) {
+  const returningColumns = resolveSelectColumns(table, options.select);
+  const nowColumns = getTimestampColumns(table);
+  const conflictColumns = Object.keys(options.where);
+  const updateColumns = Object.keys(options.update);
+  const result = buildInsert({
+    table: table._name,
+    data: options.create,
+    returning: returningColumns,
+    nowColumns,
+    onConflict: {
+      columns: conflictColumns,
+      action: "update",
+      updateColumns,
+      updateValues: options.update
+    }
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  return mapRow(res.rows[0]);
+}
+async function deleteOne(queryFn, table, options) {
+  const returningColumns = resolveSelectColumns(table, options.select);
+  const result = buildDelete({
+    table: table._name,
+    where: options.where,
+    returning: returningColumns
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  if (res.rows.length === 0) {
+    throw new NotFoundError(table._name);
+  }
+  return mapRow(res.rows[0]);
+}
+async function deleteMany(queryFn, table, options) {
+  assertNonEmptyWhere(options.where, "deleteMany");
+  const result = buildDelete({
+    table: table._name,
+    where: options.where
+  });
+  const res = await executeQuery(queryFn, result.sql, result.params);
+  return { count: res.rowCount };
+}
+
+// src/query/relation-loader.ts
+function resolvePkColumn(table) {
+  const pkCols = getPrimaryKeyColumns(table);
+  const first = pkCols[0];
+  return first !== undefined ? first : "id";
+}
+async function loadRelations(queryFn, primaryRows, relations, include, depth = 0, tablesRegistry, primaryTable) {
+  if (depth > 2 || primaryRows.length === 0) {
+    return primaryRows;
+  }
+  const toLoad = [];
+  for (const [key, value] of Object.entries(include)) {
+    if (value === undefined)
+      continue;
+    const rel = relations[key];
+    if (!rel)
+      continue;
+    toLoad.push({ key, def: rel, includeValue: value });
+  }
+  if (toLoad.length === 0) {
+    return primaryRows;
+  }
+  for (const { key: relName, def, includeValue } of toLoad) {
+    const target = def._target();
+    if (def._type === "one") {
+      await loadOneRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry);
+    } else if (def._through) {
+      await loadManyToManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable);
+    } else {
+      await loadManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable);
+    }
+  }
+  return primaryRows;
+}
+function findTargetRelations(target, tablesRegistry) {
+  if (!tablesRegistry)
+    return;
+  for (const entry of Object.values(tablesRegistry)) {
+    if (entry.table._name === target._name) {
+      return entry.relations;
+    }
+  }
+  return;
+}
+async function loadOneRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry) {
+  const fk = def._foreignKey;
+  if (!fk)
+    return;
+  const fkValues = new Set;
+  for (const row of primaryRows) {
+    const val = row[fk];
+    if (val !== null && val !== undefined) {
+      fkValues.add(val);
+    }
+  }
+  if (fkValues.size === 0) {
+    for (const row of primaryRows) {
+      row[relName] = null;
+    }
+    return;
+  }
+  const targetPk = resolvePkColumn(target);
+  const selectOpt = typeof includeValue === "object" ? includeValue.select : undefined;
+  const columns = resolveSelectColumns(target, selectOpt);
+  if (!columns.includes(targetPk)) {
+    columns.push(targetPk);
+  }
+  const query = buildSelect({
+    table: target._name,
+    columns,
+    where: { [targetPk]: { in: [...fkValues] } }
+  });
+  const res = await executeQuery(queryFn, query.sql, query.params);
+  const lookup = new Map;
+  for (const row of res.rows) {
+    const mapped = mapRow(row);
+    lookup.set(mapped[targetPk], mapped);
+  }
+  if (typeof includeValue === "object" && includeValue.include && depth < 2) {
+    const targetRelations = findTargetRelations(target, tablesRegistry);
+    if (targetRelations) {
+      const childRows = [...lookup.values()];
+      await loadRelations(queryFn, childRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target);
+    }
+  }
+  for (const row of primaryRows) {
+    const fkVal = row[fk];
+    row[relName] = lookup.get(fkVal) ?? null;
+  }
+}
+async function loadManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable) {
+  const fk = def._foreignKey;
+  if (!fk)
+    return;
+  const primaryPk = primaryTable ? resolvePkColumn(primaryTable) : "id";
+  const pkValues = new Set;
+  for (const row of primaryRows) {
+    const val = row[primaryPk];
+    if (val !== null && val !== undefined) {
+      pkValues.add(val);
+    }
+  }
+  if (pkValues.size === 0) {
+    for (const row of primaryRows) {
+      row[relName] = [];
+    }
+    return;
+  }
+  const selectOpt = typeof includeValue === "object" ? includeValue.select : undefined;
+  const columns = resolveSelectColumns(target, selectOpt);
+  if (!columns.includes(fk)) {
+    columns.push(fk);
+  }
+  const query = buildSelect({
+    table: target._name,
+    columns,
+    where: { [fk]: { in: [...pkValues] } }
+  });
+  const res = await executeQuery(queryFn, query.sql, query.params);
+  const lookup = new Map;
+  for (const row of res.rows) {
+    const mapped = mapRow(row);
+    const parentId = mapped[fk];
+    const existing = lookup.get(parentId);
+    if (existing) {
+      existing.push(mapped);
+    } else {
+      lookup.set(parentId, [mapped]);
+    }
+  }
+  if (typeof includeValue === "object" && includeValue.include && depth < 2) {
+    const targetRelations = findTargetRelations(target, tablesRegistry);
+    if (targetRelations) {
+      const allChildRows = [...lookup.values()].flat();
+      await loadRelations(queryFn, allChildRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target);
+    }
+  }
+  for (const row of primaryRows) {
+    const pkVal = row[primaryPk];
+    row[relName] = lookup.get(pkVal) ?? [];
+  }
+}
+async function loadManyToManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable) {
+  const through = def._through;
+  if (!through)
+    return;
+  const primaryPk = primaryTable ? resolvePkColumn(primaryTable) : "id";
+  const targetPk = resolvePkColumn(target);
+  const joinTable = through.table();
+  const thisKey = through.thisKey;
+  const thatKey = through.thatKey;
+  const pkValues = new Set;
+  for (const row of primaryRows) {
+    const val = row[primaryPk];
+    if (val !== null && val !== undefined) {
+      pkValues.add(val);
+    }
+  }
+  if (pkValues.size === 0) {
+    for (const row of primaryRows) {
+      row[relName] = [];
+    }
+    return;
+  }
+  const joinQuery = buildSelect({
+    table: joinTable._name,
+    columns: [thisKey, thatKey],
+    where: { [thisKey]: { in: [...pkValues] } }
+  });
+  const joinRes = await executeQuery(queryFn, joinQuery.sql, joinQuery.params);
+  const primaryToTargetIds = new Map;
+  const allTargetIds = new Set;
+  for (const row of joinRes.rows) {
+    const mapped = mapRow(row);
+    const primaryId = mapped[thisKey];
+    const targetId = mapped[thatKey];
+    if (targetId !== null && targetId !== undefined) {
+      allTargetIds.add(targetId);
+      const existing = primaryToTargetIds.get(primaryId);
+      if (existing) {
+        existing.push(targetId);
+      } else {
+        primaryToTargetIds.set(primaryId, [targetId]);
+      }
+    }
+  }
+  if (allTargetIds.size === 0) {
+    for (const row of primaryRows) {
+      row[relName] = [];
+    }
+    return;
+  }
+  const selectOpt = typeof includeValue === "object" ? includeValue.select : undefined;
+  const columns = resolveSelectColumns(target, selectOpt);
+  if (!columns.includes(targetPk)) {
+    columns.push(targetPk);
+  }
+  const targetQuery = buildSelect({
+    table: target._name,
+    columns,
+    where: { [targetPk]: { in: [...allTargetIds] } }
+  });
+  const targetRes = await executeQuery(queryFn, targetQuery.sql, targetQuery.params);
+  const targetLookup = new Map;
+  for (const row of targetRes.rows) {
+    const mapped = mapRow(row);
+    targetLookup.set(mapped[targetPk], mapped);
+  }
+  if (typeof includeValue === "object" && includeValue.include && depth < 2) {
+    const targetRelations = findTargetRelations(target, tablesRegistry);
+    if (targetRelations) {
+      const allTargetRows = [...targetLookup.values()];
+      await loadRelations(queryFn, allTargetRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target);
+    }
+  }
+  for (const row of primaryRows) {
+    const pkVal = row[primaryPk];
+    const targetIds = primaryToTargetIds.get(pkVal) ?? [];
+    const relatedRows = [];
+    for (const targetId of targetIds) {
+      const targetRow = targetLookup.get(targetId);
+      if (targetRow) {
+        relatedRows.push(targetRow);
+      }
+    }
+    row[relName] = relatedRows;
+  }
+}
+
+// src/client/postgres-driver.ts
+import postgresLib from "postgres";
+function isPostgresError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string";
+}
+function adaptPostgresError(error) {
+  if (isPostgresError(error)) {
+    const adapted = Object.assign(new Error(error.message), {
+      code: error.code,
+      message: error.message,
+      table: error.table_name,
+      column: error.column_name,
+      constraint: error.constraint_name,
+      detail: error.detail
+    });
+    throw adapted;
+  }
+  throw error;
+}
+function createPostgresDriver(url, pool) {
+  const sql = postgresLib(url, {
+    max: pool?.max ?? 10,
+    idle_timeout: pool?.idleTimeout !== undefined ? pool.idleTimeout / 1000 : 30,
+    connect_timeout: pool?.connectionTimeout !== undefined ? pool.connectionTimeout / 1000 : 10,
+    fetch_types: false
+  });
+  const queryFn = async (sqlStr, params) => {
+    try {
+      const result = await sql.unsafe(sqlStr, params);
+      const rows = result.map((row) => {
+        const mapped = {};
+        for (const [key, value] of Object.entries(row)) {
+          mapped[key] = coerceValue(value);
+        }
+        return mapped;
+      });
+      return {
+        rows,
+        rowCount: result.count ?? rows.length
+      };
+    } catch (error) {
+      adaptPostgresError(error);
+    }
+  };
+  return {
+    queryFn,
+    async close() {
+      await sql.end();
+    },
+    async isHealthy() {
+      try {
+        const healthCheckTimeout = pool?.healthCheckTimeout ?? 5000;
+        const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error("Health check timed out")), healthCheckTimeout));
+        await Promise.race([sql`SELECT 1`, timeout]);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+function coerceValue(value) {
+  if (typeof value === "string" && isTimestampString(value)) {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) {
+      return date;
+    }
+  }
+  return value;
+}
+function isTimestampString(value) {
+  return /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(value);
+}
+
+// src/client/tenant-graph.ts
+function computeTenantGraph(registry) {
+  const entries = Object.entries(registry);
+  const tableNameToKey = new Map;
+  for (const [key, entry] of entries) {
+    tableNameToKey.set(entry.table._name, key);
+  }
+  let root = null;
+  const directlyScoped = [];
+  const shared = [];
+  for (const [key, entry] of entries) {
+    if (entry.table._shared) {
+      shared.push(key);
+      continue;
+    }
+    const columns = entry.table._columns;
+    for (const colKey of Object.keys(columns)) {
+      const col = columns[colKey];
+      if (col._meta.isTenant && col._meta.references) {
+        if (!directlyScoped.includes(key)) {
+          directlyScoped.push(key);
+        }
+        const rootTableName = col._meta.references.table;
+        const rootKey = tableNameToKey.get(rootTableName);
+        if (rootKey && root === null) {
+          root = rootKey;
+        }
+      }
+    }
+  }
+  const scopedTableNames = new Set;
+  if (root !== null) {
+    const rootEntry = registry[root];
+    if (rootEntry) {
+      scopedTableNames.add(rootEntry.table._name);
+    }
+  }
+  for (const key of directlyScoped) {
+    const entry = registry[key];
+    if (entry) {
+      scopedTableNames.add(entry.table._name);
+    }
+  }
+  const indirectlyScoped = [];
+  const indirectlyScopedNames = new Set;
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [key, entry] of entries) {
+      if (key === root || directlyScoped.includes(key) || shared.includes(key) || indirectlyScopedNames.has(entry.table._name)) {
+        continue;
+      }
+      const columns = entry.table._columns;
+      for (const colKey of Object.keys(columns)) {
+        const col = columns[colKey];
+        if (col._meta.references && !col._meta.isTenant) {
+          const refTable = col._meta.references.table;
+          if (scopedTableNames.has(refTable) || indirectlyScopedNames.has(refTable)) {
+            indirectlyScoped.push(key);
+            indirectlyScopedNames.add(entry.table._name);
+            scopedTableNames.add(entry.table._name);
+            changed = true;
+            break;
+          }
+        }
+      }
+    }
+  }
+  return {
+    root,
+    directlyScoped,
+    indirectlyScoped,
+    shared
+  };
+}
+
+// src/client/database.ts
+function isReadQuery(sqlStr) {
+  let normalized = sqlStr.trim();
+  while (normalized.startsWith("--") || normalized.startsWith("/*") || normalized.startsWith("//")) {
+    if (normalized.startsWith("--")) {
+      const newlineIdx = normalized.indexOf(`
+`);
+      if (newlineIdx === -1)
+        return false;
+      normalized = normalized.slice(newlineIdx + 1).trim();
+    } else if (normalized.startsWith("/*")) {
+      const endIdx = normalized.indexOf("*/");
+      if (endIdx === -1)
+        return false;
+      normalized = normalized.slice(endIdx + 2).trim();
+    } else if (normalized.startsWith("//")) {
+      const newlineIdx = normalized.indexOf(`
+`);
+      if (newlineIdx === -1)
+        return false;
+      normalized = normalized.slice(newlineIdx + 1).trim();
+    }
+  }
+  const upper = normalized.toUpperCase();
+  if (upper.startsWith("WITH ")) {
+    const hasInsert = /\bINSERT\s+INTO\b/is.test(normalized);
+    const hasUpdate = /\bUPDATE\b/is.test(normalized);
+    const hasDelete = /\bDELETE\s+FROM\b/is.test(normalized);
+    if (hasInsert || hasUpdate || hasDelete) {
+      return false;
+    }
+    const selectMatch = normalized.match(/\bSELECT\s/is);
+    return selectMatch !== null;
+  }
+  if (/\bFOR\s+(NO\s+KEY\s+)?(UPDATE|KEY\s+SHARE|SHARE)\b/is.test(upper)) {
+    return false;
+  }
+  if (upper.startsWith("SELECT INTO") || /\bSELECT\s+.+\s+INTO\b/.test(upper)) {
+    return false;
+  }
+  return upper.startsWith("SELECT");
+}
+function resolveTable(tables, name) {
+  const entry = tables[name];
+  if (!entry) {
+    throw new Error(`Table "${name}" is not registered in the database.`);
+  }
+  return entry;
+}
+function createDb(options) {
+  const { tables, log } = options;
+  const tenantGraph = computeTenantGraph(tables);
+  if (log && tenantGraph.root !== null) {
+    const allScoped = new Set([
+      ...tenantGraph.root !== null ? [tenantGraph.root] : [],
+      ...tenantGraph.directlyScoped,
+      ...tenantGraph.indirectlyScoped,
+      ...tenantGraph.shared
+    ]);
+    for (const [key, entry] of Object.entries(tables)) {
+      if (!allScoped.has(key)) {
+        log(`[vertz/db] Table "${entry.table._name}" has no tenant path and is not marked .shared(). ` + "It will not be automatically scoped to a tenant.");
+      }
+    }
+  }
+  const tablesRegistry = tables;
+  let driver = null;
+  let replicaDrivers = [];
+  let replicaIndex = 0;
+  const queryFn = (() => {
+    if (options._queryFn) {
+      return options._queryFn;
+    }
+    if (options.url) {
+      driver = createPostgresDriver(options.url, options.pool);
+      const replicas = options.pool?.replicas;
+      if (replicas && replicas.length > 0) {
+        replicaDrivers = replicas.map((replicaUrl) => createPostgresDriver(replicaUrl, options.pool));
+      }
+      return async (sqlStr, params) => {
+        if (replicaDrivers.length === 0) {
+          return driver.queryFn(sqlStr, params);
+        }
+        if (isReadQuery(sqlStr)) {
+          const targetReplica = replicaDrivers[replicaIndex];
+          replicaIndex = (replicaIndex + 1) % replicaDrivers.length;
+          try {
+            return await targetReplica.queryFn(sqlStr, params);
+          } catch (err) {
+            console.warn("[vertz/db] replica query failed, falling back to primary:", err.message);
+          }
+        }
+        return driver.queryFn(sqlStr, params);
+      };
+    }
+    return async () => {
+      throw new Error("db.query() requires a connected postgres driver. " + "Provide a `url` to connect to PostgreSQL, or `_queryFn` for testing.");
+    };
+  })();
+  return {
+    _tables: tables,
+    $tenantGraph: tenantGraph,
+    async query(fragment) {
+      return executeQuery(queryFn, fragment.sql, fragment.params);
+    },
+    async close() {
+      if (driver) {
+        await driver.close();
+      }
+      await Promise.all(replicaDrivers.map((r) => r.close()));
+    },
+    async isHealthy() {
+      if (driver) {
+        return driver.isHealthy();
+      }
+      return true;
+    },
+    async get(name, opts) {
+      const entry = resolveTable(tables, name);
+      const result = await get(queryFn, entry.table, opts);
+      if (result !== null && opts?.include) {
+        const rows = await loadRelations(queryFn, [result], entry.relations, opts.include, 0, tablesRegistry, entry.table);
+        return rows[0] ?? null;
+      }
+      return result;
+    },
+    async getOrThrow(name, opts) {
+      const entry = resolveTable(tables, name);
+      const result = await getOrThrow(queryFn, entry.table, opts);
+      if (opts?.include) {
+        const rows = await loadRelations(queryFn, [result], entry.relations, opts.include, 0, tablesRegistry, entry.table);
+        return rows[0];
+      }
+      return result;
+    },
+    async list(name, opts) {
+      const entry = resolveTable(tables, name);
+      const results = await list(queryFn, entry.table, opts);
+      if (opts?.include && results.length > 0) {
+        return loadRelations(queryFn, results, entry.relations, opts.include, 0, tablesRegistry, entry.table);
+      }
+      return results;
+    },
+    async listAndCount(name, opts) {
+      const entry = resolveTable(tables, name);
+      const { data, total } = await listAndCount(queryFn, entry.table, opts);
+      if (opts?.include && data.length > 0) {
+        const withRelations = await loadRelations(queryFn, data, entry.relations, opts.include, 0, tablesRegistry, entry.table);
+        return { data: withRelations, total };
+      }
+      return { data, total };
+    },
+    get findOne() {
+      return this.get;
+    },
+    get findOneOrThrow() {
+      return this.getOrThrow;
+    },
+    get findMany() {
+      return this.list;
+    },
+    get findManyAndCount() {
+      return this.listAndCount;
+    },
+    async create(name, opts) {
+      const entry = resolveTable(tables, name);
+      return create(queryFn, entry.table, opts);
+    },
+    async createMany(name, opts) {
+      const entry = resolveTable(tables, name);
+      return createMany(queryFn, entry.table, opts);
+    },
+    async createManyAndReturn(name, opts) {
+      const entry = resolveTable(tables, name);
+      return createManyAndReturn(queryFn, entry.table, opts);
+    },
+    async update(name, opts) {
+      const entry = resolveTable(tables, name);
+      return update(queryFn, entry.table, opts);
+    },
+    async updateMany(name, opts) {
+      const entry = resolveTable(tables, name);
+      return updateMany(queryFn, entry.table, opts);
+    },
+    async upsert(name, opts) {
+      const entry = resolveTable(tables, name);
+      return upsert(queryFn, entry.table, opts);
+    },
+    async delete(name, opts) {
+      const entry = resolveTable(tables, name);
+      return deleteOne(queryFn, entry.table, opts);
+    },
+    async deleteMany(name, opts) {
+      const entry = resolveTable(tables, name);
+      return deleteMany(queryFn, entry.table, opts);
+    },
+    async count(name, opts) {
+      const entry = resolveTable(tables, name);
+      return count(queryFn, entry.table, opts);
+    },
+    async aggregate(name, opts) {
+      const entry = resolveTable(tables, name);
+      return aggregate(queryFn, entry.table, opts);
+    },
+    async groupBy(name, opts) {
+      const entry = resolveTable(tables, name);
+      return groupBy(queryFn, entry.table, opts);
+    }
+  };
+}
+// src/schema/column.ts
+function cloneWith(source, metaOverrides) {
+  return createColumnWithMeta({ ...source._meta, ...metaOverrides });
+}
+function createColumnWithMeta(meta) {
+  const col = {
+    _meta: meta,
+    primary() {
+      return cloneWith(this, { primary: true, hasDefault: true });
+    },
+    unique() {
+      return cloneWith(this, { unique: true });
+    },
+    nullable() {
+      return cloneWith(this, { nullable: true });
+    },
+    default(value) {
+      return cloneWith(this, { hasDefault: true, defaultValue: value });
+    },
+    sensitive() {
+      return cloneWith(this, { sensitive: true });
+    },
+    hidden() {
+      return cloneWith(this, { hidden: true });
+    },
+    check(sql) {
+      return cloneWith(this, { check: sql });
+    },
+    references(table, column) {
+      return cloneWith(this, {
+        references: { table, column: column ?? "id" }
+      });
+    }
+  };
+  return col;
+}
+function defaultMeta(sqlType) {
+  return {
+    sqlType,
+    primary: false,
+    unique: false,
+    nullable: false,
+    hasDefault: false,
+    sensitive: false,
+    hidden: false,
+    isTenant: false,
+    references: null,
+    check: null
+  };
+}
+function createColumn(sqlType, extra) {
+  return createColumnWithMeta({
+    ...defaultMeta(sqlType),
+    ...extra
+  });
+}
+function createSerialColumn() {
+  return createColumnWithMeta({
+    sqlType: "serial",
+    primary: false,
+    unique: false,
+    nullable: false,
+    hasDefault: true,
+    sensitive: false,
+    hidden: false,
+    isTenant: false,
+    references: null,
+    check: null
+  });
+}
+function createTenantColumn(targetTableName) {
+  return createColumnWithMeta({
+    sqlType: "uuid",
+    primary: false,
+    unique: false,
+    nullable: false,
+    hasDefault: false,
+    sensitive: false,
+    hidden: false,
+    isTenant: true,
+    references: { table: targetTableName, column: "id" },
+    check: null
+  });
+}
+
+// src/schema/relation.ts
+function createOneRelation(target, foreignKey) {
+  return {
+    _type: "one",
+    _target: target,
+    _foreignKey: foreignKey,
+    _through: null
+  };
+}
+function createManyRelation(target, foreignKey) {
+  return {
+    _type: "many",
+    _target: target,
+    _foreignKey: foreignKey ?? null,
+    _through: null,
+    through(joinTable, thisKey, thatKey) {
+      return {
+        _type: "many",
+        _target: target,
+        _foreignKey: null,
+        _through: {
+          table: joinTable,
+          thisKey,
+          thatKey
+        }
+      };
+    }
+  };
+}
+
+// src/schema/table.ts
+function createIndex(columns) {
+  return {
+    columns: Array.isArray(columns) ? columns : [columns]
+  };
+}
+function createTable(name, columns, options) {
+  return createTableInternal(name, columns, options?.indexes ?? [], false);
+}
+function createTableInternal(name, columns, indexes, shared) {
+  const table = {
+    _name: name,
+    _columns: columns,
+    _indexes: indexes,
+    _shared: shared,
+    get $infer() {
+      return;
+    },
+    get $infer_all() {
+      return;
+    },
+    get $insert() {
+      return;
+    },
+    get $update() {
+      return;
+    },
+    get $not_sensitive() {
+      return;
+    },
+    get $not_hidden() {
+      return;
+    },
+    shared() {
+      return createTableInternal(name, columns, indexes, true);
+    }
+  };
+  return table;
+}
+
+// src/d.ts
+var d = {
+  uuid: () => createColumn("uuid"),
+  text: () => createColumn("text"),
+  varchar: (length) => createColumn("varchar", { length }),
+  email: () => createColumn("text", { format: "email" }),
+  boolean: () => createColumn("boolean"),
+  integer: () => createColumn("integer"),
+  bigint: () => createColumn("bigint"),
+  decimal: (precision, scale) => createColumn("decimal", { precision, scale }),
+  real: () => createColumn("real"),
+  doublePrecision: () => createColumn("double precision"),
+  serial: () => createSerialColumn(),
+  timestamp: () => createColumn("timestamp with time zone"),
+  date: () => createColumn("date"),
+  time: () => createColumn("time"),
+  jsonb: (opts) => createColumn("jsonb", opts?.validator ? { validator: opts.validator } : {}),
+  textArray: () => createColumn("text[]"),
+  integerArray: () => createColumn("integer[]"),
+  enum: (name, valuesOrSchema) => {
+    const values = !Array.isArray(valuesOrSchema) && typeof valuesOrSchema.values !== "undefined" ? valuesOrSchema.values : valuesOrSchema;
+    return createColumn("enum", {
+      enumName: name,
+      enumValues: values
+    });
+  },
+  tenant: (targetTable) => createTenantColumn(targetTable._name),
+  table: (name, columns, options) => createTable(name, columns, options),
+  index: (columns) => createIndex(columns),
+  ref: {
+    one: (target, foreignKey) => createOneRelation(target, foreignKey),
+    many: (target, foreignKey) => createManyRelation(target, foreignKey)
+  },
+  entry: (table, relations = {}) => ({
+    table,
+    relations
+  })
+};
+// src/errors/error-codes.ts
+var DbErrorCode = {
+  UNIQUE_VIOLATION: "23505",
+  FOREIGN_KEY_VIOLATION: "23503",
+  NOT_NULL_VIOLATION: "23502",
+  CHECK_VIOLATION: "23514",
+  EXCLUSION_VIOLATION: "23P01",
+  SERIALIZATION_FAILURE: "40001",
+  DEADLOCK_DETECTED: "40P01",
+  CONNECTION_EXCEPTION: "08000",
+  CONNECTION_DOES_NOT_EXIST: "08003",
+  CONNECTION_FAILURE: "08006",
+  NOT_FOUND: "NOT_FOUND",
+  CONNECTION_ERROR: "CONNECTION_ERROR",
+  POOL_EXHAUSTED: "POOL_EXHAUSTED"
+};
+var PgCodeToName = Object.fromEntries(Object.entries(DbErrorCode).map(([name, pgCode]) => [pgCode, name]));
+function resolveErrorCode(pgCode) {
+  return PgCodeToName[pgCode];
+}
+// src/errors/http-adapter.ts
+function dbErrorToHttpError(error) {
+  const body = error.toJSON();
+  if (error instanceof UniqueConstraintError) {
+    return { status: 409, body };
+  }
+  if (error instanceof NotFoundError) {
+    return { status: 404, body };
+  }
+  if (error instanceof ForeignKeyError) {
+    return { status: 422, body };
+  }
+  if (error instanceof NotNullError) {
+    return { status: 422, body };
+  }
+  if (error instanceof CheckConstraintError) {
+    return { status: 422, body };
+  }
+  if (error instanceof ConnectionError) {
+    return { status: 503, body };
+  }
+  return { status: 500, body };
+}
+// src/schema/registry.ts
+function createRegistry(tables, relationsCallback) {
+  const lookup = (name) => tables[name];
+  const ref = new Proxy({}, {
+    get(_target, _sourceKey) {
+      return {
+        one(targetName, foreignKey) {
+          return createOneRelation(() => lookup(targetName), foreignKey);
+        },
+        many(targetName, foreignKey) {
+          return createManyRelation(() => lookup(targetName), foreignKey);
+        }
+      };
+    }
+  });
+  const relationsMap = relationsCallback(ref);
+  const relMap = relationsMap;
+  const result = {};
+  for (const key of Object.keys(tables)) {
+    result[key] = {
+      table: lookup(key),
+      relations: relMap[key] ?? {}
+    };
+  }
+  return result;
+}
+// src/schema/enum-registry.ts
+function createEnumRegistry(definitions) {
+  const registry = {};
+  for (const [name, values] of Object.entries(definitions)) {
+    registry[name] = { name, values };
+  }
+  return registry;
+}
+// src/codegen/type-gen.ts
+function fieldTypeToTs(field) {
+  switch (field.type) {
+    case "string":
+    case "uuid":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "date":
+      return "Date";
+    case "json":
+      return "unknown";
+    case "enum":
+      return field.enumName || "string";
+    default:
+      return "unknown";
+  }
+}
+function generateTypes(domain) {
+  const { name, fields, relations } = domain;
+  const pascalName = name.charAt(0).toUpperCase() + name.slice(1);
+  const lines = [];
+  for (const field of Object.values(fields)) {
+    if (field.type === "enum" && field.enumName && field.enumValues) {
+      lines.push(`enum ${field.enumName} {`);
+      for (const value of field.enumValues) {
+        lines.push(`  ${value.toUpperCase()} = '${value}',`);
+      }
+      lines.push("}");
+      lines.push("");
+    }
+  }
+  lines.push(`interface ${pascalName} {`);
+  for (const [fieldName, field] of Object.entries(fields)) {
+    const tsType = fieldTypeToTs(field);
+    const optional = field.required === false ? "?" : "";
+    lines.push(`  ${fieldName}${optional}: ${tsType};`);
+  }
+  if (relations) {
+    for (const [relName, rel] of Object.entries(relations)) {
+      if (rel.type === "belongsTo") {
+        const targetPascal = rel.target.charAt(0).toUpperCase() + rel.target.slice(1);
+        lines.push(`  ${relName}: () => Promise<${targetPascal} | null>;`);
+      } else if (rel.type === "hasMany") {
+        const targetPascal = rel.target.charAt(0).toUpperCase() + rel.target.slice(1);
+        lines.push(`  ${relName}: () => Promise<${targetPascal}[]>;`);
+      }
+    }
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push(`interface Create${pascalName}Input {`);
+  for (const [fieldName, field] of Object.entries(fields)) {
+    if (field.primary)
+      continue;
+    const tsType = fieldTypeToTs(field);
+    if (field.required !== false) {
+      lines.push(`  ${fieldName}: ${tsType};`);
+    }
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push(`interface Update${pascalName}Input {`);
+  for (const [fieldName, field] of Object.entries(fields)) {
+    if (field.primary)
+      continue;
+    const tsType = fieldTypeToTs(field);
+    lines.push(`  ${fieldName}?: ${tsType};`);
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push(`interface ${pascalName}Where {`);
+  for (const [fieldName, field] of Object.entries(fields)) {
+    const tsType = fieldTypeToTs(field);
+    lines.push(`  ${fieldName}?: ${tsType};`);
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push(`interface ${pascalName}OrderBy {`);
+  for (const fieldName of Object.keys(fields)) {
+    lines.push(`  ${fieldName}?: 'asc' | 'desc';`);
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push(`interface List${pascalName}Params {`);
+  lines.push(`  where?: ${pascalName}Where;`);
+  lines.push(`  orderBy?: ${pascalName}OrderBy;`);
+  lines.push(`  limit?: number;`);
+  lines.push(`  offset?: number;`);
+  lines.push("}");
+  lines.push("");
+  lines.push(`interface ${pascalName}Client {`);
+  lines.push(`  list(): Promise<${pascalName}[]>;`);
+  lines.push(`  list(params?: List${pascalName}Params): Promise<${pascalName}[]>;`);
+  let idField = "id";
+  for (const [fieldName, field] of Object.entries(fields)) {
+    if (field.primary) {
+      idField = fieldName;
+      break;
+    }
+  }
+  lines.push(`  get(${idField}: string): Promise<${pascalName} | null>;`);
+  lines.push(`  create(data: Create${pascalName}Input): Promise<${pascalName}>;`);
+  lines.push(`  update(${idField}: string, data: Update${pascalName}Input): Promise<${pascalName}>;`);
+  lines.push(`  delete(${idField}: string): Promise<void>;`);
+  lines.push("}");
+  return lines.join(`
+`);
+}
+// src/codegen/client-gen.ts
+function generateClient(domains) {
+  const lines = [];
+  for (const domain of domains) {
+    const types = generateTypes(domain);
+    lines.push(types);
+    lines.push("");
+  }
+  lines.push("export const db = {");
+  for (const domain of domains) {
+    const { name, fields, relations } = domain;
+    const pascalName = name.charAt(0).toUpperCase() + name.slice(1);
+    let idField = "id";
+    for (const [fieldName, field] of Object.entries(fields)) {
+      if (field.primary) {
+        idField = fieldName;
+        break;
+      }
+    }
+    lines.push(`  ${name}: {`);
+    lines.push(`    list: (params?: List${pascalName}Params) => Promise<${pascalName}[]>,`);
+    lines.push(`    get: (${idField}: string) => Promise<${pascalName} | null>,`);
+    lines.push(`    create: (data: Create${pascalName}Input) => Promise<${pascalName}>,`);
+    lines.push(`    update: (${idField}: string, data: Update${pascalName}Input) => Promise<${pascalName}>,`);
+    lines.push(`    delete: (${idField}: string) => Promise<void>,`);
+    if (relations) {
+      for (const [relName, rel] of Object.entries(relations)) {
+        if (rel.type === "belongsTo") {
+          const targetPascal = rel.target.charAt(0).toUpperCase() + rel.target.slice(1);
+          const relParamName = `${name}Id`;
+          lines.push(`    ${relName}: {`);
+          lines.push(`      get(${relParamName}: string): Promise<${targetPascal} | null>,`);
+          lines.push(`    },`);
+        }
+      }
+    }
+    lines.push(`  },`);
+  }
+  lines.push("} as const;");
+  return lines.join(`
+`);
+}
+// src/domain.ts
+function defineDomain(name, config) {
+  return {
+    name,
+    fields: config.fields,
+    relations: config.relations
+  };
+}
+export {
+  resolveErrorCode,
+  push,
+  parsePgError,
+  migrateStatus,
+  migrateDev,
+  migrateDeploy,
+  generateTypes,
+  generateClient,
+  formatDiagnostic,
+  explainError,
+  diagnoseError,
+  defineDomain,
+  dbErrorToHttpError,
+  d,
+  createRegistry,
+  createEnumRegistry,
+  createDb,
+  computeTenantGraph,
+  UniqueConstraintError,
+  PgCodeToName,
+  NotNullError,
+  NotFoundError,
+  ForeignKeyError,
+  DbErrorCode,
+  DbError,
+  ConnectionPoolExhaustedError,
+  ConnectionError,
+  CheckConstraintError
+};