tempest-db-js 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -40,10 +40,14 @@ var OPERATORS = [
   "lte",
   "like",
   "ilike",
+  "ieq",
   "in",
   "notIn",
   "between",
-  "isNull"
+  "isNull",
+  "contains",
+  "containedBy",
+  "overlaps"
 ];
 var Agg = class {
   constructor(fn, column2) {
@@ -127,7 +131,56 @@ var SelectBuilder = class _SelectBuilder {
   offset(n) {
     return this.with({ offset: n });
   }
+  /**
+   * 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 +193,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, 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 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, col] of Object.entries(columnsOf(model))) {
+    const decoder = decoderFor(col.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 col = columns[key];
+    if (!col) {
+      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;
+    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`
+    );
+  }
+  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 +420,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 +492,8 @@ function insert(model) {
       kind: "insert",
       table: model.tablename,
       values: [],
-      returning: null
+      returning: null,
+      names: columnNamesOf(model) ?? void 0
     },
     model
   );
@@ -206,8 +508,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 +554,8 @@ function update(model) {
       set: {},
       where: void 0,
       guarded: false,
-      returning: null
+      returning: null,
+      names: columnNamesOf(model) ?? void 0
     },
     model
   );
@@ -270,7 +592,8 @@ function del(model) {
       table: model.tablename,
       where: void 0,
       guarded: false,
-      returning: null
+      returning: null,
+      names: columnNamesOf(model) ?? void 0
     },
     model
   );
@@ -323,215 +646,70 @@ function parseSqlite(raw, driver, rest) {
     driver,
     host: null,
     port: null,
-    user: null,
-    password: null,
-    database: decode(database),
-    options: {},
-    raw
-  };
-}
-function parseNetworkUrl(raw, driver, rest, dialect) {
-  let parsed;
-  try {
-    parsed = new URL(`${dialect}:${rest}`);
-  } catch {
-    throw new InvalidDatabaseUrl(raw, "could not parse host/credentials");
-  }
-  const database = decode(parsed.pathname.replace(/^\//, "")) || null;
-  const options = {};
-  for (const [key, value] of parsed.searchParams) options[key] = value;
-  return {
-    dialect,
-    driver,
-    host: parsed.hostname || null,
-    port: parsed.port ? Number(parsed.port) : null,
-    user: parsed.username ? decode(parsed.username) : null,
-    password: parsed.password ? decode(parsed.password) : null,
-    database,
-    options,
-    raw
-  };
-}
-function parseDatabaseUrl(url) {
-  const schemeEnd = url.indexOf(":");
-  if (schemeEnd === -1) {
-    throw new InvalidDatabaseUrl(
-      url,
-      "missing scheme (expected e.g. sqlite:// or postgresql://)"
-    );
-  }
-  const { base, driver } = splitScheme(url.slice(0, schemeEnd));
-  const dialect = DIALECT_ALIASES[base];
-  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));
+    user: null,
+    password: null,
+    database: decode(database),
+    options: {},
+    raw
+  };
 }
-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;
+function parseNetworkUrl(raw, driver, rest, dialect) {
+  let parsed;
+  try {
+    parsed = new URL(`${dialect}:${rest}`);
+  } catch {
+    throw new InvalidDatabaseUrl(raw, "could not parse host/credentials");
   }
+  const database = decode(parsed.pathname.replace(/^\//, "")) || null;
+  const options = {};
+  for (const [key, value] of parsed.searchParams) options[key] = value;
+  return {
+    dialect,
+    driver,
+    host: parsed.hostname || null,
+    port: parsed.port ? Number(parsed.port) : null,
+    user: parsed.username ? decode(parsed.username) : null,
+    password: parsed.password ? decode(parsed.password) : null,
+    database,
+    options,
+    raw
+  };
 }
-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);
+function parseDatabaseUrl(url) {
+  const schemeEnd = url.indexOf(":");
+  if (schemeEnd === -1) {
+    throw new InvalidDatabaseUrl(
+      url,
+      "missing scheme (expected e.g. sqlite:// or postgresql://)"
+    );
   }
-  decoderCache.set(model, map);
-  return map;
+  const { base, driver } = splitScheme(url.slice(0, schemeEnd));
+  const dialect = DIALECT_ALIASES[base];
+  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 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 +732,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 +755,21 @@ var BaseDialect = class _BaseDialect {
   static insertTemplates = /* @__PURE__ */ new Map();
   /** Quoted-identifier cache (see {@link quoteId}). Shared across dialects. */
   static quotedIds = /* @__PURE__ */ new Map();
+  /**
+   * 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 +808,175 @@ 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 -------------------------------------------------------
   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(", ")}`;
     }
     if (node.orderBy.length > 0) {
       const terms = node.orderBy.map(
-        (t) => `${this.quoteId(t.column)} ${t.direction === "desc" ? "DESC" : "ASC"}`
+        (t) => `${this.columnId(t.column, names)} ${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);
+    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
+      );
+    }
+    sql2 += this.compileReturning(node.returning, names);
+    return sql2;
   }
   /**
    * The INSERT SQL template for a given structure, cached across calls.
@@ -655,13 +986,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 +1001,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(
+      ([col, value]) => `${this.columnId(col, 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 +1093,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
@@ -787,6 +1153,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":
@@ -817,6 +1191,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 +1210,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,12 +1232,17 @@ var MysqlDialect = class extends BaseDialect {
     mysqlQuotedIds.set(name, quoted);
     return quoted;
   }
-  renderConflict(onConflict, conflictCols, nextPlaceholder) {
+  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");
+      const col = this.columnId(onConflict.target[0] ?? "id", names);
       return ` ON DUPLICATE KEY UPDATE ${col} = ${col}`;
     }
-    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}`;
   }
   compileReturning(returning) {
@@ -873,6 +1267,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 +1284,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 +1346,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 }
   );
@@ -1259,11 +1660,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 +1787,13 @@ var AsyncResult = class {
   }
 };
 var savepointCounter = 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 +1812,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;
@@ -1485,6 +1932,46 @@ 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;
     const { sql: sql2, params } = this.dialect.compile(node);
@@ -1751,73 +2238,190 @@ function createPostgresDriver(url, pool) {
 var DEFAULT_FLAGS = {
   primaryKey: false,
   notNull: false,
-  hasDefault: false
+  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) {
+    throw new Error(`Invalid foreign key reference "${ref}"; expected "table.column".`);
+  }
+  return {
+    table: ref.slice(0, dot),
+    column: ref.slice(dot + 1),
+    onDelete: options?.onDelete,
+    onUpdate: options?.onUpdate
+  };
+}
 var Column = class _Column {
-  constructor(type, flags, defaultValue = null, onUpdateValue = 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;
-  primaryKey() {
+  reference;
+  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
+      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
-    );
+    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 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
+   * `mapped_column(ForeignKey("table.column", ondelete=...))`. DDL-only — does
+   * not change the inferred type.
+   *
+   * @param ref The target as `"table.column"` (e.g. `"users.id"`).
+   * @param options Optional `onDelete` / `onUpdate` referential actions.
+   * @returns A new column carrying the reference.
+   * @throws Error When `ref` is not a valid `"table.column"` string.
+   */
+  references(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
-    );
+    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);
+    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 = {}) {
@@ -1869,10 +2473,67 @@ 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) {
+    throw new Error("unique() requires at least one column.");
+  }
+  return { kind: "unique", columns };
+}
+function foreignKey(columns, refTable, refColumns, options) {
+  if (columns.length === 0 || columns.length !== refColumns.length) {
+    throw new Error(
+      "foreignKey() requires matching, non-empty local and referenced column lists."
+    );
+  }
+  return {
+    kind: "foreignKey",
+    name: options?.name,
+    columns,
+    refTable,
+    refColumns,
+    onDelete: options?.onDelete,
+    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;
+  /**
+   * Optional table-level constraints (composite unique / foreign keys), returned
+   * by a thunk so forward references resolve lazily. Mirrors SQLAlchemy's
+   * `__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) {
@@ -1888,6 +2549,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, col] of Object.entries(columnsOf(model))) {
+    const dbName = col.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;
@@ -1906,6 +2608,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;
@@ -1921,17 +2624,22 @@ exports.and = and;
 exports.avg = avg;
 exports.belongsTo = belongsTo;
 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.foreignKey = foreignKey;
 exports.fromDict = fromDict;
 exports.getDialect = getDialect;
 exports.hasMany = hasMany;
 exports.insert = insert;
 exports.isCondition = isCondition;
+exports.isSqlExpression = isSqlExpression;
 exports.join = join;
 exports.loadRelations = loadRelations;
 exports.max = max;
@@ -1947,6 +2655,8 @@ exports.sum = sum;
 exports.toCondNode = toCondNode;
 exports.toDict = toDict;
 exports.toJSON = toJSON;
+exports.toSnakeCase = toSnakeCase;
+exports.unique = unique;
 exports.update = update;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map