tempest-db-js 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -26,6 +26,28 @@ interface AggregateTerm {
     /** The result alias. */
     readonly alias: string;
 }
+/**
+ * A row-level locking clause (`SELECT ... FOR UPDATE`).
+ *
+ * `wait` decides what happens when another transaction already holds the lock:
+ * `"block"` waits, `"skipLocked"` skips those rows (the job-queue claim), and
+ * `"noWait"` fails immediately.
+ */
+interface LockClause {
+    readonly strength: "update" | "share";
+    readonly wait: "block" | "skipLocked" | "noWait";
+    /** Tables to lock (`FOR UPDATE OF t`); empty locks every table in the query. */
+    readonly of: readonly string[];
+}
+/** Options accepted by {@link SelectBuilder.forUpdate} / {@link SelectBuilder.forShare}. */
+interface LockOptions {
+    /** Skip rows another transaction has locked instead of waiting for them. */
+    readonly skipLocked?: boolean;
+    /** Fail immediately instead of waiting for a locked row. */
+    readonly noWait?: boolean;
+    /** Restrict the lock to these tables (`FOR UPDATE OF ...`). */
+    readonly of?: readonly string[];
+}
 /** Serializable AST for a SELECT. Dialects (Phase 4) compile this to SQL. */
 interface SelectNode {
     readonly kind: "select";
@@ -39,20 +61,44 @@ interface SelectNode {
     /** `GROUP BY` columns. */
     readonly groupBy: readonly string[];
     readonly where: CondNode | undefined;
+    /** `HAVING` condition, keyed by aggregate alias or grouped column. */
+    readonly having?: CondNode | undefined;
     readonly orderBy: readonly OrderTerm[];
     readonly limit: number | undefined;
     readonly offset: number | undefined;
+    /** Row-level locking clause, or `undefined` for none. */
+    readonly lock?: LockClause | undefined;
+    /** Property → column map, or `undefined` when every name is the identity. */
+    readonly names?: NameMap | undefined;
 }
+/**
+ * A SELECT projecting exactly one column of type `T`, usable as the operand of
+ * `in` / `notIn`.
+ *
+ * Build it with {@link SelectBuilder.asSubquery}, which both narrows the
+ * projection to one column and gives the operand its element type.
+ */
+interface Subquery<T> {
+    /** Phantom: the element type the subquery yields, read only by the type system. */
+    readonly __element?: T;
+    /** The AST the outer statement embeds. */
+    readonly node: SelectNode;
+}
+/** Runtime guard: is this `in`/`notIn` operand a subquery rather than a list? */
+declare function isSubquery(value: unknown): value is Subquery<unknown>;
 /** Operators valid on every column type. */
 interface BaseOperators<T> {
     /** Equal to. */
     eq?: T;
     /** Not equal to. */
     ne?: T;
-    /** One of the given values (`IN`). */
-    in?: readonly T[];
-    /** None of the given values (`NOT IN`). */
-    notIn?: readonly T[];
+    /**
+     * One of the given values (`IN`) — a list, or a single-column
+     * {@link Subquery} built with `.asSubquery(column)`.
+     */
+    in?: readonly T[] | Subquery<T>;
+    /** None of the given values (`NOT IN`), as a list or a {@link Subquery}. */
+    notIn?: readonly T[] | Subquery<T>;
     /** `IS NULL` (true) / `IS NOT NULL` (false). */
     isNull?: boolean;
 }
@@ -71,19 +117,41 @@ interface OrderedOperators<T> extends BaseOperators<T> {
 }
 /** Extra operators for string-like types. */
 interface StringOperators<T> extends BaseOperators<T> {
-    /** `LIKE` pattern (case-sensitive). */
+    /** `LIKE` pattern (case-sensitive). `%` and `_` are wildcards. */
     like?: string;
-    /** `ILIKE` pattern (case-insensitive). */
+    /**
+     * `ILIKE` **pattern** (case-insensitive). This is pattern matching, not
+     * equality: `%` and `_` in the operand are wildcards, so `{ ilike: "%" }`
+     * matches every row. Never feed it unescaped user input — for a
+     * case-insensitive *equality* test use {@link StringOperators.ieq}, and to
+     * match a literal that may contain wildcards, wrap it in `escapeLike`.
+     */
     ilike?: string;
+    /**
+     * Case-insensitive equality — compiles to `lower(col) = lower($1)`, with no
+     * wildcards. The safe operator for a case-insensitive lookup (login, email),
+     * and the one that matches a `lower(col)` functional index.
+     */
+    ieq?: T;
+}
+/** Extra operators for array columns (PostgreSQL). */
+interface ArrayOperators<T> extends BaseOperators<T> {
+    /** `@>` — the column contains every element of the operand. */
+    contains?: T;
+    /** `<@` — every element of the column is in the operand. */
+    containedBy?: T;
+    /** `&&` — the column and the operand share at least one element. */
+    overlaps?: T;
 }
 /**
  * The operator object allowed for a column of (non-null) type `T`:
- *   - `string` → equality, `in`, `like`/`ilike`
+ *   - `T[]` → equality, `in`, `contains`/`containedBy`/`overlaps` (PostgreSQL)
+ *   - `string` → equality, `in`, `like`/`ilike`/`ieq`
  *   - `number` / `bigint` / `Date` → equality, `in`, ordered comparisons, `between`
  *   - `boolean` → equality, `isNull`
  *   - anything else (json/blob) → equality and `in` only
  */
-type OperatorsFor<T> = [T] extends [string] ? StringOperators<T> : [T] extends [number] ? OrderedOperators<T> : [T] extends [bigint] ? OrderedOperators<T> : [T] extends [Date] ? OrderedOperators<T> : [T] extends [boolean] ? BaseOperators<T> : BaseOperators<T>;
+type OperatorsFor<T> = [T] extends [readonly unknown[]] ? ArrayOperators<T> : [T] extends [string] ? StringOperators<T> : [T] extends [number] ? OrderedOperators<T> : [T] extends [bigint] ? OrderedOperators<T> : [T] extends [Date] ? OrderedOperators<T> : [T] extends [boolean] ? BaseOperators<T> : BaseOperators<T>;
 /**
  * `where` shape: each key must be a real column; each value accepts either a
  * bare value (shorthand for `eq`) or an operator object restricted to operators
@@ -94,7 +162,7 @@ type WhereInput<Row = Record<string, unknown>> = {
     [K in keyof Row]?: Row[K] | OperatorsFor<NonNullable<Row[K]>>;
 };
 /** The full set of operator keys, for the dialect compiler to recognize. */
-declare const OPERATORS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "like", "ilike", "in", "notIn", "between", "isNull"];
+declare const OPERATORS: readonly ["eq", "ne", "gt", "gte", "lt", "lte", "like", "ilike", "ieq", "in", "notIn", "between", "isNull", "contains", "containedBy", "overlaps"];
 /** One supported operator name. */
 type Operator = (typeof OPERATORS)[number];
 /** An aggregate expression carrying its result type `T` as a phantom. */
