tempest-db-js 0.4.0 → 0.6.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",
@@ -40,14 +179,18 @@ var OPERATORS = [
   "lte",
   "like",
   "ilike",
+  "ieq",
   "in",
   "notIn",
   "between",
-  "isNull"
+  "isNull",
+  "contains",
+  "containedBy",
+  "overlaps"
 ];
 var Agg = class {
-  constructor(fn, column2) {
-    this.fn = fn;
+  constructor(fn2, column2) {
+    this.fn = fn2;
     this.column = column2;
   }
   fn;
@@ -76,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 });
@@ -113,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 }]
@@ -127,7 +307,87 @@ 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()`.
+   *
+   * `{ skipLocked: true }` is the job-queue claim: competing workers each take a
+   * disjoint batch instead of blocking on — or worse, double-processing — the
+   * same rows.
+   *
+   * PostgreSQL and MySQL 8.0+ only. SQLite has no row-level locking, and its
+   * dialect throws rather than emitting a `SELECT` that silently locks nothing —
+   * a lock that does not exist only fails under production concurrency.
+   *
+   * @param options `skipLocked` / `noWait` wait behavior, and `of` to restrict
+   *   the lock to specific tables.
+   * @returns A builder carrying the locking clause.
+   * @throws Error When both `skipLocked` and `noWait` are set.
+   *
+   * @example
+   * ```ts
+   * const batch = await session.execute(
+   *   select(Outbound)
+   *     .where({ status: "queued" })
+   *     .orderBy("nextAttemptAt")
+   *     .limit(10)
+   *     .forUpdate({ skipLocked: true }),
+   * ).all();
+   * ```
+   */
+  forUpdate(options) {
+    return this.with({ lock: buildLock("update", options) });
+  }
+  /**
+   * Take a shared read lock on the selected rows (`SELECT ... FOR SHARE`), the
+   * weaker counterpart of {@link SelectBuilder.forUpdate}.
+   *
+   * @param options `skipLocked` / `noWait` wait behavior, and `of` tables.
+   * @returns A builder carrying the locking clause.
+   * @throws Error When both `skipLocked` and `noWait` are set.
+   */
+  forShare(options) {
+    return this.with({ lock: buildLock("share", options) });
+  }
 };
+function buildLock(strength, options) {
+  if (options?.skipLocked && options?.noWait) {
+    throw new Error("forUpdate/forShare accept skipLocked or noWait, not both.");
+  }
+  const wait = options?.skipLocked ? "skipLocked" : options?.noWait ? "noWait" : "block";
+  return { strength, wait, of: options?.of ?? [] };
+}
 function select(model, columns) {
   return new SelectBuilder(
     {
@@ -140,13 +400,223 @@ function select(model, columns) {
       where: void 0,
       orderBy: [],
       limit: void 0,
-      offset: void 0
+      offset: void 0,
+      names: columnNamesOf(model) ?? void 0
     },
     model
   );
 }
 
+// src/serialize.ts
+var ValidationError = class extends Error {
+  constructor(table, issues) {
+    super(`Validation failed for ${table}:
+  - ${issues.join("\n  - ")}`);
+    this.table = table;
+    this.issues = issues;
+    this.name = "ValidationError";
+  }
+  table;
+  issues;
+};
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function fromBase64(value) {
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(value, "base64"));
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function encodeValue(column2, value) {
+  if (value === null || value === void 0) return null;
+  switch (column2.type.kind) {
+    case "bigint":
+      return typeof value === "bigint" ? value.toString() : value;
+    case "date":
+    case "datetime":
+    case "timestamp":
+      return value instanceof Date ? value.toISOString() : value;
+    case "blob":
+      return value instanceof Uint8Array ? toBase64(value) : value;
+    default:
+      return value;
+  }
+}
+function decodeValue(column2, value) {
+  if (value === null || value === void 0) return null;
+  switch (column2.type.kind) {
+    case "bigint":
+      return typeof value === "bigint" ? value : BigInt(value);
+    case "date":
+    case "datetime":
+    case "timestamp":
+      return value instanceof Date ? value : new Date(value);
+    case "blob":
+      return value instanceof Uint8Array ? value : fromBase64(value);
+    case "json":
+      return typeof value === "string" ? JSON.parse(value) : value;
+    case "array": {
+      const element = column2.type.meta.element;
+      const items = typeof value === "string" ? JSON.parse(value) : value;
+      if (!Array.isArray(items)) return items;
+      if (!element) return items;
+      return items.map((item) => decodeValue({ type: element }, item));
+    }
+    case "numeric":
+      return typeof value === "string" ? value : String(value);
+    case "boolean":
+      return typeof value === "boolean" ? value : value === 1 || value === "true";
+    case "smallint":
+    case "integer":
+    case "real":
+    case "double":
+      return typeof value === "number" ? value : Number(value);
+    default:
+      return value;
+  }
+}
+function toDict(model, row) {
+  const columns = columnsOf(model);
+  const out = {};
+  for (const name of Object.keys(columns)) {
+    out[name] = row[name] ?? null;
+  }
+  return out;
+}
+function toJSON(model, row) {
+  const columns = columnsOf(model);
+  const out = {};
+  for (const [name, col2] of Object.entries(columns)) {
+    out[name] = encodeValue(col2, row[name] ?? null);
+  }
+  return out;
+}
+function stringify(model, row) {
+  return JSON.stringify(toJSON(model, row));
+}
+function fromDict(model, data) {
+  const columns = columnsOf(model);
+  const out = {};
+  const issues = [];
+  for (const [name, col2] of Object.entries(columns)) {
+    const present = name in data && data[name] !== void 0 && data[name] !== null;
+    if (!present) {
+      const required = col2.flags.notNull && !col2.flags.hasDefault;
+      if (required) {
+        issues.push(`missing required column "${name}"`);
+        continue;
+      }
+      out[name] = null;
+      continue;
+    }
+    try {
+      out[name] = decodeValue(col2, data[name]);
+    } catch (error) {
+      issues.push(`column "${name}": ${error.message}`);
+    }
+  }
+  if (issues.length > 0) {
+    throw new ValidationError(model.tablename, issues);
+  }
+  return out;
+}
+function parse(model, json) {
+  return fromDict(model, JSON.parse(json));
+}
+function decoderFor(type) {
+  switch (type.kind) {
+    case "bigint":
+      return (v) => v == null ? null : typeof v === "bigint" ? v : BigInt(v);
+    case "date":
+    case "datetime":
+    case "timestamp":
+      return (v) => v == null ? null : v instanceof Date ? v : new Date(v);
+    case "blob":
+      return (v) => v == null ? null : v instanceof Uint8Array ? v : fromBase64(v);
+    case "json":
+      return (v) => v == null ? null : typeof v === "string" ? JSON.parse(v) : v;
+    case "array": {
+      const element = type.meta.element;
+      const inner = element ? decoderFor(element) : null;
+      if (!inner) return null;
+      return (v) => v == null ? null : Array.isArray(v) ? v.map(inner) : v;
+    }
+    case "numeric":
+      return (v) => v == null ? null : typeof v === "string" ? v : String(v);
+    case "boolean":
+      return (v) => v == null ? null : typeof v === "boolean" ? v : v === 1 || v === "true";
+    case "smallint":
+    case "integer":
+    case "real":
+    case "double":
+      return (v) => v == null ? null : typeof v === "number" ? v : Number(v);
+    default:
+      return null;
+  }
+}
+var mapperCache = /* @__PURE__ */ new WeakMap();
+function mapperFor(model) {
+  const cached = mapperCache.get(model);
+  if (cached) return cached;
+  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, col2] of Object.entries(columnsOf(model))) {
+    const decoder = decoderFor(col2.type);
+    if (decoder) decoders.set(names?.[prop] ?? prop, decoder);
+  }
+  const mapper = { props, decoders };
+  mapperCache.set(model, mapper);
+  return mapper;
+}
+function coerceRow(model, raw) {
+  const { props, decoders } = mapperFor(model);
+  const out = {};
+  for (const name of Object.keys(raw)) {
+    const decode2 = decoders.get(name);
+    out[props?.[name] ?? name] = decode2 ? decode2(raw[name]) : raw[name];
+  }
+  return out;
+}
+
 // src/mutations.ts
+var STRUCTURED_KINDS = /* @__PURE__ */ new Set(["json", "array", "blob"]);
+function isBindableScalar(value) {
+  if (value === null || value === void 0) return true;
+  const type = typeof value;
+  if (type === "string" || type === "number" || type === "bigint" || type === "boolean") {
+    return true;
+  }
+  return value instanceof Date || value instanceof Uint8Array;
+}
+function assertWritableValues(model, values, clause) {
+  const columns = columnsOf(model);
+  const issues = [];
+  for (const [key, value] of Object.entries(values)) {
+    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(col2.type.kind)) continue;
+    issues.push(
+      `${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 describeValue(value) {
+  if (typeof value === "function") return "a function";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "symbol") return "a symbol";
+  return "an object";
+}
 var InsertBuilder = class _InsertBuilder {
   constructor(node, source) {
     this.node = node;
@@ -157,28 +627,66 @@ var InsertBuilder = class _InsertBuilder {
   with(patch) {
     return new _InsertBuilder({ ...this.node, ...patch }, this.source);
   }
-  /** Provide one row or many rows to insert, typed by the insert shape. */
+  /**
+   * Provide one row or many rows to insert, typed by the insert shape.
+   *
+   * @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).
+   */
   values(rows) {
     const list = Array.isArray(rows) ? rows : [rows];
+    for (const row of list) assertWritableValues(this.source, row, "values");
     return this.with({ values: list });
   }
   /**
    * On a unique/PK conflict on `target`, do nothing (skip the row).
    *
    * @param target The conflicting column(s) — a unique or primary key.
+   * @param options Pass `where` to name the predicate of a **partial** unique
+   *   index, which PostgreSQL requires in order to match it as a conflict target.
+   * @returns A builder carrying the conflict clause.
+   *
+   * @example
+   * ```ts
+   * insert(Outbound)
+   *   .values(data)
+   *   .onConflictDoNothing(["consumer", "idempotencyKey"], {
+   *     where: { idempotencyKey: { isNull: false } },
+   *   })
+   *   .returning();
+   * ```
    */
-  onConflictDoNothing(target) {
-    return this.with({ onConflict: { target, update: "nothing" } });
+  onConflictDoNothing(target, options) {
+    return this.with({
+      onConflict: {
+        target,
+        update: "nothing",
+        targetWhere: options?.where ? toCondNode(options.where) : void 0
+      }
+    });
   }
   /**
    * On a unique/PK conflict on `target`, overwrite the given columns (upsert).
    *
    * @param target The conflicting column(s) — a unique or primary key.
    * @param set The columns to update with new values.
+   * @param options `indexWhere` names the predicate of a partial unique index
+   *   (the conflict target); `updateWhere` further restricts which conflicting
+   *   rows are rewritten.
+   * @returns A builder carrying the conflict clause.
+   * @throws ValidationError When a `set` value cannot be bound.
    */
-  onConflictDoUpdate(target, set) {
+  onConflictDoUpdate(target, set, options) {
+    assertWritableValues(this.source, set, "set");
     return this.with({
-      onConflict: { target, update: set }
+      onConflict: {
+        target,
+        update: set,
+        targetWhere: options?.indexWhere ? toCondNode(options.indexWhere) : void 0,
+        updateWhere: options?.updateWhere ? toCondNode(options.updateWhere) : void 0
+      }
     });
   }
   returning(columns) {
@@ -191,7 +699,8 @@ function insert(model) {
       kind: "insert",
       table: model.tablename,
       values: [],
-      returning: null
+      returning: null,
+      names: columnNamesOf(model) ?? void 0
     },
     model
   );
@@ -206,8 +715,27 @@ var UpdateBuilder = class _UpdateBuilder {
   with(patch) {
     return new _UpdateBuilder({ ...this.node, ...patch }, this.source);
   }
-  /** The columns to write. Partial — only the given columns change. */
+  /**
+   * The columns to write. Partial — only the given columns change.
+   *
+   * A value is bound as a parameter unless it is a {@link sql} expression, which
+   * is rendered inline instead — that is how a counter is written without a
+   * read-modify-write race.
+   *
+   * @param values The column → value map.
+   * @returns A builder carrying the assignments.
+   * @throws ValidationError When a value is not a column value the dialect can
+   *   bind (a bare object, an array on a scalar column, a function).
+   *
+   * @example
+   * ```ts
+   * update(Outbound)
+   *   .set({ attempts: sql.raw("attempts + 1"), updatedAt: sql.now() })
+   *   .where({ id });
+   * ```
+   */
   set(values) {
+    assertWritableValues(this.source, values, "set");
     return this.with({ set: values });
   }
   /** Restrict the rows to update. Marks the builder safe to execute. */
@@ -233,7 +761,8 @@ function update(model) {
       set: {},
       where: void 0,
       guarded: false,
-      returning: null
+      returning: null,
+      names: columnNamesOf(model) ?? void 0
     },
     model
   );
@@ -270,7 +799,8 @@ function del(model) {
       table: model.tablename,
       where: void 0,
       guarded: false,
-      returning: null
+      returning: null,
+      names: columnNamesOf(model) ?? void 0
     },
     model
   );
@@ -365,173 +895,28 @@ function parseDatabaseUrl(url) {
   if (!dialect) {
     throw new InvalidDatabaseUrl(url, `unknown dialect ${JSON.stringify(base)}`);
   }
-  const rest = url.slice(schemeEnd + 1);
-  if (dialect === "sqlite") return parseSqlite(url, driver, rest);
-  return parseNetworkUrl(url, driver, rest, dialect);
-}
-function detectDialect(url) {
-  return parseDatabaseUrl(url).dialect;
-}
-
-// src/serialize.ts
-var ValidationError = class extends Error {
-  constructor(table, issues) {
-    super(`Validation failed for ${table}:
-  - ${issues.join("\n  - ")}`);
-    this.table = table;
-    this.issues = issues;
-    this.name = "ValidationError";
-  }
-  table;
-  issues;
-};
-function toBase64(bytes) {
-  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
-  let binary = "";
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary);
-}
-function fromBase64(value) {
-  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(value, "base64"));
-  const binary = atob(value);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
-function encodeValue(column2, value) {
-  if (value === null || value === void 0) return null;
-  switch (column2.type.kind) {
-    case "bigint":
-      return typeof value === "bigint" ? value.toString() : value;
-    case "date":
-    case "datetime":
-    case "timestamp":
-      return value instanceof Date ? value.toISOString() : value;
-    case "blob":
-      return value instanceof Uint8Array ? toBase64(value) : value;
-    default:
-      return value;
-  }
-}
-function decodeValue(column2, value) {
-  if (value === null || value === void 0) return null;
-  switch (column2.type.kind) {
-    case "bigint":
-      return typeof value === "bigint" ? value : BigInt(value);
-    case "date":
-    case "datetime":
-    case "timestamp":
-      return value instanceof Date ? value : new Date(value);
-    case "blob":
-      return value instanceof Uint8Array ? value : fromBase64(value);
-    case "json":
-      return typeof value === "string" ? JSON.parse(value) : value;
-    case "numeric":
-      return typeof value === "string" ? value : String(value);
-    case "boolean":
-      return typeof value === "boolean" ? value : value === 1 || value === "true";
-    case "smallint":
-    case "integer":
-    case "real":
-    case "double":
-      return typeof value === "number" ? value : Number(value);
-    default:
-      return value;
-  }
-}
-function toDict(model, row) {
-  const columns = columnsOf(model);
-  const out = {};
-  for (const name of Object.keys(columns)) {
-    out[name] = row[name] ?? null;
-  }
-  return out;
-}
-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);
-  }
-  return out;
-}
-function stringify(model, row) {
-  return JSON.stringify(toJSON(model, row));
-}
-function fromDict(model, data) {
-  const columns = columnsOf(model);
-  const out = {};
-  const issues = [];
-  for (const [name, col] 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;
-      if (required) {
-        issues.push(`missing required column "${name}"`);
-        continue;
-      }
-      out[name] = null;
-      continue;
-    }
-    try {
-      out[name] = decodeValue(col, data[name]);
-    } catch (error) {
-      issues.push(`column "${name}": ${error.message}`);
-    }
-  }
-  if (issues.length > 0) {
-    throw new ValidationError(model.tablename, issues);
-  }
-  return out;
-}
-function parse(model, json) {
-  return fromDict(model, JSON.parse(json));
-}
-function decoderForKind(kind) {
-  switch (kind) {
-    case "bigint":
-      return (v) => v == null ? null : typeof v === "bigint" ? v : BigInt(v);
-    case "date":
-    case "datetime":
-    case "timestamp":
-      return (v) => v == null ? null : v instanceof Date ? v : new Date(v);
-    case "blob":
-      return (v) => v == null ? null : v instanceof Uint8Array ? v : fromBase64(v);
-    case "json":
-      return (v) => v == null ? null : typeof v === "string" ? JSON.parse(v) : v;
-    case "numeric":
-      return (v) => v == null ? null : typeof v === "string" ? v : String(v);
-    case "boolean":
-      return (v) => v == null ? null : typeof v === "boolean" ? v : v === 1 || v === "true";
-    case "smallint":
-    case "integer":
-    case "real":
-    case "double":
-      return (v) => v == null ? null : typeof v === "number" ? v : Number(v);
-    default:
-      return null;
-  }
-}
-var decoderCache = /* @__PURE__ */ new WeakMap();
-function decodersFor(model) {
-  const cached = decoderCache.get(model);
-  if (cached) return cached;
-  const map = /* @__PURE__ */ new Map();
-  for (const [name, col] of Object.entries(columnsOf(model))) {
-    const decoder = decoderForKind(col.type.kind);
-    if (decoder) map.set(name, decoder);
-  }
-  decoderCache.set(model, map);
-  return map;
+  const rest = url.slice(schemeEnd + 1);
+  if (dialect === "sqlite") return parseSqlite(url, driver, rest);
+  return parseNetworkUrl(url, driver, rest, dialect);
 }
