tempest-db-js 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -14,6 +14,142 @@ function toCondNode(input) {
 function wrap(node) {
   return { [CONDITION]: true, node };
 }
+function toExprNode(operand) {
+  return isExpression(operand) ? operand.node : { kind: "value", value: operand };
+}
+function assertValueOperands(op, operands) {
+  if (operands.some(isExpression)) {
+    throw new Error(
+      `The "${op}" operator binds its operands, so it takes values, not expressions.`
+    );
+  }
+}
+function isExpression(value) {
+  return value instanceof Expression;
+}
+var Expression = class {
+  constructor(node) {
+    this.node = node;
+  }
+  node;
+  /** Compare this expression against another expression or a bound value. */
+  compare(op, operand) {
+    return wrap({ kind: "compare", left: this.node, op, right: toExprNode(operand) });
+  }
+  /** `=` (or `IS NULL` for a null value). */
+  eq(operand) {
+    return this.compare("eq", operand);
+  }
+  /** `<>` (or `IS NOT NULL` for a null value). */
+  ne(operand) {
+    return this.compare("ne", operand);
+  }
+  /** `>`. */
+  gt(operand) {
+    return this.compare("gt", operand);
+  }
+  /** `>=`. */
+  gte(operand) {
+    return this.compare("gte", operand);
+  }
+  /** `<`. */
+  lt(operand) {
+    return this.compare("lt", operand);
+  }
+  /** `<=`. */
+  lte(operand) {
+    return this.compare("lte", operand);
+  }
+  /** `LIKE` — `%` and `_` in the operand are wildcards. */
+  like(pattern) {
+    return this.compare("like", pattern);
+  }
+  /** `ILIKE` — case-insensitive **pattern** matching, wildcards included. */
+  ilike(pattern) {
+    return this.compare("ilike", pattern);
+  }
+  /** Case-insensitive equality (`lower(a) = lower(b)`), with no wildcards. */
+  ieq(operand) {
+    return this.compare("ieq", operand);
+  }
+  /**
+   * `IN (...)` over a list of values.
+   *
+   * @param values The values to test against.
+   * @returns The condition.
+   * @throws Error When an entry is an {@link Expression} — a list operand is
+   *   bound, so an expression there would be serialized as a parameter instead of
+   *   rendered as SQL.
+   */
+  in(values) {
+    assertValueOperands("in", values);
+    return this.compare("in", values);
+  }
+  /**
+   * `NOT IN (...)` over a list of values.
+   *
+   * @param values The values to exclude.
+   * @returns The condition.
+   * @throws Error When an entry is an {@link Expression} (see {@link Expression.in}).
+   */
+  notIn(values) {
+    assertValueOperands("notIn", values);
+    return this.compare("notIn", values);
+  }
+  /**
+   * `BETWEEN lo AND hi` (inclusive).
+   *
+   * @param lo The lower bound.
+   * @param hi The upper bound.
+   * @returns The condition.
+   * @throws Error When a bound is an {@link Expression} (see {@link Expression.in}).
+   */
+  between(lo, hi) {
+    assertValueOperands("between", [lo, hi]);
+    return this.compare("between", [lo, hi]);
+  }
+  /** `IS NULL` (true) / `IS NOT NULL` (false). */
+  isNull(value = true) {
+    return this.compare("isNull", value);
+  }
+};
+function col(name) {
+  return new Expression({ kind: "column", name });
+}
+function val(value) {
+  return new Expression({ kind: "value", value });
+}
+var FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function toArg(arg) {
+  return typeof arg === "string" ? { kind: "column", name: arg } : arg.node;
+}
+function call(name, ...args) {
+  if (!FUNCTION_NAME.test(name)) {
+    throw new Error(
+      `fn.call() takes a plain SQL function name; got ${JSON.stringify(name)}.`
+    );
+  }
+  return new Expression({ kind: "fn", name, args: args.map(toArg) });
+}
+var fn = {
+  /** `lower(x)`. */
+  lower: (arg) => call("lower", arg),
+  /** `upper(x)`. */
+  upper: (arg) => call("upper", arg),
+  /** `trim(x)`. */
+  trim: (arg) => call("trim", arg),
+  /** `length(x)`. */
+  length: (arg) => call("length", arg),
+  /** `abs(x)`. */
+  abs: (arg) => call("abs", arg),
+  /** `coalesce(a, b, ...)`. */
+  coalesce: (...args) => call("coalesce", ...args),
+  /**
+   * Any other SQL function, by name. Portability is the caller's problem —
+   * `date_trunc` is PostgreSQL, `strftime` is SQLite.
+   */
+  call
+};
 function and(...inputs) {
   return wrap({
     kind: "and",
@@ -31,6 +167,9 @@ function not(input) {
 }
 
 // src/query.ts
+function isSubquery(value) {
+  return typeof value === "object" && value !== null && value.node?.kind === "select";
+}
 var OPERATORS = [
   "eq",
   "ne",
@@ -50,8 +189,8 @@ var OPERATORS = [
   "overlaps"
 ];
 var Agg = class {
-  constructor(fn, column2) {
-    this.fn = fn;
+  constructor(fn2, column2) {
+    this.fn = fn2;
     this.column = column2;
   }
   fn;
@@ -80,12 +219,41 @@ var SelectBuilder = class _SelectBuilder {
   node;
   source;
   with(patch) {
-    return new _SelectBuilder({ ...this.node, ...patch }, this.source);
+    return new _SelectBuilder(
+      { ...this.node, ...patch },
+      this.source
+    );
   }
   /** Add a WHERE filter: the object form (keys typed) or an `and`/`or`/`not`. */
   where(input) {
     return this.with({ where: toCondNode(input) });
   }
+  /**
+   * Filter by the result of the aggregation (`HAVING`).
+   *
+   * Only available on a grouped builder — `.having()` before `.aggregate()` is a
+   * compile error, not invalid SQL at runtime. Keys are the aggregate aliases you
+   * named plus the grouped columns; `WHERE` still filters rows *before* grouping,
+   * which is a different question.
+   *
+   * @param input The condition, keyed by alias or grouped column.
+   * @returns A builder carrying the `HAVING` clause.
+   *
+   * @example
+   * ```ts
+   * select(Outbound)
+   *   .where({ status: "queued" })
+   *   .aggregate(["consumer"], { n: count() })
+   *   .having({ n: { gt: 100 } });
+   * // ... GROUP BY "consumer" HAVING COUNT(*) > $2
+   * ```
+   */
+  having(input) {
+    return new _SelectBuilder(
+      { ...this.node, having: toCondNode(input) },
+      this.source
+    );
+  }
   /** Emit `SELECT DISTINCT` — drop duplicate rows. */
   distinct() {
     return this.with({ distinct: true });
@@ -117,7 +285,15 @@ var SelectBuilder = class _SelectBuilder {
       this.source
     );
   }
-  /** Order by a column of `Full`. */
+  /**
+   * Order by a column of the model, or — on a grouped query — by an aggregate
+   * alias. Unlike `HAVING`, every dialect accepts the output alias in `ORDER BY`,
+   * so the alias is emitted as written.
+   *
+   * @param column A model column, or a projected alias.
+   * @param direction `"asc"` (default) or `"desc"`.
+   * @returns A builder carrying the ordering term.
+   */
   orderBy(column2, direction = "asc") {
     return this.with({
       orderBy: [...this.node.orderBy, { column: column2, direction }]
@@ -131,6 +307,37 @@ var SelectBuilder = class _SelectBuilder {
   offset(n) {
     return this.with({ offset: n });
   }
+  /**
+   * Narrow this SELECT to a single column and mark it as a subquery, so it can be
+   * the operand of `in` / `notIn`.
+   *
+   * The whole query — `where`, `orderBy`, `limit`, and a locking clause — is
+   * embedded in the outer statement, which is what collapses the claim-a-batch
+   * pattern into one round trip instead of selecting ids and sending them back.
+   *
+   * @param column The single column to project (checked against the model).
+   * @returns A subquery carrying that column's type.
+   *
+   * @example
+   * ```ts
+   * update(Outbound)
+   *   .set({ status: "sending", attempts: sql.raw("attempts + 1") })
+   *   .where({
+   *     id: {
+   *       in: select(Outbound)
+   *         .where({ status: "queued" })
+   *         .orderBy("nextAttemptAt")
+   *         .limit(10)
+   *         .forUpdate({ skipLocked: true })
+   *         .asSubquery("id"),
+   *     },
+   *   })
+   *   .returning();
+   * ```
+   */
+  asSubquery(column2) {
+    return { node: { ...this.node, columns: [column2] } };
+  }
   /**
    * Lock the selected rows for update (`SELECT ... FOR UPDATE`), à la
    * SQLAlchemy's `with_for_update()`.
@@ -284,8 +491,8 @@ function toDict(model, row) {
 function toJSON(model, row) {
   const columns = columnsOf(model);
   const out = {};
-  for (const [name, col] of Object.entries(columns)) {
-    out[name] = encodeValue(col, row[name] ?? null);
+  for (const [name, col2] of Object.entries(columns)) {
+    out[name] = encodeValue(col2, row[name] ?? null);
   }
   return out;
 }
@@ -296,10 +503,10 @@ function fromDict(model, data) {
   const columns = columnsOf(model);
   const out = {};
   const issues = [];
-  for (const [name, col] of Object.entries(columns)) {
+  for (const [name, col2] of Object.entries(columns)) {
     const present = name in data && data[name] !== void 0 && data[name] !== null;
     if (!present) {
-      const required = col.flags.notNull && !col.flags.hasDefault;
+      const required = col2.flags.notNull && !col2.flags.hasDefault;
       if (required) {
         issues.push(`missing required column "${name}"`);
         continue;
@@ -308,7 +515,7 @@ function fromDict(model, data) {
       continue;
     }
     try {
-      out[name] = decodeValue(col, data[name]);
+      out[name] = decodeValue(col2, data[name]);
     } catch (error) {
       issues.push(`column "${name}": ${error.message}`);
     }
@@ -359,8 +566,8 @@ function mapperFor(model) {
   const props = columnPropsOf(model);
   const names = props ? Object.fromEntries(Object.entries(props).map(([db, prop]) => [prop, db])) : null;
   const decoders = /* @__PURE__ */ new Map();
-  for (const [prop, col] of Object.entries(columnsOf(model))) {
-    const decoder = decoderFor(col.type);
+  for (const [prop, col2] of Object.entries(columnsOf(model))) {
+    const decoder = decoderFor(col2.type);
     if (decoder) decoders.set(names?.[prop] ?? prop, decoder);
   }
   const mapper = { props, decoders };
@@ -391,19 +598,34 @@ function assertWritableValues(model, values, clause) {
   const columns = columnsOf(model);
   const issues = [];
   for (const [key, value] of Object.entries(values)) {
-    const col = columns[key];
-    if (!col) {
+    const col2 = columns[key];
+    if (!col2) {
       issues.push(`${clause}: "${key}" is not a column of ${model.tablename}`);
       continue;
     }
     if (isSqlExpression(value) || isBindableScalar(value)) continue;
-    if (typeof value === "object" && STRUCTURED_KINDS.has(col.type.kind)) continue;
+    if (typeof value === "object" && STRUCTURED_KINDS.has(col2.type.kind)) continue;
     issues.push(
-      `${clause}: "${key}" got ${describeValue(value)}, which cannot be bound to a ${col.type.kind} column \u2014 use sql.raw()/sql.expr\`...\` for a SQL expression`
+      `${clause}: "${key}" got ${describeValue(value)}, which cannot be bound to a ${col2.type.kind} column \u2014 use sql.raw()/sql.expr\`...\` for a SQL expression`
     );
   }
   if (issues.length > 0) throw new ValidationError(model.tablename, issues);
 }
+function assertConsistentRows(model, rows) {
+  if (rows.length < 2) return;
+  const union = /* @__PURE__ */ new Set();
+  for (const row of rows) for (const key of Object.keys(row)) union.add(key);
+  const inconsistent = [...union].filter((key) => rows.some((row) => !(key in row)));
+  if (inconsistent.length === 0) return;
+  const columns = columnsOf(model);
+  const defaulted = inconsistent.filter((key) => columns[key]?.flags.hasDefault);
+  if (defaulted.length === 0) return;
+  const named = defaulted.map((c) => `"${c}"`).join(", ");
+  const verb = defaulted.length === 1 ? "has" : "have";
+  throw new ValidationError(model.tablename, [
+    `values: ${named} ${verb} a default but is missing from some rows of this multi-row insert \u2014 every row shares one column list, so the omitting rows would be written as NULL instead of taking the default. Give the column in every row, or insert the rows separately.`
+  ]);
+}
 function describeValue(value) {
   if (typeof value === "function") return "a function";
   if (Array.isArray(value)) return "an array";
@@ -426,11 +648,13 @@ var InsertBuilder = class _InsertBuilder {
    * @param rows One row, or an array of rows.
    * @returns A builder carrying the rows.
    * @throws ValidationError When a value is not a column value the dialect can
-   *   bind (see the `sql` helpers for writing an expression instead).
+   *   bind (see the `sql` helpers for writing an expression instead), or when the
+   *   rows of a multi-row insert disagree about a column that has a default.
    */
   values(rows) {
     const list = Array.isArray(rows) ? rows : [rows];
     for (const row of list) assertWritableValues(this.source, row, "values");
+    assertConsistentRows(this.source, list);
     return this.with({ values: list });
   }
   /**
@@ -732,6 +956,18 @@ var Params = class {
     return this.placeholder(this.values.length);
   }
 };
+function insertColumns(rows) {
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (seen.has(key)) continue;
+      seen.add(key);
+      columns.push(key);
+    }
+  }
+  return columns;
+}
 function insertHasExpression(node) {
   for (const row of node.values) {
     for (const value of Object.values(row)) {
@@ -755,6 +991,15 @@ var BaseDialect = class _BaseDialect {
   static insertTemplates = /* @__PURE__ */ new Map();
   /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
   static quotedIds = /* @__PURE__ */ new Map();
+  /**
+   * Validate a subquery operand before it is rendered, for dialects that restrict
+   * what an `IN (SELECT ...)` may contain. The default accepts everything.
+   *
+   * @param _node The subquery's AST.
+   * @throws Error When the dialect cannot execute this subquery.
+   */
+  checkSubquery(_node) {
+  }
   /**
    * The SQL operator for an array containment/overlap test.
    *
@@ -878,6 +1123,19 @@ var BaseDialect = class _BaseDialect {
     return ` ${strength}${of}${wait}`;
   }
   // ---- statements -------------------------------------------------------
+  /**
+   * Compile a SELECT.
+   *
+   * Two alias rules differ between clauses and are handled here: PostgreSQL does
+   * NOT accept a `SELECT` alias in `HAVING`, so an aggregate key is re-emitted as
+   * its expression (`COUNT(*) > $1`), a form every dialect accepts; `ORDER BY`,
+   * by contrast, accepts the output alias everywhere, so it is emitted as
+   * written.
+   *
+   * @param node The select AST.
+   * @param params The parameter collector.
+   * @returns The SQL text.
+   */
   compileSelect(node, params) {
     const names = node.names;
     let cols;
@@ -901,10 +1159,21 @@ var BaseDialect = class _BaseDialect {
     if (node.groupBy.length > 0) {
       sql2 += ` GROUP BY ${node.groupBy.map((c) => this.columnId(c, names)).join(", ")}`;
     }
+    const aggByAlias = new Map(node.aggregates.map((a) => [a.alias, a]));
+    if (node.having) {
+      const having = this.compileCondition(node.having, params, (key) => {
+        const agg = aggByAlias.get(key);
+        if (!agg) return this.columnId(key, names);
+        const inner = agg.column === "*" ? "*" : this.columnId(agg.column, names);
+        return `${agg.fn.toUpperCase()}(${inner})`;
+      });
+      if (having) sql2 += ` HAVING ${having}`;
+    }
     if (node.orderBy.length > 0) {
-      const terms = node.orderBy.map(
-        (t) => `${this.columnId(t.column, names)} ${t.direction === "desc" ? "DESC" : "ASC"}`
-      ).join(", ");
+      const terms = node.orderBy.map((t) => {
+        const id = aggByAlias.has(t.column) ? this.quoteId(t.column) : this.columnId(t.column, names);
+        return `${id} ${t.direction === "desc" ? "DESC" : "ASC"}`;
+      }).join(", ");
       sql2 += ` ORDER BY ${terms}`;
     }
     if (node.limit !== void 0) sql2 += ` LIMIT ${params.bind(node.limit)}`;
@@ -928,7 +1197,7 @@ var BaseDialect = class _BaseDialect {
    * SQL order, so placeholder positions stay correct.
    */
   compileInsert(node, params) {
-    const columns = node.values.length > 0 ? Object.keys(node.values[0]) : [];
+    const columns = insertColumns(node.values);
     const conflict = node.onConflict;
     const cacheable = conflict?.targetWhere === void 0 && conflict?.updateWhere === void 0 && !insertHasExpression(node);
     if (!cacheable) return this.compileInsertDirect(node, columns, params);
@@ -1040,7 +1309,7 @@ var BaseDialect = class _BaseDialect {
   compileUpdate(node, params) {
     const names = node.names;
     const sets = Object.entries(node.set).map(
-      ([col, value]) => `${this.columnId(col, names)} = ${this.renderValue(value, params)}`
+      ([col2, value]) => `${this.columnId(col2, names)} = ${this.renderValue(value, params)}`
     ).join(", ");
     let sql2 = `UPDATE ${this.quoteId(node.table)} SET ${sets}`;
     const where = this.compileCondition(
@@ -1133,6 +1402,83 @@ var BaseDialect = class _BaseDialect {
         const inner = this.compileCondition(node.part, params, idFor);
         return inner ? `NOT (${inner})` : "";
       }
+      case "compare": {
+        const left = this.renderExpr(node.left, params, idFor);
+        if (node.right.kind === "value") {
+          return this.compileOperator(left, node.op, node.right.value, params);
+        }
+        return this.compileExprOperator(
+          left,
+          node.op,
+          this.renderExpr(node.right, params, idFor)
+        );
+      }
+    }
+  }
+  /**
+   * Render one side of a comparison.
+   *
+   * A column reference goes through `idFor`, so an explicit `.name()` mapping and
+   * join qualification apply here exactly as they do in the object form of
+   * `where` — `col()` is not a way around them. Only a `value` node binds.
+   *
+   * @param node The expression AST.
+   * @param params The parameter collector.
+   * @param idFor The identifier resolver for the enclosing statement.
+   * @returns The SQL text of the expression.
+   */
+  renderExpr(node, params, idFor) {
+    switch (node.kind) {
+      case "column":
+        return idFor(node.name);
+      case "value":
+        return params.bind(node.value);
+      case "fn": {
+        const args = node.args.map((a) => this.renderExpr(a, params, idFor)).join(", ");
+        return `${node.name}(${args})`;
+      }
+    }
+  }
+  /**
+   * Compile a comparison whose right-hand side is another expression rather than
+   * a bound value (`total > paid`, `lower(a) = lower(b)`).
+   *
+   * The list and null operators are excluded: `IN`, `BETWEEN` and `IS NULL` take
+   * a value operand, and accepting an expression there would silently compile to
+   * something else.
+   *
+   * @param left The rendered left-hand side.
+   * @param op The operator name.
+   * @param right The rendered right-hand side.
+   * @returns The SQL text of the predicate.
+   * @throws Error When the operator needs a value operand.
+   */
+  compileExprOperator(left, op, right) {
+    switch (op) {
+      case "eq":
+        return `${left} = ${right}`;
+      case "ne":
+        return `${left} <> ${right}`;
+      case "gt":
+        return `${left} > ${right}`;
+      case "gte":
+        return `${left} >= ${right}`;
+      case "lt":
+        return `${left} < ${right}`;
+      case "lte":
+        return `${left} <= ${right}`;
+      case "like":
+        return `${left} LIKE ${right}`;
+      case "ilike":
+        return this.ilike(left, right);
+      case "ieq":
+        return `lower(${left}) = lower(${right})`;
+      case "contains":
+      case "containedBy":
+      case "overlaps":
+        return `${left} ${this.arrayOperator(op)} ${right}`;
+      default:
+        throw new Error(`The "${op}" operator takes a value operand, not an expression.`);
     }
   }
   compileOperator(id, op, operand, params) {
@@ -1175,12 +1521,33 @@ var BaseDialect = class _BaseDialect {
         throw new Error(`Unknown operator ${JSON.stringify(op)}`);
     }
   }
-  compileIn(id, values, params, negate) {
+  /**
+   * Compile `IN` / `NOT IN`, whose operand is either a value list or a
+   * single-column subquery.
+   *
+   * The subquery is rendered at the position it appears in the outer statement
+   * and shares the same parameter collector, so its own placeholders land in the
+   * right order — and it keeps its own `names` map, since the inner model may use
+   * a different naming convention than the outer one.
+   *
+   * @param id The quoted column identifier being tested.
+   * @param operand A list of values, or a {@link Subquery}.
+   * @param params The parameter collector for the statement being compiled.
+   * @param negate True for `NOT IN`.
+   * @returns The SQL text of the predicate.
+   */
+  compileIn(id, operand, params, negate) {
+    const keyword = negate ? "NOT IN" : "IN";
+    if (isSubquery(operand)) {
+      this.checkSubquery(operand.node);
+      return `${id} ${keyword} (${this.compileSelect(operand.node, params)})`;
+    }
+    const values = operand;
     if (values.length === 0) {
       return negate ? "1 = 1" : "1 = 0";
     }
     const list = values.map((v) => params.bind(v)).join(", ");
-    return `${id} ${negate ? "NOT IN" : "IN"} (${list})`;
+    return `${id} ${keyword} (${list})`;
   }
 };
 var SqliteDialect = class extends BaseDialect {
@@ -1232,6 +1599,19 @@ var MysqlDialect = class extends BaseDialect {
     mysqlQuotedIds.set(name, quoted);
     return quoted;
   }
+  /**
+   * MySQL rejects `LIMIT` inside an `IN` subquery with
+   * `ER_NOT_SUPPORTED_YET: This version of MySQL doesn't yet support
+   * 'LIMIT & IN/ALL/ANY/SOME subquery'`. Failing at compile time names the fix
+   * instead of surfacing that error from the driver at runtime.
+   */
+  checkSubquery(node) {
+    if (node.limit !== void 0 || node.offset !== void 0) {
+      throw new Error(
+        "MySQL does not support LIMIT/OFFSET inside an IN subquery. Select the ids first and pass them as a list, or wrap the subquery in a derived table."
+      );
+    }
+  }
   renderConflict(onConflict, conflictCols, nextValue, names) {
     if (onConflict.targetWhere || onConflict.updateWhere) {
       throw new Error(
@@ -1239,16 +1619,25 @@ var MysqlDialect = class extends BaseDialect {
       );
     }
     if (onConflict.update === "nothing") {
-      const col = this.columnId(onConflict.target[0] ?? "id", names);
-      return ` ON DUPLICATE KEY UPDATE ${col} = ${col}`;
+      const col2 = this.columnId(onConflict.target[0] ?? "id", names);
+      return ` ON DUPLICATE KEY UPDATE ${col2} = ${col2}`;
     }
     const assignments = conflictCols.map((c) => `${this.columnId(c, names)} = ${nextValue()}`).join(", ");
     return ` ON DUPLICATE KEY UPDATE ${assignments}`;
   }
+  /**
+   * MySQL has no `RETURNING`, so it cannot be compiled into a statement.
+   *
+   * `session.execute()` still honors `.returning()` on a **single-row INSERT** by
+   * running the insert and reading the row back by key on the same connection —
+   * that is execution, not compilation, so it never reaches here. Compiling a
+   * node with `returning` directly is an error, rather than SQL that silently
+   * returns nothing.
+   */
   compileReturning(returning) {
     if (returning === null) return "";
     throw new Error(
-      "RETURNING is not supported on MySQL \u2014 insert, then SELECT by key (e.g. LAST_INSERT_ID())."
+      "RETURNING cannot be compiled for MySQL. session.execute() reads a single-row INSERT back by key (LAST_INSERT_ID()); UPDATE/DELETE have no equivalent \u2014 run a SELECT yourself."
     );
   }
 };
@@ -1361,8 +1750,8 @@ var RecordNotFound = class extends Error {
   }
 };
 function primaryKeyOf(model) {
-  for (const [name, col] of Object.entries(columnsOf(model))) {
-    if (col.flags.primaryKey) return name;
+  for (const [name, col2] of Object.entries(columnsOf(model))) {
+    if (col2.flags.primaryKey) return name;
   }
   throw new Error(`${model.tablename} has no primary key`);
 }
@@ -1450,8 +1839,8 @@ var BaseRepository = class {
 
 // src/active-record.ts
 function primaryKeyOf2(model) {
-  for (const [name, col] of Object.entries(columnsOf(model))) {
-    if (col.flags.primaryKey) return name;
+  for (const [name, col2] of Object.entries(columnsOf(model))) {
+    if (col2.flags.primaryKey) return name;
   }
   throw new Error(`${model.tablename} has no primary key`);
 }
@@ -1617,10 +2006,18 @@ var NodeSqliteDriver = class _NodeSqliteDriver {
   constructor(database) {
     this.db = database;
   }
-  /** Open a `node:sqlite` database at the given path (or `:memory:`). */
-  static open(path) {
+  /**
+   * Open a `node:sqlite` database at the given path (or `:memory:`).
+   *
+   * @param path The database file, or `":memory:"`.
+   * @param options Passed straight to `DatabaseSync` (`readOnly`, `timeout`, …).
+   * @returns A driver over the open handle.
+   */
+  static open(path, options) {
     const { DatabaseSync } = nodeRequire("node:sqlite");
-    return new _NodeSqliteDriver(new DatabaseSync(path));
+    return new _NodeSqliteDriver(
+      options ? new DatabaseSync(path, { ...options }) : new DatabaseSync(path)
+    );
   }
   /** Return the cached prepared statement for `sql`, preparing it on first use. */
   // biome-ignore lint/suspicious/noExplicitAny: statement type is unavailable here.
@@ -1787,6 +2184,18 @@ var AsyncResult = class {
   }
 };
 var savepointCounter = 0;
+function needsInsertReadBack(dialect, node) {
+  return dialect.name === "mysql" && node.kind === "insert" && node.returning !== null;
+}
+function singlePrimaryKey(model) {
+  const keys = Object.entries(columnsOf(model)).filter(([, column2]) => column2.flags.primaryKey).map(([name]) => name);
+  if (keys.length !== 1) {
+    throw new Error(
+      `${model.tablename} needs exactly one primary key to read an insert back on a dialect without RETURNING; found ${keys.length}.`
+    );
+  }
+  return keys[0];
+}
 function assertRawParams(params) {
   if (!Array.isArray(params)) {
     throw new TypeError(
@@ -1859,10 +2268,10 @@ var SyncSession = class {
     return new SyncResult(rows, result.changes);
   }
   /** Run `fn` inside a transaction: commit on success, rollback on throw. */
-  transaction(fn) {
+  transaction(fn2) {
     this.exec("BEGIN", []);
     try {
-      const out = fn(this);
+      const out = fn2(this);
       this.exec("COMMIT", []);
       return out;
     } catch (error) {
@@ -1871,12 +2280,12 @@ var SyncSession = class {
     }
   }
   /** Run `fn` inside a SAVEPOINT (nested transaction). */
-  beginNested(fn) {
+  beginNested(fn2) {
     savepointCounter += 1;
     const name = `qsp_${savepointCounter}`;
     this.exec(`SAVEPOINT ${name}`, []);
     try {
-      const out = fn(this);
+      const out = fn2(this);
       this.exec(`RELEASE ${name}`, []);
       return out;
     } catch (error) {
@@ -1974,6 +2383,11 @@ var AsyncSession = class _AsyncSession {
   }
   execute(builder) {
     const node = builder.node;
+    if (needsInsertReadBack(this.dialect, node)) {
+      return new AsyncResult(
+        this.insertAndReadBack(builder, node)
+      );
+    }
     const { sql: sql2, params } = this.dialect.compile(node);
     const inner = this.exec(sql2, params).then((result) => {
       const rows = mapRows(builder, result.rows);
@@ -1981,6 +2395,53 @@ var AsyncSession = class _AsyncSession {
     });
     return new AsyncResult(inner);
   }
+  /**
+   * Honor `.returning()` on a dialect without `RETURNING`, by inserting and then
+   * reading the row back by key.
+   *
+   * Both statements must run on **one** connection, because `LAST_INSERT_ID()` is
+   * per-connection: outside a transaction the pooled driver is reserved for the
+   * pair; inside one, the session already holds a pinned connection (a reserved
+   * driver exposes no `reserve`), so it runs there directly.
+   *
+   * @param builder The insert builder, for its source model.
+   * @param node The insert AST, whose `returning` drives the read-back.
+   * @returns The result view over the read-back row.
+   * @throws Error When the insert writes more than one row — `LAST_INSERT_ID()`
+   *   identifies only the first, and the rest are consecutive only under some
+   *   auto-increment lock modes.
+   */
+  async insertAndReadBack(builder, node) {
+    if (node.values.length !== 1) {
+      throw new Error(
+        `${this.dialect.name} has no RETURNING, and reading back a multi-row insert is not reliable \u2014 insert one row at a time, or drop .returning().`
+      );
+    }
+    const model = builder.source;
+    const pk = singlePrimaryKey(model);
+    const supplied = node.values[0][pk];
+    const readBack = select(model).where(
+      supplied === void 0 || supplied === null ? col(pk).eq(fn.call("LAST_INSERT_ID")) : { [pk]: supplied }
+    );
+    const insertSql = this.dialect.compile({ ...node, returning: null });
+    const selectSql = this.dialect.compile(
+      node.returning === "*" || node.returning === null ? readBack.node : { ...readBack.node, columns: node.returning }
+    );
+    const run = async (driver) => {
+      const scoped = new _AsyncSession(driver, this.dialect, this.logger);
+      const written = await scoped.exec(insertSql.sql, insertSql.params);
+      const read = await scoped.exec(selectSql.sql, selectSql.params);
+      const rows = read.rows.map((row) => coerceRow(model, row));
+      return new SyncResult(rows, written.changes);
+    };
+    if (!this.driver.reserve) return run(this.driver);
+    const reserved = await this.driver.reserve();
+    try {
+      return await run(reserved);
+    } finally {
+      await reserved.release();
+    }
+  }
   /** Lazily iterate result rows. Uses driver streaming when available. */
   async *stream(builder) {
     const node = builder.node;
@@ -2001,13 +2462,13 @@ var AsyncSession = class _AsyncSession {
       yield coerceOne(builder, raw);
     }
   }
-  async transaction(fn) {
+  async transaction(fn2) {
     if (this.driver.reserve) {
       const reserved = await this.driver.reserve();
       const scoped = new _AsyncSession(reserved, this.dialect, this.logger);
       try {
         await scoped.exec("BEGIN", []);
-        const out = await fn(scoped);
+        const out = await fn2(scoped);
         await scoped.exec("COMMIT", []);
         return out;
       } catch (error) {
@@ -2019,7 +2480,7 @@ var AsyncSession = class _AsyncSession {
     }
     await this.exec("BEGIN", []);
     try {
-      const out = await fn(this);
+      const out = await fn2(this);
       await this.exec("COMMIT", []);
       return out;
     } catch (error) {
@@ -2035,6 +2496,13 @@ var AsyncSession = class _AsyncSession {
     await this.close();
   }
 };
+function emitNotice(logger, notice) {
+  if (!logger) return;
+  try {
+    logger(notice);
+  } catch {
+  }
+}
 var SyncEngine = class {
   constructor(driver, logger) {
     this.driver = driver;
@@ -2046,8 +2514,8 @@ var SyncEngine = class {
   session() {
     return new SyncSession(this.driver, getDialect("sqlite"), this.logger);
   }
-  transaction(fn) {
-    return this.session().transaction(fn);
+  transaction(fn2) {
+    return this.session().transaction(fn2);
   }
   close() {
     this.driver.close();
@@ -2069,8 +2537,8 @@ var AsyncEngine = class {
   session() {
     return new AsyncSession(this.driver, getDialect(this.dialect), this.logger);
   }
-  transaction(fn) {
-    return this.session().transaction(fn);
+  transaction(fn2) {
+    return this.session().transaction(fn2);
   }
   async close() {
     await this.driver.close();
@@ -2080,6 +2548,16 @@ var AsyncEngine = class {
     await this.close();
   }
 };
+function toAsyncDriver(driver) {
+  return {
+    async execute(sql2, params) {
+      return await driver.execute(sql2, params);
+    },
+    async close() {
+      await driver.close();
+    }
+  };
+}
 function asAsync(driver) {
   const syncIterate = driver.iterate?.bind(driver);
   return {
@@ -2092,8 +2570,8 @@ function asAsync(driver) {
     } : {}
   };
 }
-function openSqliteDriver(path, _options) {
-  return NodeSqliteDriver.open(path);
+function openSqliteDriver(path, options) {
+  return NodeSqliteDriver.open(path, options?.driverOptions);
 }
 function createSyncEngine(url, options) {
   const parsed = parseDatabaseUrl(url);
@@ -2103,7 +2581,7 @@ function createSyncEngine(url, options) {
     );
   }
   return new SyncEngine(
-    openSqliteDriver(parsed.database ?? ":memory:"),
+    openSqliteDriver(parsed.database ?? ":memory:", options),
     options?.onQuery
   );
 }
@@ -2111,20 +2589,20 @@ function createEngine(url, options) {
   const parsed = parseDatabaseUrl(url);
   if (parsed.dialect === "sqlite") {
     return new AsyncEngine(
-      asAsync(openSqliteDriver(parsed.database ?? ":memory:")),
+      asAsync(openSqliteDriver(parsed.database ?? ":memory:", options)),
       "sqlite",
       options?.onQuery
     );
   }
   if (parsed.dialect === "mysql") {
     return new AsyncEngine(
-      createMysqlDriver(parsed.raw, options?.pool),
+      createMysqlDriver(parsed.raw, options),
       "mysql",
       options?.onQuery
     );
   }
   return new AsyncEngine(
-    createPostgresDriver(parsed.raw, options?.pool),
+    createPostgresDriver(parsed.raw, options),
     "postgresql",
     options?.onQuery
   );
@@ -2144,7 +2622,8 @@ function toMysqlResult(rows) {
   const header = rows;
   return { rows: [], changes: header.affectedRows ?? 0 };
 }
-function createMysqlDriver(url, pool) {
+function createMysqlDriver(url, options) {
+  const pool = options?.pool;
   let poolHandle;
   const ensure = async () => {
     if (poolHandle) return;
@@ -2157,6 +2636,7 @@ function createMysqlDriver(url, pool) {
     if (pool?.size !== void 0) opts.connectionLimit = pool.size;
     if (pool?.idleTimeoutMs !== void 0) opts.idleTimeout = pool.idleTimeoutMs;
     if (pool?.connectTimeoutMs !== void 0) opts.connectTimeout = pool.connectTimeoutMs;
+    Object.assign(opts, options?.driverOptions ?? {});
     poolHandle = mod.createPool(opts);
   };
   const runOn = async (queryable, sql2, params) => {
@@ -2190,7 +2670,8 @@ function toPostgresResult(rows) {
   const arr = rows;
   return { rows: Array.from(arr), changes: arr.count ?? arr.length };
 }
-function createPostgresDriver(url, pool) {
+function createPostgresDriver(url, options) {
+  const pool = options?.pool;
   let client;
   const ensure = async () => {
     if (client) return;
@@ -2206,6 +2687,8 @@ function createPostgresDriver(url, pool) {
     if (pool?.connectTimeoutMs !== void 0) {
       opts.connect_timeout = Math.ceil(pool.connectTimeoutMs / 1e3);
     }
+    opts.onnotice = (notice) => emitNotice(options?.onNotice, notice);
+    Object.assign(opts, options?.driverOptions ?? {});
     client = (mod.default ?? mod)(url, opts);
   };
   return {
@@ -2558,8 +3041,8 @@ function columnNamesOf(model) {
   const map = {};
   const seen = /* @__PURE__ */ new Map();
   let renamed = false;
-  for (const [prop, col] of Object.entries(columnsOf(model))) {
-    const dbName = col.dbName ?? (strategy === "snake_case" ? toSnakeCase(prop) : prop);
+  for (const [prop, col2] of Object.entries(columnsOf(model))) {
+    const dbName = col2.dbName ?? (strategy === "snake_case" ? toSnakeCase(prop) : prop);
     const collision = seen.get(dbName);
     if (collision !== void 0) {
       throw new Error(
@@ -2600,6 +3083,7 @@ exports.BaseDialect = BaseDialect;
 exports.BaseRepository = BaseRepository;
 exports.Column = Column;
 exports.DeleteBuilder = DeleteBuilder;
+exports.Expression = Expression;
 exports.InsertBuilder = InsertBuilder;
 exports.InvalidDatabaseUrl = InvalidDatabaseUrl;
 exports.JoinBuilder = JoinBuilder;
@@ -2623,6 +3107,7 @@ exports.activeRecord = activeRecord;
 exports.and = and;
 exports.avg = avg;
 exports.belongsTo = belongsTo;
+exports.col = col;
 exports.column = column;
 exports.columnNamesOf = columnNamesOf;
 exports.columnPropsOf = columnPropsOf;
@@ -2633,13 +3118,16 @@ exports.createSyncEngine = createSyncEngine;
 exports.dbColumn = dbColumn;
 exports.del = del;
 exports.detectDialect = detectDialect;
+exports.fn = fn;
 exports.foreignKey = foreignKey;
 exports.fromDict = fromDict;
 exports.getDialect = getDialect;
 exports.hasMany = hasMany;
 exports.insert = insert;
 exports.isCondition = isCondition;
+exports.isExpression = isExpression;
 exports.isSqlExpression = isSqlExpression;
+exports.isSubquery = isSubquery;
 exports.join = join;
 exports.loadRelations = loadRelations;
 exports.max = max;
@@ -2652,11 +3140,13 @@ exports.select = select;
 exports.sql = sql;
 exports.stringify = stringify;
 exports.sum = sum;
+exports.toAsyncDriver = toAsyncDriver;
 exports.toCondNode = toCondNode;
 exports.toDict = toDict;
 exports.toJSON = toJSON;
 exports.toSnakeCase = toSnakeCase;
 exports.unique = unique;
 exports.update = update;
+exports.val = val;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map