@@ -126,20 +194,43 @@ type SimplifyProj<T> = {
  * @typeParam Full - the complete row type (constrains where/orderBy keys).
  * @typeParam Proj - the projected result type returned on execution.
  */
-declare class SelectBuilder<Full, Proj = Full> {
+declare class SelectBuilder<Full, Proj = Full, Grouped extends boolean = false> {
     readonly node: SelectNode;
     /** The source model, used to coerce rows on execution. */
     readonly source: ModelClass;
     /** Phantom: the result element type, read only by the type system. */
     readonly __row: Proj;
+    /** Phantom: `true` once `aggregate()` has made `having()` meaningful. */
+    readonly __grouped: Grouped;
     constructor(node: SelectNode, 
     /** The source model, used to coerce rows on execution. */
     source: ModelClass);
     private with;
     /** Add a WHERE filter: the object form (keys typed) or an `and`/`or`/`not`. */
-    where(input: WhereInput<Full> | Condition): SelectBuilder<Full, Proj>;
+    where(input: WhereInput<Full> | Condition): SelectBuilder<Full, Proj, Grouped>;
+    /**
+     * 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(this: SelectBuilder<Full, Proj, true>, input: WhereInput<Proj> | Condition): SelectBuilder<Full, Proj, true>;
     /** Emit `SELECT DISTINCT` — drop duplicate rows. */
-    distinct(): SelectBuilder<Full, Proj>;
+    distinct(): SelectBuilder<Full, Proj, Grouped>;
     /**
      * Group by columns and compute aggregates. The result row is the grouped
      * columns (typed from the model) plus one field per aggregate alias.
@@ -158,13 +249,88 @@ declare class SelectBuilder<Full, Proj = Full> {
      */
     aggregate<K extends keyof Full & string, S extends Record<string, Agg<unknown>>>(groupBy: readonly K[], spec: S): SelectBuilder<Full, SimplifyProj<Pick<Full, K> & {
         [A in keyof S]: AggResult<S[A]>;
-    }>>;
-    /** Order by a column of `Full`. */
-    orderBy(column: keyof Full & string, direction?: SortDirection): SelectBuilder<Full, Proj>;
+    }>, true>;
+    /**
+     * 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(column: (keyof Full & string) | (keyof Proj & string), direction?: SortDirection): SelectBuilder<Full, Proj, Grouped>;
     /** Limit the number of rows. */
-    limit(n: number): SelectBuilder<Full, Proj>;
+    limit(n: number): SelectBuilder<Full, Proj, Grouped>;
     /** Skip the first `n` rows. */
-    offset(n: number): SelectBuilder<Full, Proj>;
+    offset(n: number): SelectBuilder<Full, Proj, Grouped>;
+    /**
+     * 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<K extends keyof Full & string>(column: K): Subquery<Full[K]>;
+    /**
+     * 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?: LockOptions): SelectBuilder<Full, Proj, Grouped>;
+    /**
+     * 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?: LockOptions): SelectBuilder<Full, Proj, Grouped>;
 }
 /** Build a SELECT over every column of the model. */
 declare function select<C extends ModelClass>(model: C): SelectBuilder<InferModel<C>, InferModel<C>>;
@@ -185,6 +351,25 @@ interface CondFields {
     readonly kind: "fields";
     readonly fields: Record<string, unknown>;
 }
+/**
+ * One side of a comparison: a column reference, a bound value, or a SQL function
+ * applied to other expressions.
+ *
+ * A column reference carries the **property** name, not the database column —
+ * the dialect resolves it through the node's name map, so `col()` cannot become a
+ * back door around an explicit `.name()` mapping.
+ */
+type ExprNode = {
+    readonly kind: "column";
+    readonly name: string;
+} | {
+    readonly kind: "value";
+    readonly value: unknown;
+} | {
+    readonly kind: "fn";
+    readonly name: string;
+    readonly args: readonly ExprNode[];
+};
 /** Logical condition nodes. */
 type CondNode = CondFields | {
     readonly kind: "and";
@@ -195,6 +380,11 @@ type CondNode = CondFields | {
 } | {
     readonly kind: "not";
     readonly part: CondNode;
+} | {
+    readonly kind: "compare";
+    readonly left: ExprNode;
+    readonly op: Operator;
+    readonly right: ExprNode;
 };
 declare const CONDITION: unique symbol;
 /** A composed condition produced by `and`/`or`/`not`. */
@@ -214,6 +404,145 @@ declare function toCondNode(input: Condition | Record<string, unknown>): CondNod
  *   for full key + operator checking inside combinators.
  */
 type WhereArg<Row = Record<string, unknown>> = WhereInput<Row> | Condition;
+/** Runtime guard: is this operand a built {@link Expression}? */
+declare function isExpression(value: unknown): value is Expression;
+/**
+ * One side of a comparison, built with {@link col}, {@link val} or {@link fn}.
+ *
+ * The comparison methods mirror the `where` operators, but both sides are
+ * expressions — which is what makes `col("total").gt(col("paid"))` and a
+ * functional-index lookup like `fn.lower("email").eq(fn.lower(val(probe)))`
+ * expressible at all. An operand that is not an `Expression` is bound as a
+ * parameter, so `.eq(probe)` stays safe by default.
+ */
+declare class Expression {
+    /** The expression AST the dialect renders. */
+    readonly node: ExprNode;
+    constructor(
+    /** The expression AST the dialect renders. */
+    node: ExprNode);
+    /** Compare this expression against another expression or a bound value. */
+    private compare;
+    /** `=` (or `IS NULL` for a null value). */
+    eq(operand: unknown): Condition;
+    /** `<>` (or `IS NOT NULL` for a null value). */
+    ne(operand: unknown): Condition;
+    /** `>`. */
+    gt(operand: unknown): Condition;
+    /** `>=`. */
+    gte(operand: unknown): Condition;
+    /** `<`. */
+    lt(operand: unknown): Condition;
+    /** `<=`. */
+    lte(operand: unknown): Condition;
+    /** `LIKE` — `%` and `_` in the operand are wildcards. */
+    like(pattern: string | Expression): Condition;
+    /** `ILIKE` — case-insensitive **pattern** matching, wildcards included. */
+    ilike(pattern: string | Expression): Condition;
+    /** Case-insensitive equality (`lower(a) = lower(b)`), with no wildcards. */
+    ieq(operand: unknown): Condition;
+    /**
+     * `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: readonly unknown[]): Condition;
+    /**
+     * `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: readonly unknown[]): Condition;
+    /**
+     * `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: unknown, hi: unknown): Condition;
+    /** `IS NULL` (true) / `IS NOT NULL` (false). */
+    isNull(value?: boolean): Condition;
+}
+/**
+ * A column reference, by **property** name.
+ *
+ * Pass the row type for key-safety: `col<UserRow>("total")` rejects a name that
+ * is not a column. The name is resolved through the model's column-name map at
+ * compile time, exactly like the object form of `where`.
+ *
+ * @param name The model property name.
+ * @returns An expression referencing that column.
+ *
+ * @example
+ * ```ts
+ * select(Order).where(col<OrderRow>("total").gt(col<OrderRow>("paid")));
+ * // SELECT * FROM "orders" WHERE "total" > "paid"
+ * ```
+ */
+declare function col<Row = Record<string, unknown>>(name: keyof Row & string): Expression;
+/**
+ * A bound value, for the places that take an expression and would otherwise read
+ * a bare string as a column name (the arguments of {@link fn}).
+ *
+ * @param value The value to bind as a parameter.
+ * @returns An expression that renders as a placeholder.
+ */
+declare function val(value: unknown): Expression;
+/**
+ * Build a call to a SQL function.
+ *
+ * A bare string argument is a **column name** — that is the useful default here
+ * (`fn.lower("username")`), and it is why a literal has to be wrapped in
+ * {@link val}. The function name is interpolated into the statement, so it is
+ * validated as a plain identifier and must never come from user input; the
+ * arguments are always rendered through the expression compiler.
+ *
+ * @param name The SQL function name.
+ * @param args Column names or expressions.
+ * @returns An expression for the call.
+ * @throws Error When `name` is not a plain SQL identifier.
+ */
+declare function call(name: string, ...args: (Expression | string)[]): Expression;
+/**
+ * SQL functions usable on either side of a comparison.
+ *
+ * The named entries are the ones every supported dialect implements. Anything
+ * else — `date_trunc`, `strftime`, a custom function — goes through
+ * {@link fn.call}, which does not pretend to be portable.
+ *
+ * @example
+ * ```ts
+ * select(AdminUser).where(fn.lower("username").eq(fn.lower(val(probe))));
+ * // WHERE lower("username") = lower($1)
+ * ```
+ */
+declare const fn: {
+    /** `lower(x)`. */
+    readonly lower: (arg: Expression | string) => Expression;
+    /** `upper(x)`. */
+    readonly upper: (arg: Expression | string) => Expression;
+    /** `trim(x)`. */
+    readonly trim: (arg: Expression | string) => Expression;
+    /** `length(x)`. */
+    readonly length: (arg: Expression | string) => Expression;
+    /** `abs(x)`. */
+    readonly abs: (arg: Expression | string) => Expression;
+    /** `coalesce(a, b, ...)`. */
+    readonly coalesce: (...args: (Expression | string)[]) => Expression;
+    /**
+     * Any other SQL function, by name. Portability is the caller's problem —
+     * `date_trunc` is PostgreSQL, `strftime` is SQLite.
+     */
+    readonly call: typeof call;
+};
 /** Combine conditions with `AND`. */
 declare function and<Row = Record<string, unknown>>(...inputs: WhereArg<NoInfer<Row>>[]): Condition;
 /** Combine conditions with `OR`. */
@@ -235,6 +564,19 @@ declare function not<Row = Record<string, unknown>>(input: WhereArg<NoInfer<Row>
 
 /** Columns to return from a mutation, or "*" for the whole row. */
 type Returning = readonly string[] | "*" | null;
+/**
+ * A write shape over `Row`: every column accepts its own value **or** a
+ * {@link SqlExpression}, which the dialect renders inline instead of binding.
+ * Optionality is preserved from `Row`, so an insert shape keeps its defaults
+ * optional.
+ */
+type WriteValues<Row> = {
+    [K in keyof Row]: Row[K] | SqlExpression;
+};
+/** A partial write shape — the `SET` clause of an UPDATE or a `DO UPDATE`. */
+type WritePatch<Row> = {
+    [K in keyof Row]?: Row[K] | SqlExpression;
+};
 /**
  * Conflict-resolution clause for an INSERT (`ON CONFLICT`). `target` is the
  * conflicting column(s) (a unique/PK constraint); `update` is `"nothing"` for
@@ -243,6 +585,28 @@ type Returning = readonly string[] | "*" | null;
 interface OnConflict {
     readonly target: readonly string[];
     readonly update: Record<string, unknown> | "nothing";
+    /**
+     * The predicate of a **partial** unique index. PostgreSQL only matches a
+     * partial index as a conflict target when `ON CONFLICT` repeats its predicate,
+     * so without this an insert against `... WHERE key IS NOT NULL` is rejected
+     * with "there is no unique or exclusion constraint matching the ON CONFLICT
+     * specification".
+     */
+    readonly targetWhere?: CondNode | undefined;
+    /** Extra condition restricting which conflicting rows `DO UPDATE` rewrites. */
+    readonly updateWhere?: CondNode | undefined;
+}
+/** Options for the `ON CONFLICT` clause of {@link InsertBuilder.onConflictDoNothing}. */
+interface OnConflictOptions<Full> {
+    /** The predicate of the partial unique index used as the conflict target. */
+    readonly where?: WhereInput<Full> | Condition;
+}
+/** Options for {@link InsertBuilder.onConflictDoUpdate}. */
+interface OnConflictUpdateOptions<Full> {
+    /** The predicate of the partial unique index used as the conflict target. */
+    readonly indexWhere?: WhereInput<Full> | Condition;
+    /** Extra condition deciding which conflicting rows are actually rewritten. */
+    readonly updateWhere?: WhereInput<Full> | Condition;
 }
 /** Serializable AST for an INSERT. */
 interface InsertNode {
@@ -252,6 +616,8 @@ interface InsertNode {
     readonly returning: Returning;
     /** Conflict handling (`ON CONFLICT ...`), or `undefined` for none. */
     readonly onConflict?: OnConflict;
+    /** Property → column map, or `undefined` when every name is the identity. */
+    readonly names?: NameMap | undefined;
 }
 /**
  * INSERT builder.
@@ -269,21 +635,46 @@ declare class InsertBuilder<Full, Ins, Ret = number> {
     /** The source model, used to coerce returned rows on execution. */
     source: ModelClass);
     private with;
-    /** Provide one row or many rows to insert, typed by the insert shape. */
-    values(rows: Ins | readonly Ins[]): InsertBuilder<Full, Ins, Ret>;
+    /**
+     * 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: WriteValues<Ins> | readonly WriteValues<Ins>[]): InsertBuilder<Full, Ins, Ret>;
     /**
      * 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: readonly (keyof Full & string)[]): InsertBuilder<Full, Ins, Ret>;
+    onConflictDoNothing(target: readonly (keyof Full & string)[], options?: OnConflictOptions<Full>): InsertBuilder<Full, Ins, Ret>;
     /**
      * 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: readonly (keyof Full & string)[], set: Partial<Full>): InsertBuilder<Full, Ins, Ret>;
+    onConflictDoUpdate(target: readonly (keyof Full & string)[], set: WritePatch<Full>, options?: OnConflictUpdateOptions<Full>): InsertBuilder<Full, Ins, Ret>;
     /** Return the full inserted row(s). */
     returning(): InsertBuilder<Full, Ins, Full>;
     /** Return only the given columns of the inserted row(s). */
@@ -300,6 +691,8 @@ interface UpdateNode {
     /** True once a where-clause or explicit opt-in makes the write safe. */
     readonly guarded: boolean;
     readonly returning: Returning;
+    /** Property → column map, or `undefined` when every name is the identity. */
+    readonly names?: NameMap | undefined;
 }
 /**
  * UPDATE builder.
@@ -318,8 +711,26 @@ declare class UpdateBuilder<Full, Guarded extends boolean, Ret = number> {
     /** The source model, used to coerce returned rows on execution. */
     source: ModelClass);
     private with;
-    /** The columns to write. Partial — only the given columns change. */
-    set(values: Partial<Full>): UpdateBuilder<Full, Guarded, Ret>;
+    /**
+     * 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: WritePatch<Full>): UpdateBuilder<Full, Guarded, Ret>;
     /** Restrict the rows to update. Marks the builder safe to execute. */
     where(input: WhereInput<Full> | Condition): UpdateBuilder<Full, true, Ret>;
     /** Explicit opt-in to update EVERY row. Use deliberately. */
@@ -338,6 +749,8 @@ interface DeleteNode {
     readonly where: CondNode | undefined;
     readonly guarded: boolean;
     readonly returning: Returning;
+    /** Property → column map, or `undefined` when every name is the identity. */
+    readonly names?: NameMap | undefined;
 }
 /**
  * DELETE builder. Starts unguarded — same safety rule as UPDATE.
@@ -532,6 +945,8 @@ interface JoinNode {
     }[];
     readonly limit: number | undefined;
     readonly offset: number | undefined;
+    /** Per-alias property → column maps, for the sources that rename columns. */
+    readonly names?: Readonly<Record<string, NameMap>> | undefined;
 }
 /** A map of source alias → its (possibly nullable) row type. */
 type Sources = Record<string, object | null>;
@@ -605,6 +1020,16 @@ interface CompiledQuery {
 }
 /** Any compilable AST node. */
 type QueryNode = SelectNode | InsertNode | UpdateNode | DeleteNode | JoinNode;
+/**
+ * Collects bound parameters and renders placeholders in dialect style. Exposed
+ * because dialect subclasses receive it when overriding clause rendering.
+ */
+declare class Params {
+    private readonly placeholder;
+    readonly values: unknown[];
+    constructor(placeholder: (index: number) => string);
+    bind(value: unknown): string;
+}
 /**
  * Base SQL compiler shared by every dialect. Subclasses customize only what
  * actually differs between databases (placeholder syntax, `ILIKE` support).
@@ -623,6 +1048,25 @@ declare abstract class BaseDialect {
     protected abstract placeholder(index: number): string;
     /** Render a case-insensitive LIKE for the active dialect. */
     protected abstract ilike(column: string, param: string): string;
+    /**
+     * 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.
+     */
+    protected checkSubquery(_node: SelectNode): void;
+    /**
+     * 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.
+     */
+    protected arrayOperator(op: "contains" | "containedBy" | "overlaps"): string;
     /**
      * Quote an identifier (column/table) for the active dialect.
      *
@@ -634,10 +1078,83 @@ declare abstract class BaseDialect {
     protected quoteId(name: string): string;
     /** Compile any node to `{ sql, params }`. */
     compile(node: QueryNode): CompiledQuery;
-    /** Render a qualified `alias.column` ref as `"alias"."column"`. */
+    /**
+     * 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.
+     */
     private qualify;
+    /**
+     * 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.
+     */
+    protected columnId(prop: string, names: NameMap | undefined): string;
+    /**
+     * 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.
+     */
+    protected renderExpression(expr: SqlExpression, params: Params): string;
+    /** Render one write value: a SQL expression inline, anything else as a parameter. */
+    protected renderValue(value: unknown, params: Params): string;
+    /**
+     * 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.
+     */
+    protected renderLock(lock: LockClause): string;
+    /**
+     * 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.
+     */
     private compileSelect;
+    /**
+     * 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.
+     */
     private compileInsert;
+    /**
+     * 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.
+     */
+    private compileInsertDirect;
     /**
      * The INSERT SQL template for a given structure, cached across calls.
      *
@@ -649,24 +1166,74 @@ declare abstract class BaseDialect {
     private insertTemplate;
     /**
      * 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.
      */
-    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextPlaceholder: () => string): string;
+    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined, params: Params): string;
     private compileUpdate;
     private compileDelete;
     private compileJoin;