-function coerceRow(model, raw) {
-  const decoders = decodersFor(model);
-  const out = {};
-  for (const name of Object.keys(raw)) {
-    const decode2 = decoders.get(name);
-    out[name] = decode2 ? decode2(raw[name]) : raw[name];
+function detectDialect(url) {
+  return parseDatabaseUrl(url).dialect;
+}
+
+// src/expressions.ts
+function renderPortableToken(token, dialect) {
+  switch (token) {
+    case "now":
+      return dialect === "postgresql" ? "now()" : "CURRENT_TIMESTAMP";
+    case "current_date":
+      return "CURRENT_DATE";
+    case "current_time":
+      return "CURRENT_TIME";
+    case "uuidv4":
+      if (dialect === "postgresql") return "gen_random_uuid()";
+      if (dialect === "mysql") return "(UUID())";
+      return "(lower(hex(randomblob(16))))";
   }
-  return out;
 }
 
 // src/dialect.ts
@@ -554,6 +939,20 @@ var Params = class {
     return this.placeholder(this.values.length);
   }
 };
+function insertHasExpression(node) {
+  for (const row of node.values) {
+    for (const value of Object.values(row)) {
+      if (isSqlExpression(value)) return true;
+    }
+  }
+  const update2 = node.onConflict?.update;
+  if (update2 && update2 !== "nothing") {
+    for (const value of Object.values(update2)) {
+      if (isSqlExpression(value)) return true;
+    }
+  }
+  return false;
+}
 var BaseDialect = class _BaseDialect {
   /**
    * INSERT SQL templates keyed by structure (dialect|table|columns|rowCount|
@@ -563,6 +962,30 @@ 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.
+   *
+   * Only PostgreSQL has native arrays; the other dialects throw rather than
+   * emitting an operator that means something else there.
+   *
+   * @param op The array operator name.
+   * @returns The SQL operator text.
+   * @throws Error On a dialect without native array support.
+   */
+  arrayOperator(op) {
+    throw new Error(
+      `The "${op}" operator needs native array support, which ${this.name} does not have.`
+    );
+  }
   /**
    * Quote an identifier (column/table) for the active dialect.
    *
@@ -601,51 +1024,199 @@ var BaseDialect = class _BaseDialect {
     }
     return { sql: sql2, params: params.values };
   }
-  /** Render a qualified `alias.column` ref as `"alias"."column"`. */
-  qualify(ref) {
+  /**
+   * Render a qualified `alias.column` ref as `"alias"."column"`, translating the
+   * property name to the real column name for that alias's model.
+   *
+   * @param ref The `alias.property` reference (a bare name is left unqualified).
+   * @param names The node's per-alias name maps, if any source renames columns.
+   * @returns The quoted, qualified identifier.
+   */
+  qualify(ref, names) {
     const dot = ref.indexOf(".");
     if (dot === -1) return this.quoteId(ref);
-    return `${this.quoteId(ref.slice(0, dot))}.${this.quoteId(ref.slice(dot + 1))}`;
+    const alias = ref.slice(0, dot);
+    const prop = ref.slice(dot + 1);
+    return `${this.quoteId(alias)}.${this.columnId(prop, names?.[alias])}`;
+  }
+  /**
+   * Quote a column identifier, translating the model property name to the real
+   * database column name first.
+   *
+   * `names` is `undefined` for a model that renames nothing — the overwhelmingly
+   * common case — so this stays a single lookup plus the memoized quote.
+   *
+   * @param prop The model property name as written in the builder.
+   * @param names The node's property → column map, if any.
+   * @returns The quoted database identifier.
+   */
+  columnId(prop, names) {
+    return this.quoteId(names?.[prop] ?? prop);
+  }
+  /**
+   * Render a {@link SqlExpression} inline, binding the parameters it carries.
+   *
+   * This is what keeps `set({ attempts: sql.raw("attempts + 1") })` an expression
+   * instead of a bound object: the fragment goes into the statement text, and
+   * only a `sql.expr` template's interpolations become parameters.
+   *
+   * @param expr The branded expression.
+   * @param params The parameter collector for the statement being compiled.
+   * @returns The SQL text of the expression.
+   */
+  renderExpression(expr, params) {
+    const token = expr.expression;
+    if (typeof token === "string") return renderPortableToken(token, this.name);
+    if ("raw" in token) return token.raw;
+    const parts = token.parts;
+    let sql2 = parts[0] ?? "";
+    for (let i = 1; i < parts.length; i++) {
+      sql2 += `${params.bind(expr.params[i - 1])}${parts[i]}`;
+    }
+    return sql2;
+  }
+  /** Render one write value: a SQL expression inline, anything else as a parameter. */
+  renderValue(value, params) {
+    return isSqlExpression(value) ? this.renderExpression(value, params) : params.bind(value);
+  }
+  /**
+   * Render a row-level locking clause (`FOR UPDATE ...`).
+   *
+   * Standard on PostgreSQL and MySQL 8.0+; SQLite overrides it to throw.
+   *
+   * @param lock The locking clause from the node.
+   * @returns The SQL text, leading space included.
+   */
+  renderLock(lock) {
+    const strength = lock.strength === "update" ? "FOR UPDATE" : "FOR SHARE";
+    const of = lock.of.length > 0 ? ` OF ${lock.of.map((t) => this.quoteId(t)).join(", ")}` : "";
+    const wait = lock.wait === "skipLocked" ? " SKIP LOCKED" : lock.wait === "noWait" ? " NOWAIT" : "";
+    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;
     if (node.aggregates.length > 0) {
-      const groupSel = node.groupBy.map((c) => this.quoteId(c));
+      const groupSel = node.groupBy.map((c) => this.columnId(c, names));
       const aggSel = node.aggregates.map((a) => {
-        const inner = a.column === "*" ? "*" : this.quoteId(a.column);
+        const inner = a.column === "*" ? "*" : this.columnId(a.column, names);
         return `${a.fn.toUpperCase()}(${inner}) AS ${this.quoteId(a.alias)}`;
       });
       cols = [...groupSel, ...aggSel].join(", ");
     } else {
-      cols = node.columns === "*" ? "*" : node.columns.map((c) => this.quoteId(c)).join(", ");
+      cols = node.columns === "*" ? "*" : node.columns.map((c) => this.columnId(c, names)).join(", ");
     }
     let sql2 = `SELECT ${node.distinct ? "DISTINCT " : ""}${cols} FROM ${this.quoteId(node.table)}`;
-    const where = this.compileCondition(node.where, params, (k) => this.quoteId(k));
+    const where = this.compileCondition(
+      node.where,
+      params,
+      (k) => this.columnId(k, names)
+    );
     if (where) sql2 += ` WHERE ${where}`;
     if (node.groupBy.length > 0) {
-      sql2 += ` GROUP BY ${node.groupBy.map((c) => this.quoteId(c)).join(", ")}`;
+      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.quoteId(t.column)} ${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)}`;
     if (node.offset !== void 0) sql2 += ` OFFSET ${params.bind(node.offset)}`;
+    if (node.lock) {
+      if (node.distinct || node.groupBy.length > 0 || node.aggregates.length > 0) {
+        throw new Error(
+          "FOR UPDATE / FOR SHARE cannot be combined with DISTINCT or an aggregate query \u2014 lock the underlying rows in a separate SELECT."
+        );
+      }
+      sql2 += this.renderLock(node.lock);
+    }
     return sql2;
   }
+  /**
+   * Compile an INSERT.
+   *
+   * Takes the cached fast path only when the statement text is a pure function of
+   * its structure. A SQL expression among the values, or a conflict predicate,
+   * makes the text depend on the values themselves — those compile uncached, in
+   * SQL order, so placeholder positions stay correct.
+   */
   compileInsert(node, params) {
     const columns = node.values.length > 0 ? Object.keys(node.values[0]) : [];
+    const conflict = node.onConflict;
+    const cacheable = conflict?.targetWhere === void 0 && conflict?.updateWhere === void 0 && !insertHasExpression(node);
+    if (!cacheable) return this.compileInsertDirect(node, columns, params);
     for (const row of node.values) {
       for (const c of columns) params.bind(row[c] ?? null);
     }
-    const conflictCols = node.onConflict && node.onConflict.update !== "nothing" ? Object.keys(node.onConflict.update) : [];
+    const conflictCols = conflict && conflict.update !== "nothing" ? Object.keys(conflict.update) : [];
     for (const c of conflictCols) {
-      params.bind((node.onConflict?.update)[c]);
+      params.bind((conflict?.update)[c]);
+    }
+    return this.insertTemplate(node, columns, conflictCols, params);
+  }
+  /**
+   * Compile an INSERT without the template cache, rendering clauses in statement
+   * order so every parameter is bound at the position it appears.
+   *
+   * @param node The insert node.
+   * @param columns The column keys shared by every row.
+   * @param params The parameter collector.
+   * @returns The SQL text.
+   */
+  compileInsertDirect(node, columns, params) {
+    const names = node.names;
+    const colSql = columns.map((c) => this.columnId(c, names)).join(", ");
+    const rowsSql = node.values.map((row) => {
+      const cells = columns.map(
+        (c) => this.renderValue(row[c] ?? null, params)
+      );
+      return `(${cells.join(", ")})`;
+    }).join(", ");
+    let sql2 = `INSERT INTO ${this.quoteId(node.table)} (${colSql}) VALUES ${rowsSql}`;
+    if (node.onConflict) {
+      const update2 = node.onConflict.update;
+      const conflictCols = update2 === "nothing" ? [] : Object.keys(update2);
+      let cursor = 0;
+      sql2 += this.renderConflict(
+        node.onConflict,
+        conflictCols,
+        () => {
+          const key = conflictCols[cursor++];
+          return this.renderValue(update2[key], params);
+        },
+        names,
+        params
+      );
     }
-    return this.insertTemplate(node, columns, conflictCols);
+    sql2 += this.compileReturning(node.returning, names);
+    return sql2;
   }
   /**
    * The INSERT SQL template for a given structure, cached across calls.
@@ -655,13 +1226,14 @@ var BaseDialect = class _BaseDialect {
    * deterministic from the counts (a fresh statement always starts binding at 1).
    * So a per-row insert loop compiles the string once and reuses it every row.
    */
-  insertTemplate(node, columns, conflictCols) {
+  insertTemplate(node, columns, conflictCols, params) {
     const returningKey = node.returning === null ? "" : node.returning === "*" ? "*" : node.returning.join(",");
     const conflictKey = node.onConflict ? `${node.onConflict.target.join(",")}>${node.onConflict.update === "nothing" ? "nothing" : conflictCols.join(",")}` : "";
     const key = `${this.name}|${node.table}|${columns.join(",")}|${node.values.length}|${returningKey}|${conflictKey}`;
     const cached = _BaseDialect.insertTemplates.get(key);
     if (cached !== void 0) return cached;
-    const colSql = columns.map((c) => this.quoteId(c)).join(", ");
+    const names = node.names;
+    const colSql = columns.map((c) => this.columnId(c, names)).join(", ");
     let position = 0;
     const rowsSql = node.values.map(() => `(${columns.map(() => this.placeholder(++position)).join(", ")})`).join(", ");
     let sql2 = `INSERT INTO ${this.quoteId(node.table)} (${colSql}) VALUES ${rowsSql}`;
@@ -669,57 +1241,91 @@ var BaseDialect = class _BaseDialect {
       sql2 += this.renderConflict(
         node.onConflict,
         conflictCols,
-        () => this.placeholder(++position)
+        () => this.placeholder(++position),
+        names,
+        params
       );
     }
-    sql2 += this.compileReturning(node.returning);
+    sql2 += this.compileReturning(node.returning, names);
     _BaseDialect.insertTemplates.set(key, sql2);
     return sql2;
   }
   /**
    * Render the conflict-handling clause. Standard SQL (SQLite/PostgreSQL) uses
-   * `ON CONFLICT (...) DO NOTHING | DO UPDATE SET ...`; MySQL overrides this.
+   * `ON CONFLICT (...) [WHERE predicate] DO NOTHING | DO UPDATE SET ... [WHERE ...]`;
+   * MySQL overrides this.
+   *
+   * The index predicate is rendered before the `DO UPDATE` assignments because
+   * that is where it sits in the statement, so its parameters bind first.
    *
    * @param onConflict The conflict clause from the node.
    * @param conflictCols The columns to overwrite on `DO UPDATE` (empty for nothing).
-   * @param nextPlaceholder Yields the next positional placeholder (advances the count).
+   * @param nextValue Yields the SQL for the next `DO UPDATE` assignment value.
+   * @param names The node's property → column map, if any.
+   * @param params The parameter collector, for the predicates.
+   * @returns The SQL text, leading space included.
    */
-  renderConflict(onConflict, conflictCols, nextPlaceholder) {
-    const target = onConflict.target.map((c) => this.quoteId(c)).join(", ");
-    if (onConflict.update === "nothing") return ` ON CONFLICT (${target}) DO NOTHING`;
-    const assignments = conflictCols.map((c) => `${this.quoteId(c)} = ${nextPlaceholder()}`).join(", ");
-    return ` ON CONFLICT (${target}) DO UPDATE SET ${assignments}`;
+  renderConflict(onConflict, conflictCols, nextValue, names, params) {
+    const idFor = (key) => this.columnId(key, names);
+    const target = onConflict.target.map(idFor).join(", ");
+    const indexWhere = this.compileCondition(onConflict.targetWhere, params, idFor);
+    const targetSql = indexWhere ? `(${target}) WHERE ${indexWhere}` : `(${target})`;
+    if (onConflict.update === "nothing") return ` ON CONFLICT ${targetSql} DO NOTHING`;
+    const assignments = conflictCols.map((c) => `${idFor(c)} = ${nextValue()}`).join(", ");
+    let sql2 = ` ON CONFLICT ${targetSql} DO UPDATE SET ${assignments}`;
+    const updateWhere = this.compileCondition(onConflict.updateWhere, params, idFor);
+    if (updateWhere) sql2 += ` WHERE ${updateWhere}`;
+    return sql2;
   }
   compileUpdate(node, params) {
-    const sets = Object.entries(node.set).map(([col, value]) => `${this.quoteId(col)} = ${params.bind(value)}`).join(", ");
+    const names = node.names;
+    const sets = Object.entries(node.set).map(
+      ([col2, value]) => `${this.columnId(col2, names)} = ${this.renderValue(value, params)}`
+    ).join(", ");
     let sql2 = `UPDATE ${this.quoteId(node.table)} SET ${sets}`;
-    const where = this.compileCondition(node.where, params, (k) => this.quoteId(k));
+    const where = this.compileCondition(
+      node.where,
+      params,
+      (k) => this.columnId(k, names)
+    );
     if (where) sql2 += ` WHERE ${where}`;
-    sql2 += this.compileReturning(node.returning);
+    sql2 += this.compileReturning(node.returning, names);
     return sql2;
   }
   compileDelete(node, params) {
+    const names = node.names;
     let sql2 = `DELETE FROM ${this.quoteId(node.table)}`;
-    const where = this.compileCondition(node.where, params, (k) => this.quoteId(k));
+    const where = this.compileCondition(
+      node.where,
+      params,
+      (k) => this.columnId(k, names)
+    );
     if (where) sql2 += ` WHERE ${where}`;
-    sql2 += this.compileReturning(node.returning);
+    sql2 += this.compileReturning(node.returning, names);
     return sql2;
   }
   compileJoin(node, params) {
+    const names = node.names;
     const cols = node.selections.map((s) => {
       const ref = `${s.alias}.${s.column}`;
-      return `${this.qualify(ref)} AS ${this.quoteId(ref)}`;
+      return `${this.qualify(ref, names)} AS ${this.quoteId(ref)}`;
     }).join(", ");
     let sql2 = `SELECT ${cols} FROM ${this.quoteId(node.base.table)} AS ${this.quoteId(node.base.alias)}`;
     for (const j of node.joins) {
       const kw = j.kind === "left" ? "LEFT JOIN" : "INNER JOIN";
-      const on = j.on.map(([l, r]) => `${this.qualify(l)} = ${this.qualify(r)}`).join(" AND ");
+      const on = j.on.map(([l, r]) => `${this.qualify(l, names)} = ${this.qualify(r, names)}`).join(" AND ");
       sql2 += ` ${kw} ${this.quoteId(j.table)} AS ${this.quoteId(j.alias)} ON ${on}`;
     }
-    const where = this.compileCondition(node.where, params, (k) => this.qualify(k));
+    const where = this.compileCondition(
+      node.where,
+      params,
+      (k) => this.qualify(k, names)
+    );
     if (where) sql2 += ` WHERE ${where}`;
     if (node.orderBy.length > 0) {
-      const terms = node.orderBy.map((t) => `${this.qualify(t.ref)} ${t.direction === "desc" ? "DESC" : "ASC"}`).join(", ");
+      const terms = node.orderBy.map(
+        (t) => `${this.qualify(t.ref, names)} ${t.direction === "desc" ? "DESC" : "ASC"}`
+      ).join(", ");
       sql2 += ` ORDER BY ${terms}`;
     }
     if (node.limit !== void 0) sql2 += ` LIMIT ${params.bind(node.limit)}`;
@@ -727,10 +1333,10 @@ var BaseDialect = class _BaseDialect {
     return sql2;
   }
   // ---- clauses ----------------------------------------------------------
-  compileReturning(returning) {
+  compileReturning(returning, names) {
     if (returning === null) return "";
     if (returning === "*") return " RETURNING *";
-    return ` RETURNING ${returning.map((c) => this.quoteId(c)).join(", ")}`;
+    return ` RETURNING ${returning.map((c) => this.columnId(c, names)).join(", ")}`;
   }
   /**
    * Compile a condition tree (fields / and / or / not) to SQL. `idFor` renders a
@@ -767,6 +1373,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) {
@@ -787,6 +1470,14 @@ var BaseDialect = class _BaseDialect {
         return `${id} LIKE ${params.bind(operand)}`;
       case "ilike":
         return this.ilike(id, params.bind(operand));
+      case "ieq":
+        return operand === null ? `${id} IS NULL` : `lower(${id}) = lower(${params.bind(operand)})`;
+      case "contains":
+        return `${id} ${this.arrayOperator("contains")} ${params.bind(operand)}`;
+      case "containedBy":
+        return `${id} ${this.arrayOperator("containedBy")} ${params.bind(operand)}`;
+      case "overlaps":
+        return `${id} ${this.arrayOperator("overlaps")} ${params.bind(operand)}`;
       case "in":
         return this.compileIn(id, operand, params, false);
       case "notIn":
@@ -801,12 +1492,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 {
@@ -817,6 +1529,16 @@ var SqliteDialect = class extends BaseDialect {
   ilike(column2, param) {
     return `${column2} LIKE ${param}`;
   }
+  /**
+   * SQLite has no row-level locking, so a lock request is an error rather than a
+   * silently unlocked `SELECT` — a lock that does not exist only shows up as
+   * duplicated work under production concurrency.
+   */
+  renderLock() {
+    throw new Error(
+      "SQLite has no row-level locking \u2014 FOR UPDATE / FOR SHARE is unsupported. Serialize the claim inside a transaction instead."
+    );
+  }
 };
 var PostgresDialect = class extends BaseDialect {
   name = "postgresql";
@@ -826,6 +1548,11 @@ var PostgresDialect = class extends BaseDialect {
   ilike(column2, param) {
     return `${column2} ILIKE ${param}`;
   }
+  arrayOperator(op) {
+    if (op === "contains") return "@>";
+    if (op === "containedBy") return "<@";
+    return "&&";
+  }
 };
 var mysqlQuotedIds = /* @__PURE__ */ new Map();
 var MysqlDialect = class extends BaseDialect {
@@ -843,18 +1570,45 @@ var MysqlDialect = class extends BaseDialect {
     mysqlQuotedIds.set(name, quoted);
     return quoted;
   }
-  renderConflict(onConflict, conflictCols, nextPlaceholder) {
+  /**
+   * 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(
+        "MySQL's ON DUPLICATE KEY UPDATE has no conflict-target predicate \u2014 a partial unique index is PostgreSQL/SQLite only."
+      );
+    }
     if (onConflict.update === "nothing") {
-      const col = this.quoteId(onConflict.target[0] ?? "id");
-      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.quoteId(c)} = ${nextPlaceholder()}`).join(", ");
+    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."
     );
   }
 };
