uql-orm 0.79.0 → 0.80.0

package/dist/mssql/mssqlDialect.js

@@ -4,7 +4,7 @@ import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { jsonArraySlotArgs, jsonPath, jsonSlotArgs } from '../dialect/jsonSql.js';
 import { MergeSqlDialect } from '../dialect/mergeSqlDialect.js';
 import { getMeta } from '../entity/index.js';
-import { fieldOptionsToCanonical } from '../schema/canonicalType.js';
+import { canonicalToSql, fieldOptionsToCanonical, resolveColumnCanonicalType } from '../schema/canonicalType.js';
 import { QueryRaw } from '../type/index.js';
 import { parseQueryLock } from '../type/index.js';
 import { isAutoIncrement } from '../util/field.util.js';
@@ -13,10 +13,8 @@ import { escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { UqlUsageError } from '../util/uqlError.js';
 /** What SQL Server has. */
 const MSSQL_FEATURES = {
-    // Neither object takes an `IF NOT EXISTS`; both need a `sys` catalogue lookup around them, which
-    // the generator does not emit.
-    ifNotExists: false,
-    indexIfNotExists: false,
+    // No `IF NOT EXISTS` on an index, so `MsSqlIndexDdl` guards the create with a `sys.indexes` lookup.
+    indexIfNotExists: true,
     schemas: true,
     dropTableCascade: false,
     foreignKeyAlter: true,
@@ -40,6 +38,16 @@ const MSSQL_FEATURES = {
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: false,
+    triggers: {
+        preamble: 'SET NOCOUNT ON;',
+        assignsRow: false,
+        body: 'inline',
+        guards: 'beginEnd',
+        layout: 'tableFirst',
+        rows: 'set',
+        scope: 'schema',
+        before: false,
+    },
 };
 /** The `type` `OPENJSON` reports for the JSON scalar an element is compared with; anything else binds as a string. */
 function openJsonType(value) {
@@ -48,6 +56,14 @@ function openJsonType(value) {
     }
     return typeof value === 'boolean' ? 3 : 1;
 }
+/** The table variable an `OUTPUT` fills, `_uql`-prefixed as every name uql invents is. */
+const OUTPUT_TABLE = '@_uql_output';
+/** The one key column and its field, or nothing on a composite key. */
+function soleId(meta) {
+    const [key] = meta.ids;
+    const field = meta.ids.length === 1 ? meta.fields[key] : undefined;
+    return field && { key, field };
+}
 /** Microsoft SQL Server 2017 and up. Identifiers are `"`-quoted, the ANSI spelling `tedious` enables. */
 export class MsSqlDialect extends MergeSqlDialect {
     features = MSSQL_FEATURES;
@@ -74,6 +90,8 @@ export class MsSqlDialect extends MergeSqlDialect {
     maxBindValues = 2100;
     /** `OUTPUT` has no trailing form: it sits between the column list and `VALUES`. */
     returningPosition = 'after-target';
+    /** `OUTPUT` reads the written row off the `INSERTED` pseudo-table. */
+    returnedRowPrefix = 'INSERTED.';
     insertIdSource = 'returning';
     /** Holds the update key lock across the insert; without it two concurrent upserts of one key race. */
     mergeTargetHint = ' WITH (HOLDLOCK)';
@@ -96,30 +114,20 @@ export class MsSqlDialect extends MergeSqlDialect {
         }
         super.pager(ctx, opts, sorted);
     }
-    /**
-     * `SET IDENTITY_INSERT` around an insert that states a key the engine would generate, which it otherwise
-     * refuses; turned off in the same batch, since one table per session may hold it.
-     */
     insert(ctx, entity, payload, opts) {
-        const table = this.identityInsertTarget(entity, payload);
-        if (table) {
-            ctx.append(`SET IDENTITY_INSERT ${table} ON; `);
-        }
-        super.insert(ctx, entity, payload, opts);
-        if (table) {
-            ctx.append(`; SET IDENTITY_INSERT ${table} OFF`);
-        }
+        this.writeRows(ctx, getMeta(entity), payload, () => {
+            super.insert(ctx, entity, payload, opts);
+            ctx.append(';');
+        });
     }
     /** The table to toggle, or nothing when no record writes a key the engine would have generated. */
-    identityInsertTarget(entity, payload) {
-        const meta = getMeta(entity);
-        const [idKey] = meta.ids;
-        const field = meta.ids.length === 1 ? meta.fields[idKey] : undefined;
-        if (!field || !isAutoIncrement(field, true)) {
+    identityInsertTarget(meta, payload) {
+        const id = soleId(meta);
+        if (!id || !isAutoIncrement(id.field, true)) {
             return undefined;
         }
         const records = Array.isArray(payload) ? payload : [payload];
-        const stated = records.some((record) => record[idKey] !== undefined);
+        const stated = records.some((record) => record[id.key] !== undefined);
         return stated ? this.escapedTableName(meta) : undefined;
     }
     /** A `DECIMAL` declared `String`, converted before it crosses the wire, where `tedious` would round it. */
@@ -151,17 +159,44 @@ export class MsSqlDialect extends MergeSqlDialect {
     placeholder(index) {
         return `@p${index}`;
     }
-    /** `OUTPUT` reads the written row out of the `INSERTED` pseudo-table rather than `RETURNING` it. */
+    /**
+     * `OUTPUT` reads the written row out of the `INSERTED` pseudo-table rather than `RETURNING` it, and
+     * always `INTO` a table variable: SQL Server refuses an `OUTPUT` straight back to the client on a table
+     * carrying a trigger, and through a table it works whether one is there or not.
+     */
     returningId(meta) {
         const expression = this.returningIdExpression(meta);
-        return expression ? `OUTPUT ${expression}` : '';
+        return expression ? `OUTPUT ${expression} INTO ${OUTPUT_TABLE}` : '';
+    }
+    upsert(ctx, entity, conflictPaths, payload, extraReturning = '') {
+        this.writeRows(ctx, getMeta(entity), payload, () => super.upsert(ctx, entity, conflictPaths, payload, extraReturning));
     }
-    returningIdExpression(meta) {
-        const [idKey] = meta.ids;
-        return meta.ids.length === 1 ? `INSERTED.${this.escapeId(this.columnOf(meta, idKey))} ${this.escapeId('id')}` : '';
+    /**
+     * A statement writing rows, `write`, wrapped in what SQL Server needs around one. The table variable its
+     * `OUTPUT` fills, typed as the id column is, and the read handing that back, uncounted so the batch
+     * reports the rows written alone; none on a composite key, which has no id to hand back. And `SET
+     * IDENTITY_INSERT` where a row states a key the engine would generate, turned off in the same batch.
+     */
+    writeRows(ctx, meta, payload, write) {
+        const id = soleId(meta);
+        const column = this.escapeId('id');
+        const identity = this.identityInsertTarget(meta, payload);
+        if (id) {
+            ctx.append(`DECLARE ${OUTPUT_TABLE} TABLE (${column} ${canonicalToSql(resolveColumnCanonicalType(id.field), this)}); `);
+        }
+        if (identity) {
+            ctx.append(`SET IDENTITY_INSERT ${identity} ON; `);
+        }
+        write();
+        if (identity) {
+            ctx.append(` SET IDENTITY_INSERT ${identity} OFF;`);
+        }
+        if (id) {
+            ctx.append(` SET NOCOUNT ON; SELECT ${column} FROM ${OUTPUT_TABLE}; SET NOCOUNT OFF;`);
+        }
     }
     mergeReturning(expression) {
-        return `OUTPUT ${expression}`;
+        return `OUTPUT ${expression} INTO ${OUTPUT_TABLE}`;
     }
     /** A row lock is a hint on the table here, which `rowLocks.placement` says instead of a trailing clause. */
     lockHint(q) {
@@ -217,9 +252,7 @@ export class MsSqlDialect extends MergeSqlDialect {
     }
     /** There is no `CREATE SCHEMA IF NOT EXISTS`, and `CREATE SCHEMA` has to be alone in its batch. */
     createSchemaSql(schema) {
-        const literal = escapeSingleQuotes(schema);
-        const quoted = escapeSingleQuotes(this.escapeId(schema, true));
-        return `IF SCHEMA_ID(N'${literal}') IS NULL EXEC(N'CREATE SCHEMA ${quoted}')`;
+        return `IF SCHEMA_ID(${this.escape(schema)}) IS NULL EXEC(${this.escape(`CREATE SCHEMA ${this.escapeId(schema, true)}`)})`;
     }
     /** The estimate the engine already keeps per partition, live without a stats refresh. */
     estimatedCount(ctx, entity) {
@@ -229,8 +262,19 @@ export class MsSqlDialect extends MergeSqlDialect {
             ` JOIN sys.schemas s ON s.schema_id = o.schema_id` +
             ` WHERE p.index_id IN (0, 1) AND o.name = `);
         ctx.addValue(this.resolveTableAlias(meta));
+        // The connection's own default schema where the entity names none, as the introspector reads it.
+        const schema = this.resolveSchema(meta);
         ctx.append(' AND s.name = ');
-        ctx.addValue(this.resolveSchema(meta) ?? 'dbo');
+        if (schema === undefined) {
+            ctx.append('SCHEMA_NAME()');
+        }
+        else {
+            ctx.addValue(schema);
+        }
+    }
+    /** Null-safe on every version, `EXCEPT` comparing NULLs as equal: `IS DISTINCT FROM` needs 2022. */
+    neExpr(field, ph) {
+        return `EXISTS (SELECT ${field} EXCEPT SELECT ${ph})`;
     }
     numericCast(expr) {
         return `TRY_CAST(${expr} AS FLOAT)`;

package/dist/mssql/mssqlQuerier.js

@@ -25,8 +25,8 @@ export class MsSqlQuerier extends AbstractPoolQuerier {
     async internalRun(query, values) {
         const res = await this.#request(values).query(query);
         return this.buildUpdateResult({
-            // `rowsAffected` carries one entry per statement, and a `MERGE` upsert emits its `OUTPUT`
-            // alongside the write, so the counts are summed rather than read at [0].
+            // `rowsAffected` carries one entry per statement, and a write runs in a batch of several - the table
+            // variable its ids go through, the read handing them back uncounted - so the counts are summed.
             changes: res.rowsAffected.reduce((total, count) => total + count, 0),
             rows: decodeWireTypes(res.recordset, res.recordset?.columns),
         });

package/dist/schema/canonicalType.d.ts

@@ -1,6 +1,6 @@
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { VectorCast } from '../dialect/vectorCast.js';
-import type { ColumnType, FieldOptions } from '../type/entity.js';
+import type { ColumnType, EntityGetter, FieldMeta, FieldOptions } from '../type/entity.js';
 import type { CanonicalType, TypeCategory } from './types.js';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export declare function isVectorCategory(category: TypeCategory | undefined): category is VectorCast;
@@ -51,3 +51,8 @@ export declare function isBreakingTypeChange(from: CanonicalType, to: CanonicalT
  * Get the UQL ColumnType that best matches a canonical type.
  */
 export declare function canonicalToColumnType(type: CanonicalType): ColumnType;
+/**
+ * A field's canonical type, taken from the referenced key where the field gave `references` and no
+ * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
+ */
+export declare function resolveColumnCanonicalType(field: FieldMeta, seen?: Set<EntityGetter>): CanonicalType;

package/dist/schema/canonicalType.js

@@ -1,4 +1,5 @@
 // Canonical types, between an engine's SQL types and TypeScript's.
+import { fieldOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
 import { QueryRaw } from '../type/index.js';
 import { columnFamily, isIntegerColumn } from '../util/field.util.js';
 import { constantSql } from '../util/raw.js';
@@ -456,3 +457,16 @@ export function canonicalToColumnType(type) {
             return 'sparsevec';
     }
 }
+/**
+ * A field's canonical type, taken from the referenced key where the field gave `references` and no
+ * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
+ */
+export function resolveColumnCanonicalType(field, seen = new Set()) {
+    const hasExplicitType = !!field.columnType || !field.typeFromReference;
+    if (!hasExplicitType && field.references && !seen.has(field.references)) {
+        seen.add(field.references);
+        const referencedMeta = getMeta(field.references());
+        return resolveColumnCanonicalType(fieldOf(referencedMeta, soleIdOf(referencedMeta, 'a foreign key')), seen);
+    }
+    return fieldOptionsToCanonical(field);
+}

package/dist/schema/schemaASTBuilder.d.ts

@@ -1,8 +1,7 @@
-import type { EntityGetter } from '../type/entity.js';
-import type { EntityMeta, EntityWhereMeta, FieldMeta, FieldOptions, Type } from '../type/index.js';
+import type { EntityMeta, EntityWhereMeta, FieldOptions, Type } from '../type/index.js';
 import type { NamingStrategy } from '../type/namingStrategy.js';
 import { SchemaAST } from './schemaAST.js';
-import { type CanonicalType, type ForeignKeyAction } from './types.js';
+import { type ForeignKeyAction } from './types.js';
 /**
  * Options for building SchemaAST from entities.
  */
@@ -34,8 +33,3 @@ export interface BuildSchemaASTOptions {
  * resolves against a table another entity declares, and an index against the columns of its own.
  */
 export declare function buildSchemaAST(entities: readonly Type<object>[], options?: BuildSchemaASTOptions): SchemaAST;
-/**
- * A field's canonical type, taken from the referenced key where the field gave `references` and no
- * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
- */
-export declare function resolveColumnCanonicalType(field: FieldMeta, seen?: Set<EntityGetter>): CanonicalType;

package/dist/schema/schemaASTBuilder.js

@@ -1,14 +1,12 @@
-import { fieldOf, foreignKeysOf, getMeta, soleIdOf } from '../entity/metadata/definition.js';
+import { fieldOf, foreignKeysOf, getMeta } from '../entity/metadata/definition.js';
 import { declaredIndexes, declaredIndexName, renderIndexColumn } from '../util/ddlExpression.util.js';
 import { fulltextWeights, textWeightSteps } from '../util/dialect.util.js';
-import { isInlinedExpression } from '../util/field.util.js';
-import { isSoleIdField } from '../util/field.util.js';
-import { isAutoIncrement } from '../util/field.util.js';
+import { isAutoIncrement, isInlinedExpression, isSoleIdField } from '../util/field.util.js';
 import { definedEntries } from '../util/object.util.js';
 import { derivedForeignKeyName, derivedIndexName, qualifyName } from '../util/sql.util.js';
-import { fieldOptionsToCanonical } from './canonicalType.js';
+import { resolveColumnCanonicalType } from './canonicalType.js';
 import { createTableNode, SchemaAST } from './schemaAST.js';
-import { DEFAULT_FOREIGN_KEY_ACTION, } from './types.js';
+import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Build a SchemaAST from entity classes (decorated with `@Entity`, `@Field`, etc.).
  *
@@ -40,19 +38,6 @@ export function buildSchemaAST(entities, options = {}) {
 function refuseDdl() {
     throw new TypeError('building the schema of an entity that declares SQL (a check, a stored computed column, an index expression or predicate) needs a dialect to render it: pass `compileDdl`, as `buildEntityAST` does');
 }
-/**
- * A field's canonical type, taken from the referenced key where the field gave `references` and no
- * `type` (`typeFromReference`), so a foreign key matches the key it points at; `columnType` always wins.
- */
-export function resolveColumnCanonicalType(field, seen = new Set()) {
-    const hasExplicitType = !!field.columnType || !field.typeFromReference;
-    if (!hasExplicitType && field.references && !seen.has(field.references)) {
-        seen.add(field.references);
-        const referencedMeta = getMeta(field.references());
-        return resolveColumnCanonicalType(fieldOf(referencedMeta, soleIdOf(referencedMeta, 'a foreign key')), seen);
-    }
-    return fieldOptionsToCanonical(field);
-}
 /**
  * Add a table from entity metadata.
  */
@@ -80,7 +65,8 @@ function addTableFromEntity(ctx, meta) {
             isPrimaryKey,
             isAutoIncrement: isAutoIncrement(field, isSoleKey),
             isUnique: field.unique ?? false,
-            generatedAs: field.computed && ctx.compileDdl(field.computed, meta.entity),
+            // A stamp is filled by a trigger, so it is a column like any other; only `stored: true` generates.
+            generatedAs: field.stored === true && field.computed ? ctx.compileDdl(field.computed, meta.entity) : undefined,
             comment: field.comment,
             enum: field.enum,
             table,

package/dist/sqlite/sqliteDialect.d.ts

@@ -36,7 +36,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
      */
     protected appendDefaultInsertValue(ctx: QueryContext, field: FieldOptions | undefined): void;
     protected readonly caseInsensitiveMatch = "native";
-    protected get neOp(): string;
+    neExpr(field: string, ph: string): string;
     normalizeValue(value: unknown): unknown;
     /**
      * `OFFSET` is only legal after a `LIMIT` here too, so a bare `$skip` needs one - `-1` being

package/dist/sqlite/sqliteDialect.js

@@ -17,7 +17,6 @@ function ftsQuery(columns, value) {
 }
 /** What SQLite and the engines derived from it have. */
 export const SQLITE_FEATURES = {
-    ifNotExists: true,
     indexIfNotExists: true,
     schemas: false, // SQLite's namespaces are attached database files, not declared objects
     dropTableCascade: false,
@@ -41,6 +40,16 @@ export const SQLITE_FEATURES = {
     narrowVectorTypes: false,
     vectorTuningNeedsTransaction: false,
     serialDeclaresPrimaryKey: true,
+    triggers: {
+        preamble: '',
+        assignsRow: false,
+        body: 'inline',
+        guards: 'clause',
+        layout: 'timingFirst',
+        rows: 'row',
+        scope: 'schema',
+        before: true,
+    },
 };
 export class SqliteDialect extends AbstractSqlDialect {
     features = SQLITE_FEATURES;
@@ -114,8 +123,8 @@ export class SqliteDialect extends AbstractSqlDialect {
     // SQLite's `LIKE` already ignores case on both sides, for ASCII - and only ASCII, with or without
     // `NOCASE`, so folding the pattern here would break the accented text the engine leaves alone.
     caseInsensitiveMatch = 'native';
-    get neOp() {
-        return 'IS NOT';
+    neExpr(field, ph) {
+        return `${field} IS NOT ${ph}`;
     }
     normalizeValue(value) {
         if (value instanceof Date)

package/dist/type/dialect.d.ts

@@ -1,5 +1,5 @@
 import type { EntityMeta, UpdatePayload } from './entity.js';
-import type { Query, QueryConflictPaths, QueryOptions, QueryPage, QuerySearch, RelationQuery } from './query.js';
+import type { Query, QueryConflictPaths, QueryPage, QueryRenderOptions, QuerySearch, RelationQuery } from './query.js';
 import type { QueryAggMap, QueryAggregate, QueryAggregateOp, QueryGroupMap } from './queryAggregate.js';
 import type { QueryWhere } from './queryWhere.js';
 import type { Type } from './utility.js';
@@ -7,7 +7,7 @@ import type { QueryVectorQuery } from './vector.js';
 /**
  * comparison options.
  */
-export type QueryComparisonOptions = QueryOptions & {
+export type QueryComparisonOptions = QueryRenderOptions & {
     /**
      * Whether this fragment is rendered as an operand of an enclosing `AND`/`OR`/`NOT`. An operand
      * parenthesizes itself when it emits more than one term, so no fragment ever depends on the
@@ -78,7 +78,6 @@ export type InsertIdSource = 'returning' | 'firstId';
  * Features of the database engine (SQL syntax layer).
  */
 export interface DialectFeatures {
-    readonly ifNotExists: boolean;
     readonly indexIfNotExists: boolean;
     /**
      * Whether the engine has namespaces a table can sit behind. `false` leaves every table
@@ -176,6 +175,61 @@ export interface SqlDialectFeatures extends DialectFeatures {
     readonly vectorTuningNeedsTransaction: boolean;
     /** Whether the serial column type states `PRIMARY KEY` itself, as SQLite's `AUTOINCREMENT` must. */
     readonly serialDeclaresPrimaryKey: boolean;
+    /** How the engine spells a trigger. One value rather than a flag each, as {@link rowLocks} is. */
+    readonly triggers: TriggerFeatures;
+}
+/**
+ * What a trigger body calls the rows it reads. Row-based engines hand it a record on each side; SQL
+ * Server hands it the two tables of the set it touched.
+ */
+export type TriggerRowName = 'NEW' | 'OLD' | 'inserted' | 'deleted';
+/** How a dialect spells a trigger, once {@link SqlDialectFeatures.triggers} names its shape. */
+export interface TriggerFeatures {
+    /**
+     * Where the body lives: a function of its own that the trigger names (the Postgres family), or inside
+     * the `CREATE TRIGGER` itself (everywhere else).
+     */
+    readonly body: 'function' | 'inline';
+    /**
+     * How it states which rows it fires for: `UPDATE OF` beside a `WHEN` (`'clause'`), or, where there is
+     * no usable `WHEN` - the MySQL family, CockroachDB, SQL Server - the same condition wrapping the body,
+     * as `IF c THEN ... END IF;` (`'thenEndIf'`) or T-SQL's `IF c BEGIN ... END` (`'beginEnd'`).
+     */
+    readonly guards: 'clause' | 'thenEndIf' | 'beginEnd';
+    /**
+     * Whether it fires once per row, with a row on each side, or once per statement over the set it
+     * touched. SQL Server is the only one here that is set-based, reading `inserted` and `deleted`.
+     */
+    readonly rows: 'row' | 'set';
+    /**
+     * Where a trigger's name is unique, and so what a `DROP` has to name: per table on the Postgres
+     * family, which spells `DROP TRIGGER x ON t`, and per schema everywhere else, which spells
+     * `DROP TRIGGER x`. Two tables may carry the same trigger name only under `'table'`.
+     */
+    readonly scope: 'table' | 'schema';
+    /**
+     * Where the table sits in the statement: after the timing, `BEFORE UPDATE ON t`, or ahead of it and
+     * behind an `AS`, `ON t AFTER UPDATE AS` - which is T-SQL's shape and nobody else's.
+     */
+    readonly layout: 'timingFirst' | 'tableFirst';
+    /**
+     * What every body opens with, or `''`. T-SQL wants `SET NOCOUNT ON`: a trigger running its own DML
+     * otherwise sends a rowcount of its own back, and the client reads that as what the original statement
+     * affected. Nothing else here needs a preamble.
+     */
+    readonly preamble: string;
+    /**
+     * Whether a body may assign to the row it was handed, `NEW."col" := ...`. SQLite forbids writing `NEW`
+     * at all, and SQL Server is handed a set rather than a row, so on both a trigger that fills a column
+     * has to restate the row as an `UPDATE` after the write instead.
+     */
+    readonly assignsRow: boolean;
+    /**
+     * Whether it can fire before the write, which is what a stamp needs. SQL Server has only `AFTER` and
+     * `INSTEAD OF`, and `INSTEAD OF` would make the trigger responsible for performing the write itself,
+     * so a `before*` event is refused there rather than silently made to mean something else.
+     */
+    readonly before: boolean;
 }
 /**
  * What a SQL statement is rendered through, as a `raw` callback and a query context see it:
@@ -186,6 +240,12 @@ export interface SqlQueryDialect {
      * The SQL dialect name.
      */
     readonly dialectName: SqlDialectName;
+    /**
+     * The engine whose SQL this one also accepts, which is itself unless it is a fork: CockroachDB runs
+     * Postgres's PL/pgSQL and MariaDB runs MySQL's. What lets a body, or any other hand-written SQL, be
+     * declared once for a family rather than copied per member.
+     */
+    readonly dialectFamily: SqlDialectName;
     /**
      * the escape character for identifiers.
      */
@@ -193,17 +253,17 @@ export interface SqlQueryDialect {
     /** What the engine can do. */
     readonly features: SqlDialectFeatures;
     /** A read; with `totalAlias`, every row also carries the unpaged match count under that alias. */
-    find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryOptions, totalAlias?: string): void;
+    find<E>(ctx: QueryContext, entity: Type<E>, q: Query<E>, opts?: QueryRenderOptions, totalAlias?: string): void;
     /** A count of the records matching the filter, or of those a page of it takes. */
-    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryPage<E>, opts?: QueryOptions): void;
+    count<E>(ctx: QueryContext, entity: Type<E>, q: QueryPage<E>, opts?: QueryRenderOptions): void;
     /** An insert of one record or many. */
-    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryOptions): void;
+    insert<E>(ctx: QueryContext, entity: Type<E>, payload: E | E[], opts?: QueryRenderOptions): void;
     /** An update of the records the query matches. */
-    update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryOptions): void;
+    update<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: QueryRenderOptions): void;
     /** An upsert of one record or many by their conflict paths. */
     upsert<E>(ctx: QueryContext, entity: Type<E>, conflictPaths: QueryConflictPaths<E>, payload: E | E[]): void;
     /** A delete of the records the query matches, a soft delete where the entity has one. */
-    delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions): void;
+    delete<E>(ctx: QueryContext, entity: Type<E>, q: QuerySearch<E>, opts?: QueryRenderOptions): void;
     /**
      * escape an identifier.
      * @param val the value to be escaped
@@ -237,7 +297,7 @@ export interface SqlQueryDialect {
     /**
      * Build an aggregate query.
      */
-    aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): void;
+    aggregate<E, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(ctx: QueryContext, entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryRenderOptions): void;
     /**
      * Get the placeholder for a parameter at the given index (1-based).
      * Default: '?' for MySQL/MariaDB/SQLite, '$n' for PostgreSQL.

package/dist/type/entity.d.ts

@@ -1,8 +1,9 @@
 import type { EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
+import type { SqlDialectName } from './dialect.js';
 import type { FilterOptions, RelationQuery } from './query.js';
 import type { ColumnRef, QueryRaw, RelationAggregate } from './queryRaw.js';
 import type { QueryWhere } from './queryWhere.js';
-import type { Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
+import type { AtLeastOne, Except, ExactlyOne, IsEqual, IsMany, Json, Scalar, Type, Unpacked, Writable } from './utility.js';
 import type { VectorDistance, VectorIndexOptions, VectorIndexType } from './vector.js';
 /** Brands the property an entity is identified by, where it is not `id`, `_id` or `uuid`. */
 export declare const idKey: unique symbol;
@@ -254,8 +255,12 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
      * subquery a `$count` reads. Both resolve to SQL at registration, so everything downstream sees one.
      */
     readonly computed?: ComputedSql<E>;
-    /** Whether {@link FieldOptions.computed} is a generated column rather than spliced into each read; no query changes either way. */
-    readonly stored?: boolean;
+    /**
+     * Where {@link FieldOptions.computed} lives instead of being spliced into each read. `true` makes it a
+     * generated column, which takes only an immutable expression; a list of events makes it a stamp a trigger
+     * writes on each, whoever writes the row - how `CURRENT_TIMESTAMP` is kept, where `onUpdate` sees only uql's writes.
+     */
+    readonly stored?: boolean | readonly StampEvent[];
     readonly updatable?: boolean;
     readonly eager?: boolean;
     readonly onInsert?: OnFieldCallback<V>;
@@ -691,11 +696,97 @@ export type EntityMeta<E> = {
     checks?: EntityCheckMeta<E>[];
     /** Lifecycle hooks registered via @BeforeInsert, @AfterUpdate, etc. */
     hooks?: Partial<Record<HookEvent, HookRegistration[]>>;
+    /** Triggers the database runs, compiled when the schema is built. */
+    triggers?: EntityTriggerMeta<E>[];
     /** Bumped by every `define*` call, so what is derived from the metadata can tell it changed. */
     revision: number;
     /** The revision `getMeta` last finalized, which is what makes finalizing idempotent and re-entrant. */
     processedAt?: number;
 };
+/** When the database writes a stamp: as the row is inserted, as it is updated, or both. */
+export type StampEvent = 'insert' | 'update';
+/**
+ * The events a trigger fires on: the lifecycle names, minus the upsert pair, which names no event of its
+ * own because `ON CONFLICT` fires the insert or the update triggers, and minus `afterLoad`, which is a
+ * read. Derived from {@link HookEvent} so the two vocabularies cannot drift.
+ */
+export type TriggerEvent = Exclude<HookEvent, 'beforeUpsert' | 'afterUpsert' | 'afterLoad'>;
+/** Both events for one operation, since a trigger's timing never changes which rows it has. */
+type TriggerEventOn<Op extends string> = Extract<TriggerEvent, `before${Op}` | `after${Op}`>;
+/** The events with a row on both sides, the only ones that can say which columns moved. */
+type TriggerUpdateEvent = TriggerEventOn<'Update'>;
+/**
+ * The rows an event has, as `where` keys them: the incoming one on an insert, the outgoing one on a
+ * delete, both on an update.
+ */
+type TriggerRow<Ev extends TriggerEvent> = Ev extends TriggerEventOn<'Insert'> ? '$new' : Ev extends TriggerEventOn<'Delete'> ? '$old' : '$new' | '$old';
+/** One row's refs, rendering `NEW."col"` or `OLD."col"`, or `never` where the event has no such row. */
+type TriggerRowRefs<E, Ev extends TriggerEvent, R extends '$new' | '$old'> = R extends TriggerRow<Ev> ? RefMap<E> : never;
+/**
+ * What a trigger runs, over its rows: the incoming row first and the outgoing one second, on every event.
+ * The one an event lacks is `never`, so reading it does not compile, and a body reading only the outgoing
+ * row - `(_newRow, oldRow)` - serves an update and a delete alike.
+ */
+type TriggerBody<E, Ev extends TriggerEvent> = (newRow: TriggerRowRefs<E, Ev, '$new'>, oldRow: TriggerRowRefs<E, Ev, '$old'>) => QueryRaw;
+/**
+ * A condition as data: a predicate on each row it names, of the rows the event has, all of which hold.
+ * The row is `$`-marked, as the operators inside it are, so it never reads as a field of the entity.
+ */
+type TriggerPredicate<E, Ev extends TriggerEvent> = {
+    readonly [R in TriggerRow<Ev>]?: EntityPredicate<E>;
+};
+/**
+ * The body, the engine's own SQL: one for every engine it reads alike, or a map naming one per engine
+ * where they differ, as SQL Server's set-based `inserted`/`deleted` does. A missing entry for the engine
+ * in use is refused at `sync`, since an entity is declared without knowing which pool will render it.
+ */
+type TriggerRun<E, Ev extends TriggerEvent> = TriggerBody<E, Ev> | Readonly<AtLeastOne<Record<SqlDialectName, TriggerBody<E, Ev>>>>;
+/**
+ * A trigger, `{ on: 'beforeUpdate', of: (post) => [post.body], run: (newRow) => raw`...` }`.
+ *
+ * A list rather than a map keyed by the event, as `checks` and `indexes` are lists: several triggers may
+ * share an event, they fire in the order written, and each is named, diffed and dropped by that name.
+ */
+export type TriggerOptions<E = unknown> = {
+    [Ev in TriggerEvent]: {
+        readonly on: Ev;
+        /**
+         * What to call this trigger within the entity, for a clearer identifier than its event and position.
+         * A label, not the identifier: uql prefixes and qualifies what it installs, so it can tell its own
+         * objects from hand-written ones and two entities may share a label.
+         */
+        readonly name?: string;
+        /**
+         * The columns whose change the trigger waits for, reading as the `UPDATE OF` it renders. Beside it
+         * goes a `WHEN` comparing each with `IS DISTINCT FROM`, which is the point of the pair: `UPDATE OF`
+         * fires on a column that was merely assigned, and the comparison narrows that to one that moved.
+         */
+        readonly of?: Ev extends TriggerUpdateEvent ? (refs: RefMap<E>) => readonly ColumnRef<string>[] : never;
+        /**
+         * A further condition, as the `WHEN` the engine evaluates before entering the body, over the rows the
+         * body reads: a predicate on each, `{ $old: { status: 'draft' }, $new: { status: 'published' } }`,
+         * rendered on every engine from the one declaration, or SQL off them for what no predicate states.
+         */
+        readonly where?: TriggerPredicate<E, Ev> | TriggerBody<E, Ev>;
+        readonly run: TriggerRun<E, Ev>;
+    };
+}[TriggerEvent];
+/**
+ * A trigger as entity metadata keeps it: the column callback resolved to keys, and a body widened to
+ * take both rows, which the renderer passes whatever the event, each body reading only its own.
+ */
+export type EntityTriggerMeta<E = object> = Except<TriggerOptions<E>, 'of' | 'where' | 'run'> & {
+    readonly of?: readonly string[];
+    readonly where?: TriggerPredicate<E, TriggerUpdateEvent> | TriggerMetaBody<E>;
+    readonly run: TriggerMetaBody<E> | Readonly<Partial<Record<SqlDialectName, TriggerMetaBody<E>>>>;
+};
+/**
+ * A body as the renderer calls it, with both rows whatever the event. Bivariant, as {@link EntitySql} is,
+ * so a body typing the row its event lacks as `never` is still held here.
+ */
+export type TriggerMetaBody<E> = {
+    run(newRow: RefMap<E>, oldRow: RefMap<E>): QueryRaw;
+}['run'];
 /**
  * A table's `CHECK`, `{ where: { balance: { $gte: 0 } } }`, or SQL off the refs,
  * `{ where: (wallet) => raw`${wallet.spent} <= ${wallet.balance}` }`.
@@ -743,6 +834,8 @@ export type EntityOptions<E = unknown> = {
     readonly checks?: readonly CheckOptions<E>[];
     /** Each lifecycle event and the methods it runs, read off the key map: `{ beforeInsert: (post) => [post.stamp] }`. */
     readonly hooks?: Partial<Record<HookEvent, (keys: KeyMap<E>) => readonly MethodKey<E>[]>>;
+    /** Triggers the database runs, in the order written. See {@link TriggerOptions}. */
+    readonly triggers?: readonly TriggerOptions<E>[];
 };
 /**
  * Everything an index carries beyond its columns, as the migration builder's `table.index(...)` takes it,