-    protected compileReturning(returning: readonly string[] | "*" | null): string;
+    protected compileReturning(returning: readonly string[] | "*" | null, names?: NameMap | undefined): string;
     /**
      * Compile a condition tree (fields / and / or / not) to SQL. `idFor` renders a
      * key to a quoted identifier — `quoteId` for single-table, `qualify` for joins —
      * so select/update/delete/join all share this one compiler.
      */
     private compileCondition;
+    /**
+     * 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.
+     */
+    private renderExpr;
+    /**
+     * 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.
+     */
+    private compileExprOperator;
     private compileOperator;
+    /**
+     * 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.
+     */
     private compileIn;
 }
 /** SQLite dialect: `?` placeholders; `ILIKE` falls back to `LIKE` (ASCII-insensitive). */
@@ -674,12 +1241,19 @@ declare class SqliteDialect extends BaseDialect {
     readonly name: "sqlite";
     protected placeholder(): string;
     protected ilike(column: string, param: string): string;
+    /**
+     * 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.
+     */
+    protected renderLock(): string;
 }
-/** PostgreSQL dialect: `$1` placeholders; native `ILIKE`. */
+/** PostgreSQL dialect: `$1` placeholders; native `ILIKE`; native array operators. */
 declare class PostgresDialect extends BaseDialect {
     readonly name: "postgresql";
     protected placeholder(index: number): string;
     protected ilike(column: string, param: string): string;
+    protected arrayOperator(op: "contains" | "containedBy" | "overlaps"): string;
 }
 /**
  * MySQL dialect: `?` placeholders, backtick identifiers, `ON DUPLICATE KEY
@@ -691,7 +1265,23 @@ declare class MysqlDialect extends BaseDialect {
     protected placeholder(): string;
     protected ilike(column: string, param: string): string;
     protected quoteId(name: string): string;
-    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextPlaceholder: () => string): string;
+    /**
+     * 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.
+     */
+    protected checkSubquery(node: SelectNode): void;
+    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined): string;
+    /**
+     * 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.
+     */
     protected compileReturning(returning: readonly string[] | "*" | null): string;
 }
 /** Get a dialect instance by name. */