@@ -873,6 +1627,11 @@ function getDialect(name) {
 function selectionsFor(alias, model) {
   return Object.keys(columnsOf(model)).map((column2) => ({ alias, column: column2 }));
 }
+function withAliasNames(current, alias, model) {
+  const names = columnNamesOf(model);
+  if (!names) return current;
+  return { ...current ?? {}, [alias]: names };
+}
 var JoinBuilder = class _JoinBuilder {
   constructor(node, sources) {
     this.node = node;
@@ -885,7 +1644,8 @@ var JoinBuilder = class _JoinBuilder {
       {
         ...this.node,
         joins: [...this.node.joins, clause],
-        selections: [...this.node.selections, ...selectionsFor(clause.alias, model)]
+        selections: [...this.node.selections, ...selectionsFor(clause.alias, model)],
+        names: withAliasNames(this.node.names, clause.alias, model)
       },
       { ...this.sources, [clause.alias]: model }
     );
@@ -946,7 +1706,8 @@ function join(model, alias) {
       where: void 0,
       orderBy: [],
       limit: void 0,
-      offset: void 0
+      offset: void 0,
+      names: withAliasNames(void 0, alias, model)
     },
     { [alias]: model }
   );
@@ -960,8 +1721,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`);
 }
@@ -1049,8 +1810,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`);
 }
