tempest-db-js 0.3.0 → 0.5.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";
@@ -42,6 +64,10 @@ interface SelectNode {
     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;
 }
 /** Operators valid on every column type. */
 interface BaseOperators<T> {
@@ -71,19 +97,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 +142,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. */
@@ -165,6 +213,44 @@ declare class SelectBuilder<Full, Proj = Full> {
     limit(n: number): SelectBuilder<Full, Proj>;
     /** Skip the first `n` rows. */
     offset(n: number): SelectBuilder<Full, Proj>;
+    /**
+     * 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>;
+    /**
+     * 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>;
 }
 /** Build a SELECT over every column of the model. */
 declare function select<C extends ModelClass>(model: C): SelectBuilder<InferModel<C>, InferModel<C>>;
@@ -235,6 +321,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 +342,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 +373,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 +392,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 +448,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 +468,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 +506,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 +702,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 +777,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 +805,17 @@ 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;
+    /**
+     * 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 +827,70 @@ 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;
     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,17 +902,24 @@ 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 —
@@ -674,12 +934,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 +958,7 @@ 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;
+    protected renderConflict(onConflict: NonNullable<InsertNode["onConflict"]>, conflictCols: readonly string[], nextValue: () => string, names: NameMap | undefined): string;
     protected compileReturning(returning: readonly string[] | "*" | null): string;
 }
 /** Get a dialect instance by name. */
@@ -832,6 +1099,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,6 +1159,40 @@ 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>>;
     /** Lazily iterate result rows. Uses driver streaming when available. */
     stream<B extends Executable>(builder: B): AsyncIterableIterator<RowOf<B>>;
@@ -1157,13 +1492,18 @@ interface ColumnFlags {
     readonly primaryKey: boolean;
     readonly notNull: boolean;
     readonly hasDefault: boolean;
+    /**
+     * A `UNIQUE` constraint on the column. Does NOT influence the inferred type —
+     * it is DDL-only metadata (mirrors SQLAlchemy's `mapped_column(unique=True)`).
+     */
+    readonly unique: boolean;
 }
 /**
  * The canonical, dialect-neutral kind of a column type. Mirrors SQLAlchemy's
  * 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`. */
@@ -1178,6 +1518,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 {
@@ -1188,10 +1530,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
@@ -1205,22 +1551,105 @@ 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.
+ * Dialect-neutral tokens rendered uppercase at the DDL edge (mirrors
+ * SQLAlchemy's `ForeignKey(ondelete=..., onupdate=...)`).
+ */
+type FkAction = "cascade" | "restrict" | "set null" | "set default" | "no action";
+/**
+ * A resolved foreign-key reference: the target `table.column` plus optional
+ * referential actions. Produced by `Column.references("table.column", ...)`.
+ */
+interface ForeignKeyRef {
+    readonly table: string;
+    readonly column: string;
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
+/** Options for a foreign-key reference (referential actions). */
+interface ForeignKeyOptions {
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
 /**
  * A typed column builder. Holds runtime metadata (structured `type`, `flags`,
- * `default`, `onUpdate`) and a phantom static type `T` used purely for inference.
+ * `default`, `onUpdate`, foreign-key `reference`) and a phantom static type `T`
+ * used purely for inference.
  */
 declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly type: ColumnType;
@@ -1229,13 +1658,23 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly defaultValue: DefaultValue | null;
     /** The value re-applied on update (e.g. `updated_at`), or `null`. */
     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, 
     /** The default applied on insert, or `null` for none. */
     defaultValue?: DefaultValue | null, 
     /** The value re-applied on update (e.g. `updated_at`), or `null`. */
-    onUpdateValue?: DefaultValue | null);
+    onUpdateValue?: DefaultValue | null, 
+    /** The foreign-key reference this column points to, or `null` for none. */
+    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;
@@ -1243,9 +1682,55 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     notNull(): Column<T, F & {
         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(): 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
+     * 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: string, options?: ForeignKeyOptions): Column<T, F>;
     /**
      * 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;
@@ -1253,6 +1738,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>;
 }
@@ -1321,10 +1810,95 @@ 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
+ * SQLAlchemy's `__table_args__` entries (`UniqueConstraint`, `ForeignKeyConstraint`).
+ * Use the {@link unique} and {@link foreignKey} helpers to build these.
+ */
+type TableConstraint = {
+    readonly kind: "unique";
+    readonly name?: string | undefined;
+    readonly columns: readonly string[];
+} | {
+    readonly kind: "foreignKey";
+    readonly name?: string | undefined;
+    readonly columns: readonly string[];
+    readonly refTable: string;
+    readonly refColumns: readonly string[];
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
 };
+/**
+ * Declare a (possibly composite) `UNIQUE` table constraint over the given
+ * columns. Mirrors SQLAlchemy's `UniqueConstraint("a", "b")`.
+ *
+ * @param columns The column names covered by the constraint.
+ * @returns A unique {@link TableConstraint}.
+ * @throws Error When no columns are given.
+ */
+declare function unique(...columns: string[]): TableConstraint;
+/**
+ * Declare a (possibly composite) foreign-key table constraint. Mirrors
+ * SQLAlchemy's `ForeignKeyConstraint([...], [...], ondelete=...)`.
+ *
+ * @param columns The local column names.
+ * @param refTable The referenced table name.
+ * @param refColumns The referenced column names (same length as `columns`).
+ * @param options Optional constraint `name` and referential actions.
+ * @returns A foreign-key {@link TableConstraint}.
+ * @throws Error When the column arrays are empty or mismatched in length.
+ */
+declare function foreignKey(columns: string[], refTable: string, refColumns: string[], options?: {
+    name?: string;
+    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;
+    /**
+     * Optional table-level constraints (composite unique / foreign keys), returned
+     * by a thunk so forward references resolve lazily. Mirrors SQLAlchemy's
+     * `__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.
@@ -1340,6 +1914,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. */
@@ -1349,6 +1949,8 @@ type ColumnKeys<M> = {
 /** Constructor type for a Model subclass. */
 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> = {
@@ -1386,4 +1988,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 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, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, 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 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 SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, type WritePatch, type WriteValues, activeRecord, and, avg, belongsTo, column, columnNamesOf, columnPropsOf, columnsOf, count, createEngine, createSyncEngine, dbColumn, del, detectDialect, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, isSqlExpression, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, toSnakeCase, unique, update };