@@ -749,7 +1339,7 @@ declare class NodeSqliteDriver implements SyncDriver {
     iterate(sql: string, params: readonly unknown[]): IterableIterator<Record<string, unknown>>;
     close(): void;
 }
-type AnySelect = SelectBuilder<any, any>;
+type AnySelect = SelectBuilder<any, any, any>;
 type AnyInsert = InsertBuilder<any, any, any>;
 type GuardedUpdate = UpdateBuilder<any, true, any>;
 type GuardedDelete = DeleteBuilder<any, true, any>;
@@ -832,6 +1422,40 @@ declare class SyncSession {
     logger?: QueryLogger | undefined);
     /** Log, run, and error-wrap one raw statement. */
     private exec;
+    /**
+     * 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<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[], options?: {
+        readonly as?: ModelClass;
+    }): SyncResult<Row>;
     /** Compile, run, and coerce a builder into a result. */
     execute<B extends Executable>(builder: B): SyncResult<RowOf<B>>;
     /** Run `fn` inside a transaction: commit on success, rollback on throw. */
@@ -858,7 +1482,58 @@ declare class AsyncSession {
     logger?: QueryLogger | undefined);
     /** Log, run, and error-wrap one raw statement. */
     private exec;
+    /**
+     * 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<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[], options?: {
+        readonly as?: ModelClass;
+    }): AsyncResult<Row>;
     execute<B extends Executable>(builder: B): AsyncResult<RowOf<B>>;
+    /**
+     * 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.
+     */
+    private insertAndReadBack;
     /** Lazily iterate result rows. Uses driver streaming when available. */
     stream<B extends Executable>(builder: B): AsyncIterableIterator<RowOf<B>>;
     transaction<T>(fn: (tx: AsyncSession) => Promise<T>): Promise<T>;