@@ -1259,11 +2020,12 @@ function splitJoinRow(node, sources, raw) {
   const out = {};
   for (const [alias, model] of Object.entries(sources)) {
     const sub = {};
+    const names = columnNamesOf(model);
     let allNull = true;
     for (const colName of Object.keys(columnsOf(model))) {
       const value = raw[`${alias}.${colName}`];
       if (value !== null && value !== void 0) allNull = false;
-      sub[colName] = value;
+      sub[names?.[colName] ?? colName] = value;
     }
     out[alias] = leftAliases.has(alias) && allNull ? null : coerceRow(model, sub);
   }
@@ -1385,6 +2147,25 @@ 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(
+      "session.raw(sql, params) takes an array of bound parameters \u2014 never interpolate values into the SQL string."
+    );
+  }
+}
 var SyncSession = class {
   constructor(driver, dialect, logger) {
     this.driver = driver;
@@ -1403,6 +2184,44 @@ var SyncSession = class {
       throw new QueryExecutionError(error, sql2, params);
     }
   }
+  /**
+   * Run a raw, parameterized SQL statement (synchronous) — the runtime counterpart of the
+   * migrations' `Op.execute`.
+   *
+   * A query builder never covers all of SQL, and without an escape hatch a single
+   * unsupported query forces a whole second database stack alongside this one. Use
+   * it for what the builder cannot yet express, and keep everything else typed.
+   *
+   * The statement goes through the same path as a compiled one: it is logged via
+   * `onQuery`, wrapped in {@link QueryExecutionError} on failure, and runs on the
+   * reserved connection inside `transaction()`.
+   *
+   * @param sql The statement text. Placeholders only (`$1` / `?` per dialect) —
+   *   never interpolate a value into this string.
+   * @param params The bound parameters, in placeholder order.
+   * @param options Pass `as` to coerce the returned rows with a model's column
+   *   types (and its column-name mapping).
+   * @returns The result view over the returned rows.
+   * @throws Error When `params` is not an array — the guard against calling this
+   *   with an interpolated string and no parameters by mistake.
+   *
+   * @example
+   * ```ts
+   * const claimed = await session.raw<OutboundRow>(
+   *   `UPDATE outbound_messages SET status = 'sending'
+   *      WHERE id = ANY($1) RETURNING *`,
+   *   [ids],
+   *   { as: Outbound },
+   * ).all();
+   * ```
+   */
+  raw(sql2, params = [], options) {
+    assertRawParams(params);
+    const result = this.exec(sql2, params);
+    const model = options?.as;
+    const rows = model ? result.rows.map((row) => coerceRow(model, row)) : result.rows;
+    return new SyncResult(rows, result.changes);
+  }
   /** Compile, run, and coerce a builder into a result. */
   execute(builder) {
     const node = builder.node;
@@ -1412,10 +2231,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) {
@@ -1424,12 +2243,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) {
@@ -1485,8 +2304,53 @@ var AsyncSession = class _AsyncSession {
       throw new QueryExecutionError(error, sql2, params);
     }
   }
+  /**
+   * Run a raw, parameterized SQL statement — the runtime counterpart of the
+   * migrations' `Op.execute`.
+   *
+   * A query builder never covers all of SQL, and without an escape hatch a single
+   * unsupported query forces a whole second database stack alongside this one. Use
+   * it for what the builder cannot yet express, and keep everything else typed.
+   *
+   * The statement goes through the same path as a compiled one: it is logged via
+   * `onQuery`, wrapped in {@link QueryExecutionError} on failure, and runs on the
+   * reserved connection inside `transaction()`.
+   *
+   * @param sql The statement text. Placeholders only (`$1` / `?` per dialect) —
+   *   never interpolate a value into this string.
+   * @param params The bound parameters, in placeholder order.
+   * @param options Pass `as` to coerce the returned rows with a model's column
+   *   types (and its column-name mapping).
+   * @returns The result view over the returned rows.
+   * @throws Error When `params` is not an array — the guard against calling this
+   *   with an interpolated string and no parameters by mistake.
+   *
+   * @example
+   * ```ts
+   * const claimed = await session.raw<OutboundRow>(
+   *   `UPDATE outbound_messages SET status = 'sending'
+   *      WHERE id = ANY($1) RETURNING *`,
+   *   [ids],
+   *   { as: Outbound },
+   * ).all();
+   * ```
+   */
+  raw(sql2, params = [], options) {
+    assertRawParams(params);
+    const model = options?.as;
+    const inner = this.exec(sql2, params).then((result) => {
+      const rows = model ? result.rows.map((row) => coerceRow(model, row)) : result.rows;
+      return new SyncResult(rows, result.changes);
+    });
+    return new AsyncResult(inner);
+  }
   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);
