uql-orm 0.78.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;
@@ -19,6 +19,7 @@ export declare function canonicalColumnType(sqlType: string, reported?: {
     length?: number;
     precision?: number;
     scale?: number;
+    dimensions?: number;
 }): CanonicalType;
 /**
  * Convert a canonical type to a SQL type string for a specific dialect instance.
@@ -50,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,5 +1,8 @@
 // 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';
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export function isVectorCategory(category) {
     return category === 'vector' || category === 'halfvec' || category === 'sparsevec';
@@ -272,11 +275,23 @@ export function canonicalColumnType(sqlType, reported = {}) {
     const base = sqlToCanonical(sqlType);
     return {
         ...base,
-        length: reported.length ?? base.length,
+        // A vector states its length as `dimensions`, and only a vector may: one bound, named from either side.
+        length: reported.dimensions ?? reported.length ?? base.length,
         precision: reported.precision ?? base.precision,
         scale: reported.scale ?? base.scale,
     };
 }
+/**
+ * The SQL type a field declares, however it named one: `columnType`, the engine's own as a `raw`
+ * constant, or a `type` that is a SQL string rather than a constructor.
+ */
+function declaredSqlType(options) {
+    const { columnType, type } = options;
+    if (columnType instanceof QueryRaw) {
+        return constantSql(columnType);
+    }
+    return columnType ?? (typeof type === 'string' ? type : undefined);
+}
 /**
  * Convert a canonical type to a SQL type string for a specific dialect instance.
  */
@@ -339,21 +354,13 @@ export function engineType(dialect) {
  * Convert UQL FieldOptions to a canonical type.
  */
 export function fieldOptionsToCanonical(options) {
-    // An explicit column type is read exactly as an introspected one is: the SQL type, plus whatever
-    // bounds are stated beside it.
-    if (options.columnType) {
-        return canonicalColumnType(options.columnType, options);
-    }
-    // Infer from type, which is a SQL type string or one of the constructors.
-    const { type } = options;
-    if (typeof type === 'string') {
-        const canonical = sqlToCanonical(type);
-        // Propagate explicit dimensions into CanonicalType.length for vector types
-        return options.dimensions && isVectorCategory(canonical.category)
-            ? { ...canonical, length: options.dimensions }
-            : canonical;
+    // A SQL type is read exactly as an introspected one is, whichever option named it, so a bound stated
+    // beside it is read the same way either way.
+    const declared = declaredSqlType(options);
+    if (declared !== undefined) {
+        return canonicalColumnType(declared, options);
     }
-    switch (columnFamily(type)) {
+    switch (columnFamily(options.type)) {
         case 'numeric':
             // BIGINT for every `Number` without a scale, key or not: a 32-bit column is a migration waiting
             // to happen, and the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
@@ -450,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.