@@ -911,6 +1586,18 @@ declare class AsyncEngine {
     /** `await using engine = createEngine(...)` closes the pool when the scope exits. */
     [Symbol.asyncDispose](): Promise<void>;
 }
+/**
+ * Adapt a sync **or** async driver to the async interface.
+ *
+ * `await` normalizes both: a sync driver returns a plain value, an async one a
+ * promise, and awaiting either yields the result. That is what lets the migration
+ * CLI take one code path instead of branching on a difference it cannot detect
+ * from the object's shape.
+ *
+ * @param driver Either driver flavor.
+ * @returns An async driver delegating to it.
+ */
+declare function toAsyncDriver(driver: SyncDriver | AsyncDriver): AsyncDriver;
 /**
  * Create a **synchronous** engine from a database URL. SQLite only — PostgreSQL
  * has no sane synchronous driver in Node, so a Postgres URL throws, pointing at
@@ -1168,7 +1855,7 @@ interface ColumnFlags {
  * generic types (e.g. `String` → varchar, `Text` → text). Dialect renderers
  * (Phase 4/6) map each kind + meta to concrete SQL per database.
  */
-type ColumnTypeKind = "smallint" | "integer" | "bigint" | "numeric" | "real" | "double" | "varchar" | "text" | "char" | "boolean" | "date" | "time" | "datetime" | "timestamp" | "blob" | "json" | "uuid" | "enum";
+type ColumnTypeKind = "smallint" | "integer" | "bigint" | "numeric" | "real" | "double" | "varchar" | "text" | "char" | "boolean" | "date" | "time" | "datetime" | "timestamp" | "blob" | "json" | "uuid" | "enum" | "array";
 /** Parameters that refine a column type and feed the migration IR / DDL. */
 interface ColumnTypeMeta {
     /** Max length for `varchar`/`char`. */
@@ -1183,6 +1870,8 @@ interface ColumnTypeMeta {
     readonly values?: readonly string[] | undefined;
     /** Render as `JSONB` (PostgreSQL) instead of `JSON`. */
     readonly jsonb?: boolean | undefined;
+    /** The element type of an `array` column (`text[]`, `integer[]`). */
+    readonly element?: ColumnType | undefined;
 }
 /** A structured, dialect-neutral column type descriptor. */
 interface ColumnType {
@@ -1193,10 +1882,14 @@ interface ColumnType {
  * A portable default expression. The token is dialect-neutral; the renderer
  * (Phase 4/6) maps it to the right SQL per database — e.g. `"now"` becomes
  * `CURRENT_TIMESTAMP` on SQLite and `now()` on PostgreSQL. Use `{ raw }` as an
- * escape hatch for a verbatim SQL fragment.
+ * escape hatch for a verbatim SQL fragment, or `{ parts }` for a parameterized
+ * fragment built by the `sql.expr` tagged template (one bound parameter per gap
+ * between consecutive parts).
  */
 type PortableExpression = "now" | "current_date" | "current_time" | "uuidv4" | {
     readonly raw: string;
+} | {
+    readonly parts: readonly string[];
 };
 /**
  * A column default. Either a constant literal value or a server-side expression
@@ -1210,18 +1903,79 @@ type DefaultValue = {
     readonly kind: "expression";
     readonly expression: PortableExpression;
 };
-/** Portable server-side default expressions, à la SQLAlchemy's `func`. */
+/**
+ * Brand marking a value as a SQL expression rather than a bound parameter.
+ *
+ * A plain object reaching `set()`/`values()` is a mistake (it would be bound as a
+ * parameter and silently written as JSON or null); an object carrying this symbol
+ * is deliberate, and the dialect renders it inline instead of binding it. Mirrors
+ * how `Condition` is branded, so the check is a symbol lookup, not duck typing.
+ */
+declare const EXPRESSION: unique symbol;
+/**
+ * A SQL expression, usable both as a column default (`.default(sql.now())`) and
+ * as a write value (`.set({ attempts: sql.raw("attempts + 1") })`). The dialect
+ * renders `expression` inline and binds `params` in the order of the fragment's
+ * gaps.
+ */
+interface SqlExpression {
+    readonly [EXPRESSION]: true;
+    readonly kind: "expression";
+    readonly expression: PortableExpression;
+    /** Parameters bound into the fragment's gaps, in order (empty for a token). */
+    readonly params: readonly unknown[];
+}
+/**
+ * Runtime guard: is this value a branded {@link SqlExpression}?
+ *
+ * @param value Any value handed to `set()`, `values()` or `.default()`.
+ * @returns True when the value carries the expression brand.
+ */
+declare function isSqlExpression(value: unknown): value is SqlExpression;
+/**
+ * Portable server-side expressions, à la SQLAlchemy's `func`.
+ *
+ * Every entry doubles as a column default and as a write value, so
+ * `.default(sql.now())` and `.set({ updatedAt: sql.now() })` both work.
+ */
 declare const sql: {
     /** Current timestamp at insert (`CURRENT_TIMESTAMP` / `now()`). */
-    readonly now: () => DefaultValue;
+    readonly now: () => SqlExpression;
     /** Current date. */
-    readonly currentDate: () => DefaultValue;
+    readonly currentDate: () => SqlExpression;
     /** Current time. */
-    readonly currentTime: () => DefaultValue;
+    readonly currentTime: () => SqlExpression;
     /** A freshly generated UUID v4 (`gen_random_uuid()` / portable fallback). */
-    readonly uuidv4: () => DefaultValue;
-    /** Escape hatch: a verbatim SQL expression rendered as-is. */
-    readonly raw: (expression: string) => DefaultValue;
+    readonly uuidv4: () => SqlExpression;
+    /**
+     * 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.
+     */
+    readonly raw: (fragment: string) => SqlExpression;
+    /**
+     * 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
+     * ```
+     */
+    readonly expr: (parts: TemplateStringsArray, ...values: unknown[]) => SqlExpression;
 };
 /**
  * A referential action for a foreign key's `ON DELETE` / `ON UPDATE` clause.
@@ -1258,6 +2012,8 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly onUpdateValue: DefaultValue | null;
     /** The foreign-key reference this column points to, or `null` for none. */
     readonly reference: ForeignKeyRef | null;
+    /** An explicit database column name overriding the property name, or `null`. */
+    readonly dbName: string | null;
     /** Phantom: never read at runtime, only inspected by the type system. */
     readonly [TYPE]: T;
     constructor(type: ColumnType, flags: F, 
@@ -1266,7 +2022,11 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     /** The value re-applied on update (e.g. `updated_at`), or `null`. */
     onUpdateValue?: DefaultValue | null, 
     /** The foreign-key reference this column points to, or `null` for none. */
-    reference?: ForeignKeyRef | null);
+    reference?: ForeignKeyRef | null, 
+    /** An explicit database column name overriding the property name, or `null`. */
+    dbName?: string | null);
+    /** Clone this column with one facet replaced, carrying every other over. */
+    private derive;
     primaryKey(): Column<T, F & {
         primaryKey: true;
         hasDefault: true;
@@ -1281,6 +2041,29 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     unique(): Column<T, F & {
         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: string): Column<T, F>;
     /**
      * Declare a foreign-key reference to another table's column, à la SQLAlchemy's
      * `mapped_column(ForeignKey("table.column", ondelete=...))`. DDL-only — does
@@ -1295,6 +2078,11 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     /**
      * 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: T | DefaultValue): Column<T, F & {
         hasDefault: true;
@@ -1302,6 +2090,10 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     /**
      * 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: T | DefaultValue): Column<T, F>;
 }
@@ -1370,6 +2162,26 @@ declare const column: {
     readonly uuid: () => Column<string, ColumnFlags>;
     /** `ENUM(...values)` → a string-literal union of the given values. */
     readonly enum: <const E extends string>(...values: E[]) => Column<E, ColumnFlags>;
+    /**
+     * 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"]);
+     * }
+     * ```
+     */
+    readonly array: <T>(element: Column<T, ColumnFlags>) => Column<T[], ColumnFlags>;
 };
 /**
  * A table-level constraint declared via a model's `static tableArgs`. Mirrors
@@ -1414,6 +2226,16 @@ declare function foreignKey(columns: string[], refTable: string, refColumns: str
     onDelete?: FkAction;
     onUpdate?: FkAction;
 }): TableConstraint;
+/**
+ * How property names map to database column names when a column declares no
+ * explicit {@link Column.name}.
+ *
+ *   - `"preserve"` (default) — the column name is the property name, verbatim.
+ *   - `"snake_case"` — `consumerName` becomes `consumer_name`.
+ */
+type NamingStrategy = "preserve" | "snake_case";
+/** Convert a `camelCase` / `PascalCase` identifier to `snake_case`. */
+declare function toSnakeCase(name: string): string;
 /** Base class every model extends, SQLAlchemy-declarative style. */
 declare abstract class Model {
     static tablename: string;
@@ -1423,6 +2245,12 @@ declare abstract class Model {
      * `__table_args__`.
      */
     static tableArgs?: () => readonly TableConstraint[];
+    /**
+     * 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?: NamingStrategy;
 }
 /**
  * Reflect a model class into its column map at runtime, keyed by column name.
@@ -1438,6 +2266,32 @@ declare abstract class Model {
  * @returns A record of column name → `Column` instance (do not mutate).
  */
 declare function columnsOf(model: ModelClass): Record<string, Column<unknown>>;
+/** A mapping between property names and database column names. */
+type NameMap = Readonly<Record<string, string>>;
+/**
+ * The property → database-column map for a model, or `null` when every column
+ * keeps its property name.
+ *
+ * `null` is the common case and the fast path: builders and the row coercer skip
+ * translation entirely, so a model that renames nothing costs nothing. The map
+ * is memoized per class, like {@link columnsOf}.
+ *
+ * @param model The model class.
+ * @returns The name map, or `null` when no column is renamed.
+ * @throws Error When two properties resolve to the same column name.
+ */
+declare function columnNamesOf(model: ModelClass): NameMap | null;
+/**
+ * The database-column → property map for a model, or `null` when every column
+ * keeps its property name. The inverse of {@link columnNamesOf}, used to map
+ * driver rows back into property space.
+ *
+ * @param model The model class.
+ * @returns The inverse name map, or `null` when no column is renamed.
+ */
+declare function columnPropsOf(model: ModelClass): NameMap | null;
+/** Resolve one property name to its database column name. */
+declare function dbColumn(names: NameMap | null | undefined, prop: string): string;
 /** Pull the static type out of a Column. */
 type ColType<C> = C extends Column<infer T, infer _F> ? T : never;
 /** Keys of the model instance whose values are Columns. */
@@ -1448,6 +2302,7 @@ type ColumnKeys<M> = {
 type ModelClass = (new () => Model) & {
     tablename: string;
     tableArgs?: () => readonly TableConstraint[];
+    naming?: NamingStrategy;
 };
 /** Flatten an intersection into a single object literal for clean inference. */
 type Simplify<T> = {
@@ -1485,4 +2340,4 @@ type InferInsert<C extends ModelClass> = Simplify<{
     [K in Exclude<ColumnKeys<InstanceType<C>>, OptionalInsertKeys<InstanceType<C>>>]: ColValue<InstanceType<C>[K]>;
 }>;
 
-export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, Model, type ModelClass, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, type OnConflict, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, SqliteDialect, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, unique, update };
+export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type ExprNode, Expression, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, type LockClause, type LockOptions, Model, type ModelClass, MysqlDialect, type NameMap, type NamingStrategy, NoResultError, NodeSqliteDriver, OPERATORS, type OnConflict, type OnConflictOptions, type OnConflictUpdateOptions, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, Params, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, type SqlExpression, SqliteDialect, type Subquery, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, col, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, fn, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isExpression, isSqlExpression, isSubquery, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toAsyncDriver, toCondNode, toDict, toJSON, toSnakeCase, unique, update, val };