@@ -1494,6 +2358,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;
@@ -1514,13 +2425,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) {
@@ -1532,7 +2443,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) {
@@ -1559,8 +2470,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();
@@ -1582,8 +2493,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();
@@ -1593,6 +2504,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 {
@@ -1754,24 +2675,58 @@ var DEFAULT_FLAGS = {
   hasDefault: false,
   unique: false
 };
+var EXPRESSION = /* @__PURE__ */ Symbol.for("tempest-db-js.expression");
+function expression(token, params = []) {
+  return { [EXPRESSION]: true, kind: "expression", expression: token, params };
+}
+function isSqlExpression(value) {
+  return typeof value === "object" && value !== null && value[EXPRESSION] === true;
+}
 var sql = {
   /** Current timestamp at insert (`CURRENT_TIMESTAMP` / `now()`). */
-  now: () => ({ kind: "expression", expression: "now" }),
+  now: () => expression("now"),
   /** Current date. */
-  currentDate: () => ({ kind: "expression", expression: "current_date" }),
+  currentDate: () => expression("current_date"),
   /** Current time. */
-  currentTime: () => ({ kind: "expression", expression: "current_time" }),
+  currentTime: () => expression("current_time"),
   /** A freshly generated UUID v4 (`gen_random_uuid()` / portable fallback). */
-  uuidv4: () => ({ kind: "expression", expression: "uuidv4" }),
-  /** Escape hatch: a verbatim SQL expression rendered as-is. */
-  raw: (expression) => ({
-    kind: "expression",
-    expression: { raw: expression }
-  })
+  uuidv4: () => expression("uuidv4"),
+  /**
+   * Escape hatch: a verbatim SQL expression rendered as-is, with no parameters.
+   *
+   * The fragment is interpolated into the statement untouched, so it must never
+   * carry user input — use {@link sql.expr} when a value has to be bound.
+   *
+   * @param fragment The SQL text (e.g. `"attempts + 1"`).
+   * @returns The expression, usable as a default and as a write value.
+   */
+  raw: (fragment) => expression({ raw: fragment }),
+  /**
+   * A parameterized SQL expression, written as a tagged template. Static text is
+   * SQL; every `${...}` interpolation becomes a bound parameter, so the fragment
+   * is injection-safe by construction.
+   *
+   * Cannot be used as a column default — a `DEFAULT` clause has nowhere to bind
+   * parameters; use {@link sql.raw} there.
+   *
+   * @param parts The static SQL segments supplied by the template tag.
+   * @param values The interpolated values, bound in order.
+   * @returns The expression, usable as a write value.
+   *
+   * @example
+   * ```ts
+   * update(Account).set({ balance: sql.expr`balance - ${amount}` }).where({ id });
+   * // UPDATE "accounts" SET "balance" = balance - $1 WHERE "id" = $2
+   * ```
+   */
+  expr: (parts, ...values) => expression({ parts: Array.from(parts) }, values)
 };
 function isDefaultValue(value) {
   return typeof value === "object" && value !== null && "kind" in value && (value.kind === "literal" || value.kind === "expression");
 }
+function bindsParameters(value) {
+  return value.kind === "expression" && typeof value.expression === "object" && "parts" in value.expression;
+}
 function parseReference(ref, options) {
   const dot = ref.lastIndexOf(".");
   if (dot <= 0 || dot === ref.length - 1) {
@@ -1785,48 +2740,71 @@ function parseReference(ref, options) {
   };
 }
 var Column = class _Column {
-  constructor(type, flags, defaultValue = null, onUpdateValue = null, reference = null) {
+  constructor(type, flags, defaultValue = null, onUpdateValue = null, reference = null, dbName = null) {
     this.type = type;
     this.flags = flags;
     this.defaultValue = defaultValue;
     this.onUpdateValue = onUpdateValue;
     this.reference = reference;
+    this.dbName = dbName;
   }
   type;
   flags;
   defaultValue;
   onUpdateValue;
   reference;
-  primaryKey() {
+  dbName;
+  /** Clone this column with one facet replaced, carrying every other over. */
+  derive(patch) {
     return new _Column(
       this.type,
-      { ...this.flags, primaryKey: true, hasDefault: true },
-      this.defaultValue,
-      this.onUpdateValue,
-      this.reference
+      patch.flags ?? this.flags,
+      patch.defaultValue !== void 0 ? patch.defaultValue : this.defaultValue,
+      patch.onUpdateValue !== void 0 ? patch.onUpdateValue : this.onUpdateValue,
+      patch.reference !== void 0 ? patch.reference : this.reference,
+      patch.dbName !== void 0 ? patch.dbName : this.dbName
     );
   }
+  primaryKey() {
+    return this.derive({ flags: { ...this.flags, primaryKey: true, hasDefault: true } });
+  }
   notNull() {
-    return new _Column(
-      this.type,
-      { ...this.flags, notNull: true },
-      this.defaultValue,
-      this.onUpdateValue,
-      this.reference
-    );
+    return this.derive({ flags: { ...this.flags, notNull: true } });
   }
   /**
    * Add a `UNIQUE` constraint to the column (mirrors SQLAlchemy's
    * `mapped_column(unique=True)`). DDL-only — does not change the inferred type.
    */
   unique() {
-    return new _Column(
-      this.type,
-      { ...this.flags, unique: true },
-      this.defaultValue,
-      this.onUpdateValue,
-      this.reference
-    );
+    return this.derive({ flags: { ...this.flags, unique: true } });
+  }
+  /**
+   * Map this property to a differently-named database column, à la SQLAlchemy's
+   * `mapped_column("consumer_name")` (Django's `db_column`, Prisma's `@map`).
+   *
+   * The override applies everywhere the name reaches SQL — select, insert,
+   * update, delete, where, order by, group by, returning, conflict targets, the
+   * migration IR and the drift check — while the TypeScript row keeps the
+   * property name. Use it to keep a `snake_case` schema behind a `camelCase`
+   * model; {@link Model.naming} does the same for a whole table at once.
+   *
+   * @param dbName The real column name in the database.
+   * @returns A new column bound to that name.
+   * @throws Error When `dbName` is empty.
+   *
+   * @example
+   * ```ts
+   * class ApiKey extends Model {
+   *   static tablename = "api_keys";
+   *   consumerName = column.text().name("consumer_name").notNull();
+   * }
+   * ```
+   */
+  name(dbName) {
+    if (dbName.length === 0) {
+      throw new Error("column.name() requires a non-empty database column name.");
+    }
+    return this.derive({ dbName });
   }
   /**
    * Declare a foreign-key reference to another table's column, à la SQLAlchemy's
@@ -1839,35 +2817,45 @@ var Column = class _Column {
    * @throws Error When `ref` is not a valid `"table.column"` string.
    */
   references(ref, options) {
-    return new _Column(
-      this.type,
-      this.flags,
-      this.defaultValue,
-      this.onUpdateValue,
-      parseReference(ref, options)
-    );
+    return this.derive({ reference: parseReference(ref, options) });
   }
   /**
    * Set the insert-time default: a constant value of type `T`, or a portable
    * server-side expression from {@link sql} (e.g. `sql.now()`, `sql.uuidv4()`).
+   *
+   * @param value The literal default, or a {@link sql} expression.
+   * @returns A new column carrying the default.
+   * @throws Error When given a `sql.expr` fragment — a `DEFAULT` clause has
+   *   nowhere to bind parameters; use `sql.raw()` for a verbatim expression.
    */
   default(value) {
     const resolved = isDefaultValue(value) ? value : { kind: "literal", value };
-    return new _Column(
-      this.type,
-      { ...this.flags, hasDefault: true },
-      resolved,
-      this.onUpdateValue,
-      this.reference
-    );
+    if (bindsParameters(resolved)) {
+      throw new Error(
+        "sql.expr`...` binds parameters and cannot be a column default \u2014 use sql.raw() for a verbatim DEFAULT expression."
+      );
+    }
+    return this.derive({
+      flags: { ...this.flags, hasDefault: true },
+      defaultValue: resolved
+    });
   }
   /**
    * Re-apply a value whenever the row is updated (e.g. an `updated_at` column
    * with `sql.now()`). Mirrors SQLAlchemy's `onupdate`.
+   *
+   * @param value The literal value, or a {@link sql} expression.
+   * @returns A new column carrying the on-update value.
+   * @throws Error When given a `sql.expr` fragment (see {@link Column.default}).
    */
   onUpdate(value) {
     const resolved = isDefaultValue(value) ? value : { kind: "literal", value };
-    return new _Column(this.type, this.flags, this.defaultValue, resolved, this.reference);
+    if (bindsParameters(resolved)) {
+      throw new Error(
+        "sql.expr`...` binds parameters and cannot be an onUpdate default \u2014 use sql.raw() for a verbatim expression."
+      );
+    }
+    return this.derive({ onUpdateValue: resolved });
   }
 };
 function makeColumn(kind, meta = {}) {
@@ -1919,7 +2907,27 @@ var column = {
   /** `UUID` → `string`. */
   uuid: () => makeColumn("uuid"),
   /** `ENUM(...values)` → a string-literal union of the given values. */
-  enum: (...values) => makeColumn("enum", { values })
+  enum: (...values) => makeColumn("enum", { values }),
+  /**
+   * A PostgreSQL array column (`text[]`, `integer[]`) → `T[]`.
+   *
+   * PostgreSQL only: SQLite and MySQL have no native array type, and rendering
+   * one as JSON there would give the same model different semantics per dialect
+   * (`@>` and `&&` work on one and not the other), so the DDL renderer throws
+   * for those dialects instead of falling back silently.
+   *
+   * @param element The element column (its type, not its flags, is what is used).
+   * @returns A column whose inferred type is an array of the element's type.
+   *
+   * @example
+   * ```ts
+   * class ApiKey extends Model {
+   *   static tablename = "api_keys";
+   *   scopes = column.array(column.text()).notNull().default(["send"]);
+   * }
+   * ```
+   */
+  array: (element) => makeColumn("array", { element: element.type })
 };
 function unique(...columns) {
   if (columns.length === 0) {
@@ -1943,6 +2951,9 @@ function foreignKey(columns, refTable, refColumns, options) {
     onUpdate: options?.onUpdate
   };
 }
+function toSnakeCase(name) {
+  return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
 var Model = class {
   static tablename;
   /**
@@ -1951,6 +2962,12 @@ var Model = class {
    * `__table_args__`.
    */
   static tableArgs;
+  /**
+   * How to derive column names from property names (default `"preserve"`). Set
+   * `"snake_case"` to keep a `snake_case` schema behind a `camelCase` model
+   * without annotating every column; {@link Column.name} overrides it per column.
+   */
+  static naming;
 };
 var columnsCache = /* @__PURE__ */ new WeakMap();
 function columnsOf(model) {
@@ -1966,6 +2983,47 @@ function columnsOf(model) {
   columnsCache.set(model, out);
   return out;
 }
+var nameMapCache = /* @__PURE__ */ new WeakMap();
+var propMapCache = /* @__PURE__ */ new WeakMap();
+function columnNamesOf(model) {
+  const cached = nameMapCache.get(model);
+  if (cached !== void 0) return cached;
+  const strategy = model.naming ?? "preserve";
+  const map = {};
+  const seen = /* @__PURE__ */ new Map();
+  let renamed = false;
+  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(
+        `${model.tablename}: properties "${collision}" and "${prop}" both map to column "${dbName}".`
+      );
+    }
+    seen.set(dbName, prop);
+    map[prop] = dbName;
+    if (dbName !== prop) renamed = true;
+  }
+  const result = renamed ? map : null;
+  nameMapCache.set(model, result);
+  return result;
+}
+function columnPropsOf(model) {
+  const cached = propMapCache.get(model);
+  if (cached !== void 0) return cached;
+  const forward = columnNamesOf(model);
+  let result = null;
+  if (forward) {
+    const inverse = {};
+    for (const [prop, dbName] of Object.entries(forward)) inverse[dbName] = prop;
+    result = inverse;
+  }
+  propMapCache.set(model, result);
+  return result;
+}
+function dbColumn(names, prop) {
+  return names?.[prop] ?? prop;
+}
 
 exports.ActiveRecord = ActiveRecord;
 exports.Agg = Agg;
@@ -1976,6 +3034,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;
@@ -1984,6 +3043,7 @@ exports.MysqlDialect = MysqlDialect;
 exports.NoResultError = NoResultError;
 exports.NodeSqliteDriver = NodeSqliteDriver;
 exports.OPERATORS = OPERATORS;
+exports.Params = Params;
 exports.PostgresDialect = PostgresDialect;
 exports.QueryExecutionError = QueryExecutionError;
 exports.RecordNotFound = RecordNotFound;
@@ -1998,19 +3058,27 @@ exports.activeRecord = activeRecord;
 exports.and = and;
 exports.avg = avg;
 exports.belongsTo = belongsTo;
+exports.col = col;
 exports.column = column;
+exports.columnNamesOf = columnNamesOf;
+exports.columnPropsOf = columnPropsOf;
 exports.columnsOf = columnsOf;
 exports.count = count;
 exports.createEngine = createEngine;
 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;
@@ -2023,10 +3091,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