@vertz/db 0.2.15 → 0.2.17

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   buildSelect,
   buildUpdate,
   buildWhere
-} from "./shared/chunk-pxjcpnpx.js";
+} from "./shared/chunk-3a9nybt2.js";
 import {
   CheckConstraintError,
   ConnectionError,
@@ -47,33 +47,31 @@ import {
 import {
   createD1Adapter,
   createD1Driver
-} from "./shared/chunk-ndxe1h28.js";
+} from "./shared/chunk-tnaf4hbj.js";
 import {
   generateId
-} from "./shared/chunk-pkv8w501.js";
+} from "./shared/chunk-ed82s3sa.js";
 // src/adapters/database-bridge-adapter.ts
 function createDatabaseBridgeAdapter(db, tableName) {
   const delegate = db[tableName];
   return {
-    async get(id) {
-      const result = await delegate.get({ where: { id } });
+    async get(id, options) {
+      const result = await delegate.get({
+        where: { id },
+        ...options?.include && { include: options.include }
+      });
       if (!result.ok) {
         return null;
       }
       return result.data;
     },
     async list(options) {
-      const dbOptions = {};
-      if (options?.where) {
-        dbOptions.where = options.where;
-      }
-      if (options?.orderBy) {
-        dbOptions.orderBy = options.orderBy;
-      }
-      if (options?.limit !== undefined) {
-        dbOptions.limit = options.limit;
-      }
-      const result = await delegate.listAndCount(dbOptions);
+      const result = await delegate.listAndCount({
+        ...options?.where && { where: options.where },
+        ...options?.orderBy && { orderBy: options.orderBy },
+        ...options?.limit !== undefined && { limit: options.limit },
+        ...options?.include && { include: options.include }
+      });
       if (!result.ok) {
         throw result.error;
       }
@@ -1614,10 +1612,32 @@ function resolvePkColumn(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) {
+var MAX_RELATION_QUERY_BUDGET = 50;
+var DEFAULT_RELATION_LIMIT = 100;
+var GLOBAL_RELATION_ROW_LIMIT = 1e4;
+function safeMergeWhere(batchWhere, userWhere) {
+  if (!userWhere)
+    return batchWhere;
+  const merged = { ...batchWhere };
+  for (const [key, value] of Object.entries(userWhere)) {
+    if (!(key in batchWhere)) {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+function resolveEffectiveLimit(includeValue) {
+  const userLimit = typeof includeValue === "object" ? includeValue.limit : undefined;
+  if (typeof userLimit === "number" && userLimit > 0) {
+    return userLimit;
+  }
+  return DEFAULT_RELATION_LIMIT;
+}
+async function loadRelations(queryFn, primaryRows, relations, include, depth = 0, tablesRegistry, primaryTable, queryBudget) {
+  if (depth > 3 || primaryRows.length === 0) {
     return primaryRows;
   }
+  const budget = queryBudget ?? { remaining: MAX_RELATION_QUERY_BUDGET };
   const toLoad = [];
   for (const [key, value] of Object.entries(include)) {
     if (value === undefined)
@@ -1633,11 +1653,11 @@ async function loadRelations(queryFn, primaryRows, relations, include, depth = 0
   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);
+      await loadOneRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, budget);
     } else if (def._through) {
-      await loadManyToManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable);
+      await loadManyToManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable, budget);
     } else {
-      await loadManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable);
+      await loadManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable, budget);
     }
   }
   return primaryRows;
@@ -1652,7 +1672,7 @@ function findTargetRelations(target, tablesRegistry) {
   }
   return;
 }
-async function loadOneRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry) {
+async function loadOneRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, queryBudget) {
   const fk = def._foreignKey;
   if (!fk)
     return;
@@ -1675,22 +1695,29 @@ async function loadOneRelation(queryFn, primaryRows, def, target, relName, inclu
   if (!columns.includes(targetPk)) {
     columns.push(targetPk);
   }
+  if (queryBudget && queryBudget.remaining <= 0) {
+    throw new Error(`Relation query budget exceeded (max ${MAX_RELATION_QUERY_BUDGET} queries). ` + "Reduce include depth or number of included relations.");
+  }
+  const userWhere = typeof includeValue === "object" ? includeValue.where : undefined;
+  const batchWhere = safeMergeWhere({ [targetPk]: { in: [...fkValues] } }, userWhere);
   const query = buildSelect({
     table: target._name,
     columns,
-    where: { [targetPk]: { in: [...fkValues] } }
+    where: batchWhere
   });
+  if (queryBudget)
+    queryBudget.remaining--;
   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) {
+  if (typeof includeValue === "object" && includeValue.include && depth < 3) {
     const targetRelations = findTargetRelations(target, tablesRegistry);
     if (targetRelations) {
       const childRows = [...lookup.values()];
-      await loadRelations(queryFn, childRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target);
+      await loadRelations(queryFn, childRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target, queryBudget);
     }
   }
   for (const row of primaryRows) {
@@ -1698,7 +1725,7 @@ async function loadOneRelation(queryFn, primaryRows, def, target, relName, inclu
     row[relName] = lookup.get(fkVal) ?? null;
   }
 }
-async function loadManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable) {
+async function loadManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable, queryBudget) {
   const fk = def._foreignKey;
   if (!fk)
     return;
@@ -1721,11 +1748,21 @@ async function loadManyRelation(queryFn, primaryRows, def, target, relName, incl
   if (!columns.includes(fk)) {
     columns.push(fk);
   }
+  const userWhere = typeof includeValue === "object" ? includeValue.where : undefined;
+  const batchWhere = safeMergeWhere({ [fk]: { in: [...pkValues] } }, userWhere);
+  const userOrderBy = typeof includeValue === "object" ? includeValue.orderBy : undefined;
+  if (queryBudget && queryBudget.remaining <= 0) {
+    throw new Error(`Relation query budget exceeded (max ${MAX_RELATION_QUERY_BUDGET} queries). ` + "Reduce include depth or number of included relations.");
+  }
   const query = buildSelect({
     table: target._name,
     columns,
-    where: { [fk]: { in: [...pkValues] } }
+    where: batchWhere,
+    orderBy: userOrderBy,
+    limit: GLOBAL_RELATION_ROW_LIMIT
   });
+  if (queryBudget)
+    queryBudget.remaining--;
   const res = await executeQuery(queryFn, query.sql, query.params);
   const lookup = new Map;
   for (const row of res.rows) {
@@ -1738,11 +1775,17 @@ async function loadManyRelation(queryFn, primaryRows, def, target, relName, incl
       lookup.set(parentId, [mapped]);
     }
   }
-  if (typeof includeValue === "object" && includeValue.include && depth < 2) {
+  const effectiveLimit = resolveEffectiveLimit(includeValue);
+  for (const [parentId, rows] of lookup) {
+    if (rows.length > effectiveLimit) {
+      lookup.set(parentId, rows.slice(0, effectiveLimit));
+    }
+  }
+  if (typeof includeValue === "object" && includeValue.include && depth < 3) {
     const targetRelations = findTargetRelations(target, tablesRegistry);
     if (targetRelations) {
       const allChildRows = [...lookup.values()].flat();
-      await loadRelations(queryFn, allChildRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target);
+      await loadRelations(queryFn, allChildRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target, queryBudget);
     }
   }
   for (const row of primaryRows) {
@@ -1750,7 +1793,7 @@ async function loadManyRelation(queryFn, primaryRows, def, target, relName, incl
     row[relName] = lookup.get(pkVal) ?? [];
   }
 }
-async function loadManyToManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable) {
+async function loadManyToManyRelation(queryFn, primaryRows, def, target, relName, includeValue, depth, tablesRegistry, primaryTable, queryBudget) {
   const through = def._through;
   if (!through)
     return;
@@ -1772,11 +1815,16 @@ async function loadManyToManyRelation(queryFn, primaryRows, def, target, relName
     }
     return;
   }
+  if (queryBudget && queryBudget.remaining <= 0) {
+    throw new Error(`Relation query budget exceeded (max ${MAX_RELATION_QUERY_BUDGET} queries). ` + "Reduce include depth or number of included relations.");
+  }
   const joinQuery = buildSelect({
     table: joinTable._name,
     columns: [thisKey, thatKey],
     where: { [thisKey]: { in: [...pkValues] } }
   });
+  if (queryBudget)
+    queryBudget.remaining--;
   const joinRes = await executeQuery(queryFn, joinQuery.sql, joinQuery.params);
   const primaryToTargetIds = new Map;
   const allTargetIds = new Set;
@@ -1805,22 +1853,32 @@ async function loadManyToManyRelation(queryFn, primaryRows, def, target, relName
   if (!columns.includes(targetPk)) {
     columns.push(targetPk);
   }
+  const userWhere = typeof includeValue === "object" ? includeValue.where : undefined;
+  const targetWhere = safeMergeWhere({ [targetPk]: { in: [...allTargetIds] } }, userWhere);
+  const userOrderBy = typeof includeValue === "object" ? includeValue.orderBy : undefined;
+  if (queryBudget && queryBudget.remaining <= 0) {
+    throw new Error(`Relation query budget exceeded (max ${MAX_RELATION_QUERY_BUDGET} queries). ` + "Reduce include depth or number of included relations.");
+  }
   const targetQuery = buildSelect({
     table: target._name,
     columns,
-    where: { [targetPk]: { in: [...allTargetIds] } }
+    where: targetWhere,
+    orderBy: userOrderBy,
+    limit: GLOBAL_RELATION_ROW_LIMIT
   });
+  if (queryBudget)
+    queryBudget.remaining--;
   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) {
+  if (typeof includeValue === "object" && includeValue.include && depth < 3) {
     const targetRelations = findTargetRelations(target, tablesRegistry);
     if (targetRelations) {
       const allTargetRows = [...targetLookup.values()];
-      await loadRelations(queryFn, allTargetRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target);
+      await loadRelations(queryFn, allTargetRows, targetRelations, includeValue.include, depth + 1, tablesRegistry, target, queryBudget);
     }
   }
   for (const row of primaryRows) {
@@ -2058,104 +2116,15 @@ function resolveModel(models, name) {
   }
   return entry;
 }
-var RESERVED_MODEL_NAMES = new Set(["query", "close", "isHealthy", "_internals"]);
-function createDb(options) {
-  const { models, log, dialect } = options;
-  for (const key of Object.keys(models)) {
-    if (RESERVED_MODEL_NAMES.has(key)) {
-      throw new Error(`Model name "${key}" is reserved. Choose a different name for this model. ` + `Reserved names: ${[...RESERVED_MODEL_NAMES].join(", ")}`);
-    }
-  }
-  if (dialect === "sqlite") {
-    if (!options.d1) {
-      throw new Error("SQLite dialect requires a D1 binding");
-    }
-    if (options.url) {
-      throw new Error("SQLite dialect uses D1, not a connection URL");
-    }
-  }
-  const dialectObj = dialect === "sqlite" ? defaultSqliteDialect : defaultPostgresDialect;
-  const tenantGraph = computeTenantGraph(models);
-  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(models)) {
-      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 modelsRegistry = models;
-  let driver = null;
-  let sqliteDriver = null;
-  let replicaDrivers = [];
-  let replicaIndex = 0;
-  const queryFn = (() => {
-    if (options._queryFn) {
-      return options._queryFn;
-    }
-    if (dialect === "sqlite" && options.d1) {
-      const tableSchema = buildTableSchema(models);
-      sqliteDriver = createSqliteDriver(options.d1, tableSchema);
-      return async (sqlStr, params) => {
-        if (!sqliteDriver) {
-          throw new Error("SQLite driver not initialized");
-        }
-        const rows = await sqliteDriver.query(sqlStr, params);
-        return { rows, rowCount: rows.length };
-      };
-    }
-    if (options.url) {
-      let initialized = false;
-      const initPostgres = async () => {
-        if (initialized)
-          return;
-        const { createPostgresDriver } = await import("./shared/chunk-2gd1fqcw.js");
-        driver = createPostgresDriver(options.url, options.pool);
-        const replicas = options.pool?.replicas;
-        if (replicas && replicas.length > 0) {
-          replicaDrivers = replicas.map((replicaUrl) => createPostgresDriver(replicaUrl, options.pool));
-        }
-        initialized = true;
-      };
-      return async (sqlStr, params) => {
-        await initPostgres();
-        if (replicaDrivers.length === 0) {
-          if (!driver) {
-            throw new Error("Database driver not initialized");
-          }
-          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 (err3) {
-            console.warn("[vertz/db] replica query failed, falling back to primary:", err3.message);
-          }
-        }
-        if (!driver) {
-          throw new Error("Database driver not initialized");
-        }
-        return driver.queryFn(sqlStr, params);
-      };
-    }
-    return async () => {
-      throw new Error("db.query() requires a connected database driver. Provide a `url` to connect to PostgreSQL, a `dialect` with D1 binding for SQLite, or `_queryFn` for testing.");
-    };
-  })();
+var RESERVED_MODEL_NAMES = new Set(["query", "transaction", "close", "isHealthy", "_internals"]);
+function buildDelegates(qfn, models, dialectObj, modelsRegistry) {
   function implGet(name, opts) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await get(queryFn, entry.table, opts, dialectObj);
+        const result = await get(qfn, entry.table, opts, dialectObj);
         if (result !== null && opts?.include) {
-          const rows = await loadRelations(queryFn, [result], entry.relations, opts.include, 0, modelsRegistry, entry.table);
+          const rows = await loadRelations(qfn, [result], entry.relations, opts.include, 0, modelsRegistry, entry.table);
           return ok(rows[0] ?? null);
         }
         return ok(result);
@@ -2168,7 +2137,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await get(queryFn, entry.table, opts, dialectObj);
+        const result = await get(qfn, entry.table, opts, dialectObj);
         if (result === null) {
           return err2({
             code: "NotFound",
@@ -2177,7 +2146,7 @@ function createDb(options) {
           });
         }
         if (opts?.include) {
-          const rows = await loadRelations(queryFn, [result], entry.relations, opts.include, 0, modelsRegistry, entry.table);
+          const rows = await loadRelations(qfn, [result], entry.relations, opts.include, 0, modelsRegistry, entry.table);
           return ok(rows[0]);
         }
         return ok(result);
@@ -2190,9 +2159,9 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const results = await list(queryFn, entry.table, opts, dialectObj);
+        const results = await list(qfn, entry.table, opts, dialectObj);
         if (opts?.include && results.length > 0) {
-          const withRelations = await loadRelations(queryFn, results, entry.relations, opts.include, 0, modelsRegistry, entry.table);
+          const withRelations = await loadRelations(qfn, results, entry.relations, opts.include, 0, modelsRegistry, entry.table);
           return ok(withRelations);
         }
         return ok(results);
@@ -2205,9 +2174,9 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const { data, total } = await listAndCount(queryFn, entry.table, opts, dialectObj);
+        const { data, total } = await listAndCount(qfn, entry.table, opts, dialectObj);
         if (opts?.include && data.length > 0) {
-          const withRelations = await loadRelations(queryFn, data, entry.relations, opts.include, 0, modelsRegistry, entry.table);
+          const withRelations = await loadRelations(qfn, data, entry.relations, opts.include, 0, modelsRegistry, entry.table);
           return ok({ data: withRelations, total });
         }
         return ok({ data, total });
@@ -2220,7 +2189,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await create(queryFn, entry.table, opts, dialectObj);
+        const result = await create(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2231,7 +2200,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await createMany(queryFn, entry.table, opts, dialectObj);
+        const result = await createMany(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2242,7 +2211,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await createManyAndReturn(queryFn, entry.table, opts, dialectObj);
+        const result = await createManyAndReturn(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2253,7 +2222,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await update(queryFn, entry.table, opts, dialectObj);
+        const result = await update(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2264,7 +2233,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await updateMany(queryFn, entry.table, opts, dialectObj);
+        const result = await updateMany(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2275,7 +2244,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await upsert(queryFn, entry.table, opts, dialectObj);
+        const result = await upsert(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2286,7 +2255,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await deleteOne(queryFn, entry.table, opts, dialectObj);
+        const result = await deleteOne(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2297,7 +2266,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await deleteMany(queryFn, entry.table, opts, dialectObj);
+        const result = await deleteMany(qfn, entry.table, opts, dialectObj);
         return ok(result);
       } catch (e) {
         return err2(toWriteError(e));
@@ -2308,7 +2277,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await count(queryFn, entry.table, opts);
+        const result = await count(qfn, entry.table, opts);
         return ok(result);
       } catch (e) {
         return err2(toReadError(e));
@@ -2319,7 +2288,7 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await aggregate(queryFn, entry.table, opts);
+        const result = await aggregate(qfn, entry.table, opts);
         return ok(result);
       } catch (e) {
         return err2(toReadError(e));
@@ -2330,16 +2299,16 @@ function createDb(options) {
     return (async () => {
       try {
         const entry = resolveModel(models, name);
-        const result = await groupBy(queryFn, entry.table, opts);
+        const result = await groupBy(qfn, entry.table, opts);
         return ok(result);
       } catch (e) {
         return err2(toReadError(e));
       }
     })();
   }
-  const client = {};
+  const delegates = {};
   for (const name of Object.keys(models)) {
-    client[name] = {
+    delegates[name] = {
       get: (opts) => implGet(name, opts),
       getOrThrow: (opts) => implGetRequired(name, opts),
       list: (opts) => implList(name, opts),
@@ -2357,14 +2326,142 @@ function createDb(options) {
       groupBy: (opts) => implGroupBy(name, opts)
     };
   }
-  client.query = async (fragment) => {
+  return delegates;
+}
+function buildQueryMethod(qfn) {
+  return async (fragment) => {
     try {
-      const result = await executeQuery(queryFn, fragment.sql, fragment.params);
+      const result = await executeQuery(qfn, fragment.sql, fragment.params);
       return ok(result);
     } catch (e) {
       return err2(toReadError(e, fragment.sql));
     }
   };
+}
+function createDb(options) {
+  const { models, log, dialect } = options;
+  for (const key of Object.keys(models)) {
+    if (RESERVED_MODEL_NAMES.has(key)) {
+      throw new Error(`Model name "${key}" is reserved. Choose a different name for this model. ` + `Reserved names: ${[...RESERVED_MODEL_NAMES].join(", ")}`);
+    }
+  }
+  if (dialect === "sqlite") {
+    if (!options.d1) {
+      throw new Error("SQLite dialect requires a D1 binding");
+    }
+    if (options.url) {
+      throw new Error("SQLite dialect uses D1, not a connection URL");
+    }
+  }
+  const dialectObj = dialect === "sqlite" ? defaultSqliteDialect : defaultPostgresDialect;
+  const tenantGraph = computeTenantGraph(models);
+  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(models)) {
+      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 modelsRegistry = models;
+  let driver = null;
+  let sqliteDriver = null;
+  let replicaDrivers = [];
+  let replicaIndex = 0;
+  let initPostgres = null;
+  const queryFn = (() => {
+    if (options._queryFn) {
+      return options._queryFn;
+    }
+    if (dialect === "sqlite" && options.d1) {
+      const tableSchema = buildTableSchema(models);
+      sqliteDriver = createSqliteDriver(options.d1, tableSchema);
+      return async (sqlStr, params) => {
+        if (!sqliteDriver) {
+          throw new Error("SQLite driver not initialized");
+        }
+        const rows = await sqliteDriver.query(sqlStr, params);
+        return { rows, rowCount: rows.length };
+      };
+    }
+    if (options.url) {
+      let initialized = false;
+      initPostgres = async () => {
+        if (initialized)
+          return;
+        const { createPostgresDriver } = await import("./shared/chunk-p2x2vmg5.js");
+        driver = createPostgresDriver(options.url, options.pool);
+        const replicas = options.pool?.replicas;
+        if (replicas && replicas.length > 0) {
+          replicaDrivers = replicas.map((replicaUrl) => createPostgresDriver(replicaUrl, options.pool));
+        }
+        initialized = true;
+      };
+      return async (sqlStr, params) => {
+        await initPostgres?.();
+        if (replicaDrivers.length === 0) {
+          if (!driver) {
+            throw new Error("Database driver not initialized");
+          }
+          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 (err3) {
+            console.warn("[vertz/db] replica query failed, falling back to primary:", err3.message);
+          }
+        }
+        if (!driver) {
+          throw new Error("Database driver not initialized");
+        }
+        return driver.queryFn(sqlStr, params);
+      };
+    }
+    return async () => {
+      throw new Error("db.query() requires a connected database driver. Provide a `url` to connect to PostgreSQL, a `dialect` with D1 binding for SQLite, or `_queryFn` for testing.");
+    };
+  })();
+  const delegates = buildDelegates(queryFn, models, dialectObj, modelsRegistry);
+  const client = { ...delegates };
+  client.query = buildQueryMethod(queryFn);
+  client.transaction = async (fn) => {
+    if (initPostgres) {
+      await initPostgres();
+    }
+    if (driver?.beginTransaction) {
+      return await driver.beginTransaction(async (txQueryFn) => {
+        const txDelegates = buildDelegates(txQueryFn, models, dialectObj, modelsRegistry);
+        const tx = {
+          ...txDelegates,
+          query: buildQueryMethod(txQueryFn)
+        };
+        return fn(tx);
+      });
+    }
+    await queryFn("BEGIN", []);
+    try {
+      const tx = {
+        ...delegates,
+        query: client.query
+      };
+      const result = await fn(tx);
+      await queryFn("COMMIT", []);
+      return result;
+    } catch (e) {
+      try {
+        await queryFn("ROLLBACK", []);
+      } catch {}
+      throw e;
+    }
+  };
   client.close = async () => {
     if (driver) {
       await driver.close();

package/dist/postgres/index.d.ts

@@ -29,6 +29,12 @@ interface DbDriver {
 		rowsAffected: number;
 	}>;
 	/**
+	* Execute a callback within a database transaction.
+	* The callback receives a transaction-scoped QueryFn.
+	* Optional — not all drivers support transactions (e.g., D1).
+	*/
+	beginTransaction?<T>(fn: (txQueryFn: QueryFn) => Promise<T>): Promise<T>;
+	/**
 	* Close the database connection.
 	*/
 	close(): Promise<void>;

package/dist/postgres/index.js

@@ -1,6 +1,6 @@
 import {
   createPostgresDriver
-} from "../shared/chunk-rqe0prft.js";
+} from "../shared/chunk-rjry8vc2.js";
 import"../shared/chunk-j4kwq1gh.js";
 export {
   createPostgresDriver