uql-orm 0.82.0 → 0.83.0

package/dist/cockroachdb/crdbQuerierPool.js

@@ -1,13 +1,13 @@
 import { Pool, types } from 'pg';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
-import { numericTypes } from '../postgres/pgNumericTypes.js';
+import { wireTypes } from '../postgres/pgWireTypes.js';
 import { CockroachDialect } from './cockroachDialect.js';
 /**
  * QuerierPool for CockroachDB using the `pg` driver Pool.
  */
 export class CrdbQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
-        super(new CockroachDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
+        super(new CockroachDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: wireTypes(types), ...opts }), extra);
     }
 }

package/dist/dialect/abstractSqlDialect.d.ts

@@ -698,7 +698,7 @@ export declare abstract class AbstractSqlDialect extends VectorSqlDialect implem
     private sizeCondition;
     /** `<distance> <op> ?`, the `$where` half of a vector search, its bounds checked here since `/http` input is untyped. */
     private vectorNearCondition;
-    /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
+    /** ANSI-style single-quote escaping. */
     escape(value: unknown): string;
     protected get regexpOp(): string;
     /**

package/dist/dialect/abstractSqlDialect.js

@@ -1953,7 +1953,7 @@ export class AbstractSqlDialect extends VectorSqlDialect {
         const distance = (fragmentCtx) => this.appendVectorDistance(fragmentCtx, meta, key, near, prefix);
         return this.boundConditions(ctx, distance, bounds, (operand, op, val) => (isOrderedOp(op) ? this.operatorCondition(ctx, operand, op, val) : undefined), 'unsupported $near bound');
     }
-    /** ANSI-style single-quote escaping. MySQL-family dialects override this for backslash escaping. */
+    /** ANSI-style single-quote escaping. */
     escape(value) {
         return escapeAnsiSqlLiteral(value);
     }

package/dist/dialect/hydrateColumn.js

@@ -1,3 +1,4 @@
+import { decodeDate } from '../util/date.js';
 import { decodeWideNumber } from '../util/wideNumber.js';
 import { decodeFloat32s, parseVectorLiteral } from './vectorCast.js';
 /**
@@ -31,7 +32,7 @@ const float32Decoder = (value) => {
 const DECODERS = {
     // 0/1 from SQLite's INTEGER or MySQL's TINYINT(1). Already a boolean on Postgres.
     boolean: (value) => (typeof value === 'boolean' ? value : Boolean(value)),
-    date: (value) => (typeof value === 'string' ? (parseDate(value) ?? value) : value),
+    date: (value) => (typeof value === 'string' ? decodeDate(value) : value),
     // Only a string can be bytes that crossed JSON: bytes a driver already decoded stay as they are.
     bytes: (value) => typeof value === 'string' && value.startsWith(BYTES_PREFIX) ? hexBytes(value.slice(BYTES_PREFIX.length)) : value,
     // A number too, not just text: `type: BigInt` is BIGINT, which the pg pools decode at the wire.
@@ -61,17 +62,6 @@ const DECODERS = {
     halfvec: vectorDecoder('halfvec'),
     sparsevec: vectorDecoder('sparsevec'),
 };
-/**
- * An ISO 8601 timestamp as a `Date`, its fraction cut to the milliseconds one holds, and a bare date at
- * local midnight, which is how `pg` reads a `date`. `undefined` for text that is neither.
- */
-function parseDate(text) {
-    const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
-    const date = day
-        ? new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3]))
-        : new Date(text.replace(/(\.\d{3})\d+/, '$1'));
-    return Number.isNaN(date.getTime()) ? undefined : date;
-}
 /**
  * What bytes crossing JSON start with, before two hex digits per byte: Postgres's own text for `bytea`,
  * which every dialect spells, so a string a driver reads from a column on its own is never mistaken.

package/dist/dialect/mysqlLikeSqlDialect.d.ts

@@ -78,6 +78,8 @@ export declare abstract class MysqlLikeSqlDialect extends AbstractSqlDialect {
     /** Bytes as the hex text `decodeColumn` reads back, whole. */
     protected bytesAsText(expr: string): string;
     escape(value: unknown): string;
+    /** A date as UTC text, which a `DATETIME` stores as is, where a driver would convert it to its own zone. */
+    normalizeValue(value: unknown): unknown;
     /**
      * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
      * the server answers "Can't find FULLTEXT index matching the column list". Declare it with

package/dist/dialect/mysqlLikeSqlDialect.js

@@ -1,4 +1,5 @@
 import { getMeta } from '../entity/index.js';
+import { utcTimestamp } from '../util/date.js';
 import { textSearchFields } from '../util/index.js';
 import { escapeMysqlSqlLiteral, escapeSingleQuotes } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect, } from './abstractSqlDialect.js';
@@ -187,6 +188,10 @@ export class MysqlLikeSqlDialect extends AbstractSqlDialect {
     escape(value) {
         return escapeMysqlSqlLiteral(value);
     }
+    /** A date as UTC text, which a `DATETIME` stores as is, where a driver would convert it to its own zone. */
+    normalizeValue(value) {
+        return value instanceof Date ? utcTimestamp(value) : super.normalizeValue(value);
+    }
     /**
      * `MATCH(cols) AGAINST(?)`, which needs a `FULLTEXT` index over exactly those columns: without one
      * the server answers "Can't find FULLTEXT index matching the column list". Declare it with

package/dist/dialect/pgLikeSqlDialect.d.ts

@@ -105,6 +105,7 @@ export declare abstract class PgLikeSqlDialect extends AbstractSqlDialect {
      * array takes its type from `operand`, so it needs none of the casts `bind` would give each value.
      */
     protected formatIn(ctx: QueryContext, operand: string, values: unknown[], negate: boolean, bind: (value: unknown) => string): string;
+    escape(value: unknown): string;
     protected numericCast(expr: string): string;
     protected appendJsonValue(ctx: QueryContext, value: unknown, type: JsonColumnType): void;
     /**

package/dist/dialect/pgLikeSqlDialect.js

@@ -1,6 +1,7 @@
 import { QueryRaw, } from '../type/index.js';
+import { utcTimestamp } from '../util/date.js';
 import { fulltextConfig, fulltextIndexOver, hasVectorNear, textSearchFields } from '../util/dialect.util.js';
-import { escapeSingleQuotes } from '../util/sqlLiteral.js';
+import { escapePgSqlLiteral, escapeSingleQuotes, PG_UTC } from '../util/sqlLiteral.js';
 import { AbstractSqlDialect } from './abstractSqlDialect.js';
 import { JSON_PULL_ALIAS, RELATION_ROW_ALIAS } from './aliases.js';
 import { BYTES_PREFIX } from './hydrateColumn.js';
@@ -128,10 +129,11 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         return statements;
     }
     normalizeValue(value) {
-        if (value != null && typeof value === 'object' && Array.isArray(value)) {
-            return this.driverCapabilities.nativeArrays ? value : toPgArray(value);
+        if (Array.isArray(value)) {
+            const values = value.map(utcDate);
+            return this.driverCapabilities.nativeArrays ? values : toPgArray(values);
         }
-        return super.normalizeValue(value);
+        return super.normalizeValue(utcDate(value));
     }
     placeholder(index) {
         return `$${index}`;
@@ -240,6 +242,9 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         const ph = this.addValue(ctx, values);
         return negate ? `${operand} <> ALL(${ph})` : `${operand} = ANY(${ph})`;
     }
+    escape(value) {
+        return escapePgSqlLiteral(value);
+    }
     numericCast(expr) {
         return `(${expr})::numeric`;
     }
@@ -306,6 +311,10 @@ export class PgLikeSqlDialect extends AbstractSqlDialect {
         return this.driverCapabilities.explicitJsonCast ? `(${ph}::text)::${type}` : `${ph}::${type}`;
     }
 }
+/** A date as UTC text, which a zoneless `TIMESTAMP` stores as is, where each driver would pick its own zone. */
+function utcDate(value) {
+    return value instanceof Date ? utcTimestamp(value, PG_UTC) : value;
+}
 /**
  * Converts a JS array to a Postgres array literal string: `{"val1","val2"}`.
  * Safely handles nesting and escaping of special characters.

package/dist/maria/mariadbQuerierPool.js

@@ -9,8 +9,10 @@ export class MariadbQuerierPool extends AbstractSqlQuerierPool {
     constructor(opts, extra) {
         super(new MariaDialect(dialectOptionsFrom(extra)), extra);
         // BIGINT stays the driver's `bigint`, which `MariadbQuerier` decodes by the rule every driver here
-        // shares (`decodeWideNumber`) - not `bigIntAsNumber`, which rounds past 2^53 without a word.
-        this.pool = createPool(opts);
+        // shares (`decodeWideNumber`) - not `bigIntAsNumber`, which rounds past 2^53 without a word. A date
+        // reads as its UTC text, which hydration decodes, since the connector would take it for local time
+        // whatever `timezone` says; that only sets the session's zone, UTC, so `NOW()` agrees.
+        this.pool = createPool({ timezone: 'Z', dateStrings: true, ...opts });
         // `mariadb` fires 'error' at runtime without declaring it, hence the cast; this makes it visible.
         attachPoolErrorHandler(this.pool, 'Idle MariaDB pool connection encountered an error', extra?.logger);
     }

package/dist/migrate/builder/expressions.d.ts

@@ -13,6 +13,8 @@ export type DialectDefaults = {
     readonly expressions: SqlExpressionMap;
     /** Column types whose `DEFAULT` this engine takes only as a parenthesized expression. */
     readonly wrapTypes?: RegExp;
+    /** Column types whose `CURRENT_TIMESTAMP` default must repeat their precision, captured by the pattern. */
+    readonly preciseTypes?: RegExp;
 };
 /**
  * Looked up by name rather than carried on the dialect, which keeps DDL data out of the query

package/dist/migrate/builder/expressions.js

@@ -15,6 +15,8 @@ const MYSQL = {
 };
 /** MySQL 8.0.13+ rejects `DEFAULT 'x'` on these but accepts `DEFAULT ('x')`, whatever the value. */
 const MYSQL_LARGE_TYPES = /^\s*(TINY|MEDIUM|LONG)?(TEXT|BLOB)|^\s*(JSON|GEOMETRY)\b/i;
+/** A `DATETIME(3)` or `TIMESTAMP(3)`, whose fractional-second precision is captured. */
+const MYSQL_PRECISE_TYPES = /^\s*(?:DATETIME|TIMESTAMP)\((\d)\)/i;
 /**
  * Looked up by name rather than carried on the dialect, which keeps DDL data out of the query
  * bundle - the same split that keeps `CANONICAL_TO_SQL` in `schema/canonicalType.ts`. `uuidv7()` is
@@ -24,8 +26,12 @@ const MYSQL_LARGE_TYPES = /^\s*(TINY|MEDIUM|LONG)?(TEXT|BLOB)|^\s*(JSON|GEOMETRY
 export const DIALECT_DEFAULTS = {
     postgres: { expressions: { ...PG, uuidv7: 'uuidv7()' } },
     cockroachdb: { expressions: PG },
-    mysql: { expressions: MYSQL, wrapTypes: MYSQL_LARGE_TYPES },
-    mariadb: { expressions: { ...MYSQL, uuidv7: 'UUID_v7()' }, wrapTypes: MYSQL_LARGE_TYPES },
+    mysql: { expressions: MYSQL, wrapTypes: MYSQL_LARGE_TYPES, preciseTypes: MYSQL_PRECISE_TYPES },
+    mariadb: {
+        expressions: { ...MYSQL, uuidv7: 'UUID_v7()' },
+        wrapTypes: MYSQL_LARGE_TYPES,
+        preciseTypes: MYSQL_PRECISE_TYPES,
+    },
     sqlite: { expressions: ANSI },
     // `SYSUTCDATETIME()` over `CURRENT_TIMESTAMP`, which is local time in the server's zone. No
     // `uuidv7`: `NEWSEQUENTIALID()` is an ordered v4 GUID, so it carries no readable timestamp and
@@ -80,7 +86,7 @@ export const expr = {
  * the result needs wrapping, which MySQL demands on its large types whatever the value.
  */
 export function formatDefaultValue(value, dialect, columnType) {
-    const sql = defaultLiteral(value, dialect);
+    const sql = defaultLiteral(value, dialect, columnType);
     const { wrapTypes } = DIALECT_DEFAULTS[dialect.dialectName];
     return columnType !== undefined && wrapTypes?.test(columnType) ? `(${sql})` : sql;
 }
@@ -114,23 +120,26 @@ export function sameDefault(desired, current, dialect) {
  * cannot serve stay here: a boolean is `1` where booleans are integers, and a plain object or array
  * is JSON rather than the throw and the IN-list `escape` gives them.
  */
-function defaultLiteral(value, dialect) {
+function defaultLiteral(value, dialect, columnType) {
     if (value === undefined || value === null) {
         return 'NULL';
     }
     if (SqlExpression.isExpression(value)) {
-        return expressionSql(value, dialect);
+        return expressionSql(value, dialect, columnType);
     }
     if (typeof value === 'boolean') {
         return dialect.booleanLiteral === 'native' ? (value ? 'TRUE' : 'FALSE') : value ? '1' : '0';
     }
     return dialect.escape(typeof value === 'object' && !(value instanceof Date) ? JSON.stringify(value) : value);
 }
-function expressionSql(expression, dialect) {
-    const { expressions } = DIALECT_DEFAULTS[dialect.dialectName];
-    const sql = expression.kind === 'raw' ? expression.sql : expressions[expression.kind];
+function expressionSql(expression, dialect, columnType) {
+    const { expressions, preciseTypes } = DIALECT_DEFAULTS[dialect.dialectName];
+    const raw = expression.kind === 'raw';
+    const sql = raw ? expression.sql : expressions[expression.kind];
     if (sql == null) {
         throw new UqlUsageError(`${dialect.dialectName} has no '${expression.kind}' default; pass expr.raw(...) with SQL this engine accepts`);
     }
-    return sql;
+    // A raw default is the caller's SQL, never rewritten.
+    const precision = raw || columnType === undefined ? undefined : preciseTypes?.exec(columnType)?.[1];
+    return precision === undefined ? sql : sql.replaceAll('CURRENT_TIMESTAMP', `CURRENT_TIMESTAMP(${precision})`);
 }

package/dist/migrate/builder/tableBuilder.js

@@ -144,7 +144,7 @@ export class TableBuilder {
         return this.timestampNow('updatedAt');
     }
     timestampNow(name) {
-        return this.add(name, { category: 'timestamp' }, { defaultValue: expr.now() });
+        return this.timestamptz(name, { defaultValue: expr.now() });
     }
     timestamps() {
         this.createdAt();

package/dist/migrate/generator/mongoSchemaGenerator.d.ts

@@ -33,7 +33,7 @@ export declare class MongoSchemaGenerator extends MongoDialect implements Schema
     generateDropTable(tableName: string): string;
     /** A collection's indexes: each dropped, then each created, an alter as both. */
     generateAlterTable(diff: SchemaDiff): string[];
-    /** MongoDB has no triggers, and a write to an entity declaring one is refused, so there is none to reconcile. */
+    /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
     generateTriggers(): string[];
     generateTriggersDown(): string[];
     generateTriggerDrops(): string[];

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -115,7 +115,7 @@ export class MongoSchemaGenerator extends MongoDialect {
             ...sides(diff.indexes, 'to').map((index) => this.generateCreateIndex(diff.tableName, index)),
         ];
     }
-    /** MongoDB has no triggers, and a write to an entity declaring one is refused, so there is none to reconcile. */
+    /** MongoDB runs no trigger within a write, and a write to an entity declaring one is refused, so there is none to reconcile. */
     generateTriggers() {
         return [];
     }

package/dist/migrate/introspection/mongoIntrospector.d.ts

@@ -10,7 +10,7 @@ export declare class MongoSchemaIntrospector implements SchemaIntrospector {
     /** `listIndexes` reports keys, uniqueness and text weights; a `partialFilterExpression` is no SQL predicate. */
     readonly indexFacets: ReadonlySet<IndexFacet>;
     constructor(pool: QuerierPool);
-    /** MongoDB has no triggers, so none is ever installed. */
+    /** MongoDB runs no trigger within a write, so uql installs none. */
     ownedTriggers(): Promise<InstalledTriggers>;
     introspect(tables?: readonly string[]): Promise<SchemaAST>;
     getTableSchema(tableName: string): Promise<TableSchema | undefined>;

package/dist/migrate/introspection/mongoIntrospector.js

@@ -15,7 +15,7 @@ export class MongoSchemaIntrospector {
     constructor(pool) {
         this.pool = pool;
     }
-    /** MongoDB has no triggers, so none is ever installed. */
+    /** MongoDB runs no trigger within a write, so uql installs none. */
     async ownedTriggers() {
         return new Map();
     }

package/dist/migrate/introspection/mssqlIntrospector.js

@@ -1,3 +1,4 @@
+import { defaultTimestampPrecision } from '../../schema/canonicalType.js';
 import { AbstractSqlSchemaIntrospector, } from './abstractSqlSchemaIntrospector.js';
 /**
  * SQL Server schema introspector.
@@ -137,7 +138,7 @@ export class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             const bytes = this.toNumber(row.max_length);
             return {
                 name: row.column_name,
-                type: bytes === -1 && CHARACTER_TYPES.has(type) ? `${type}(MAX)` : type,
+                type: spelledType(type, bytes, this.toNumber(row.numeric_scale)),
                 nullable: Boolean(row.is_nullable),
                 defaultValue: this.parseDefaultValue(row.column_default),
                 isAutoIncrement: Boolean(row.is_identity),
@@ -183,6 +184,17 @@ export class MsSqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
 /** The types whose `max_length` is a width rather than a fixed storage size. */
 const CHARACTER_TYPES = new Set(['CHAR', 'NCHAR', 'VARCHAR', 'NVARCHAR', 'BINARY', 'VARBINARY']);
 const NUMERIC_TYPES = new Set(['DECIMAL', 'NUMERIC']);
+/** `(MAX)` on an unbounded character type, and a timestamp's fractional digits where not the engine's default. */
+function spelledType(type, bytes, scale) {
+    if (bytes === -1 && CHARACTER_TYPES.has(type)) {
+        return `${type}(MAX)`;
+    }
+    return (type === 'DATETIME2' || type === 'DATETIMEOFFSET') &&
+        scale !== undefined &&
+        scale !== defaultTimestampPrecision('mssql')
+        ? `${type}(${scale})`
+        : type;
+}
 /**
  * A column's declared width from `max_length`, which is bytes: an `N` type holds two a character, a
  * `VECTOR` is an 8-byte header and four a dimension, and `MAX` is `-1`. Read as bytes, every Unicode

package/dist/migrate/introspection/mysqlIntrospector.d.ts

@@ -29,6 +29,7 @@ export declare class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospect
 }
 type MysqlColumnRow = {
     column_name: string;
+    data_type: string;
     column_type: string;
     is_nullable: string;
     column_default: string | null;
@@ -36,6 +37,7 @@ type MysqlColumnRow = {
     extra: string;
     character_maximum_length: number | bigint | null;
     numeric_precision: number | bigint | null;
+    datetime_precision: number | bigint | null;
     numeric_scale: number | null;
     column_comment: string | null;
     generated_as: string | null;

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -47,6 +47,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         CHARACTER_MAXIMUM_LENGTH as character_maximum_length,
         NUMERIC_PRECISION as numeric_precision,
         NUMERIC_SCALE as numeric_scale,
+        DATETIME_PRECISION as datetime_precision,
         COLUMN_KEY as column_key,
         EXTRA as extra,
         CASE WHEN EXTRA LIKE '%STORED GENERATED%' THEN GENERATION_EXPRESSION END as generated_as,
@@ -113,7 +114,8 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             isUnique: row.column_key === 'UNI',
             // A `VECTOR`'s is its bytes, four a dimension, which `column_type` already states as dimensions.
             length: /^vector/i.test(row.column_type) ? undefined : this.toNumber(row.character_maximum_length),
-            precision: this.toNumber(row.numeric_precision),
+            // A timestamp's fractional digits, stated even when 0, which uql's own unstated `DATETIME(3)` is not.
+            precision: this.toNumber(TIMESTAMP_TYPES.has(row.data_type) ? row.datetime_precision : row.numeric_precision),
             scale: this.toNumber(row.numeric_scale),
             comment: row.column_comment || undefined,
             generatedAs: row.generated_as ?? undefined,
@@ -146,7 +148,8 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         if (normalized === 'NULL') {
             return null;
         }
-        if (normalized === 'CURRENT_TIMESTAMP' || normalized === 'CURRENT_TIMESTAMP()') {
+        // Whatever precision it repeats from its column, which the column's own type already states.
+        if (/^CURRENT_TIMESTAMP(?:\(\d?\))?$/.test(normalized)) {
             return 'CURRENT_TIMESTAMP';
         }
         if (/^-?\d+(\.\d+)?$/.test(defaultValue)) {
@@ -158,6 +161,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return quoted ? unescapeMysqlString(quoted[1]) : literal;
     }
 }
+const TIMESTAMP_TYPES = new Set(['datetime', 'timestamp']);
 /**
  * MariaDB reads out of the same `information_schema` as MySQL, save for one column type it does not
  * have: `JSON` there is an alias for `LONGTEXT` plus a `json_valid()` check constraint named after

package/dist/migrate/introspection/postgresIntrospector.js

@@ -75,7 +75,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         c.is_identity,
         c.identity_generation,
         CASE WHEN a.attgenerated = 's' THEN c.generation_expression END AS generated_as,
-        CASE WHEN c.data_type IN ('USER-DEFINED', 'vector') AND a.atttypmod > -1
+        CASE WHEN (c.data_type IN ('USER-DEFINED', 'vector') OR c.data_type LIKE 'timestamp%') AND a.atttypmod > -1
           THEN format_type(a.atttypid, a.atttypmod) END AS formatted_type,
         EXISTS (
           SELECT 1 FROM information_schema.table_constraints tc

package/dist/migrate/storage/databaseStorage.js

@@ -32,7 +32,7 @@ export class DatabaseMigrationStorage {
     async createTableIfNotExists(querier) {
         const table = new TableBuilder(this.tableName);
         table.string('name', { length: 255, primaryKey: true });
-        table.timestamp('executed_at', { defaultValue: expr.now() });
+        table.timestamptz('executed_at', { defaultValue: expr.now() });
         const generator = new SqlSchemaGenerator(querier.dialect);
         for (const sql of generator.generateCreateTableFromDefinition(table.build(), { ifNotExists: true })) {
             await querier.run(sql);

package/dist/mongo/mongodbQuerier.js

@@ -13,12 +13,13 @@ function asksForNoRows(q) {
     return q.$limit === 0;
 }
 /**
- * MongoDB has no triggers, so a write to an entity declaring one - a stamp included - would skip it
- * silently. Refused instead, as a query naming SQL is.
+ * MongoDB runs no trigger within a write (Atlas Database Triggers fire after the commit), so a write to
+ * an entity declaring one - a stamp included - would skip it silently. Refused instead, as a query naming
+ * SQL is. The why, in `architecture/triggers.md`.
  */
 function refuseTriggers(entity) {
     if (hasTriggers(getMeta(entity))) {
-        throw new UqlUsageError(`'${entity.name}' declares triggers, which MongoDB has none of: a write here would skip them. ` +
+        throw new UqlUsageError(`'${entity.name}' declares triggers, which MongoDB cannot run within a write: a write here would skip them. ` +
             'Keep the entity on a SQL engine, or drop its triggers and stamps.');
     }
 }

package/dist/mssql/mssqlQuerier.d.ts

@@ -1,3 +1,4 @@
+import { DateTime2 } from 'mssql';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import type { QueryUpdateResult, RawRow, TransactionOptions } from '../type/index.js';
 /** What `tedious` hands back for one statement, whichever shape it took. */
@@ -17,6 +18,7 @@ type MsSqlRowStream = AsyncIterable<unknown> & {
 /** The part of an `mssql` `Request` a querier drives. */
 type MsSqlRequest = {
     input(name: string, value: unknown): unknown;
+    input(name: string, type: typeof DateTime2, value: unknown): unknown;
     query(command: string): Promise<MsSqlResult>;
     toReadableStream(): MsSqlRowStream;
     cancel(): unknown;

package/dist/mssql/mssqlQuerier.js

@@ -1,4 +1,4 @@
-import { ISOLATION_LEVEL } from 'mssql';
+import { DateTime2, ISOLATION_LEVEL } from 'mssql';
 import { AbstractPoolQuerier } from '../querier/abstractPoolQuerier.js';
 import { decodeWireTypes } from './mssqlWireTypes.js';
 /**
@@ -9,13 +9,16 @@ import { decodeWireTypes } from './mssqlWireTypes.js';
 export class MsSqlQuerier extends AbstractPoolQuerier {
     #transaction;
     /**
-     * Values bind by name, `@p1` upward, matching {@link MsSqlDialect.placeholder}. `tedious` infers
-     * a type from the JS value, which is why a `Date` and a `Uint8Array` reach it unconverted - the
-     * inference is right for both, and wrong only for a bare `null`, which it calls `NVarChar`.
+     * Values bind by name, `@p1` upward, matching {@link MsSqlDialect.placeholder}. `mssql` infers a type
+     * from the JS value, right for a `Uint8Array` and harmlessly wrong for a bare `null` (`NVarChar`), but
+     * a `Date` it binds as the legacy `DATETIME`, whose 1/300 s steps no `DATETIME2` column compares equal to.
      */
     #request(values) {
         const request = this.#transaction ? this.#transaction.request() : this.getConn().request();
-        values?.forEach((value, index) => request.input(`p${index + 1}`, value));
+        values?.forEach((value, index) => {
+            const name = `p${index + 1}`;
+            return value instanceof Date ? request.input(name, DateTime2, value) : request.input(name, value);
+        });
         return request;
     }
     async internalAll(query, values) {

package/dist/mysql/mysql2QuerierPool.d.ts

@@ -4,6 +4,7 @@ import type { ExtraOptions } from '../type/index.js';
 import { MySql2Querier } from './mysql2Querier.js';
 import { MySqlDialect } from './mysqlDialect.js';
 export declare class MySql2QuerierPool extends AbstractSqlQuerierPool<MySql2Querier, MySqlDialect> {
+    #private;
     readonly pool: Pool;
     constructor(opts: PoolOptions, extra?: ExtraOptions);
     getQuerier(): Promise<MySql2Querier>;

package/dist/mysql/mysql2QuerierPool.js

@@ -5,14 +5,32 @@ import { MySql2Querier } from './mysql2Querier.js';
 import { MySqlDialect } from './mysqlDialect.js';
 export class MySql2QuerierPool extends AbstractSqlQuerierPool {
     pool;
+    #utcSessions = new WeakSet();
     constructor(opts, extra) {
         super(new MySqlDialect(dialectOptionsFrom(extra)), extra);
         // A BIGINT past 2^53 as its exact text rather than a rounded number, the rule every driver here
         // decodes by (`decodeWideNumber`); within that range it stays a number, and DECIMAL is untouched.
-        this.pool = createPool({ supportBigNumbers: true, ...opts });
+        // A date reads as the UTC it holds, whichever zone the process runs in.
+        this.pool = createPool({ supportBigNumbers: true, timezone: 'Z', ...opts });
     }
     async getQuerier() {
-        return new MySql2Querier(() => this.pool.getConnection(), this.dialect, this.extra);
+        return new MySql2Querier(() => this.#connection(), this.dialect, this.extra);
+    }
+    /** A connection whose session is UTC too, so `NOW()` agrees with a bound date: set once per connection. */
+    async #connection() {
+        const connection = await this.pool.getConnection();
+        if (this.#utcSessions.has(connection.connection)) {
+            return connection;
+        }
+        try {
+            await connection.query("SET time_zone = '+00:00'");
+        }
+        catch (error) {
+            connection.release();
+            throw error;
+        }
+        this.#utcSessions.add(connection.connection);
+        return connection;
     }
     async end() {
         await this.pool.end();

package/dist/neon/neonQuerierPool.js

@@ -1,11 +1,11 @@
 import { Pool, types } from '@neondatabase/serverless';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
-import { numericTypes } from '../postgres/pgNumericTypes.js';
+import { wireTypes } from '../postgres/pgWireTypes.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
 export class NeonQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // Neon's own `types`, not `pg`'s: this entry has to load on an edge runtime where `pg` is absent.
-        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ types: numericTypes(types), ...opts }), extra);
+        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ types: wireTypes(types), ...opts }), extra);
     }
 }

package/dist/pglite/pgliteQuerierPool.js

@@ -1,6 +1,7 @@
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { PostgresDialect } from '../postgres/postgresDialect.js';
 import { AbstractSharedHandleQuerierPool } from '../querier/abstractSharedHandleQuerierPool.js';
+import { decodeDate } from '../util/date.js';
 import { decodeWideNumber } from '../util/wideNumber.js';
 import { PgliteQuerier } from './pgliteQuerier.js';
 /**
@@ -18,12 +19,17 @@ export class PgliteQuerierPool extends AbstractSharedHandleQuerierPool {
     }
     async openDb() {
         const { PGlite, types } = await import('@electric-sql/pglite');
-        // INT8 by the one wide-integer rule, where PGlite's own answers a `bigint` past 2^53; a caller's own
-        // `parsers` still win. The declared return type is what checks {@link PgliteDatabase} against the
-        // real driver, so no cast is needed here or anywhere below it.
+        // INT8 by the one wide-integer rule, where PGlite's own answers a `bigint` past 2^53, and a zoneless
+        // TIMESTAMP or a DATE as UTC, as every pool reads one; a caller's own `parsers` still win. The declared
+        // return type is what checks {@link PgliteDatabase} against the real driver, so no cast is needed below it.
         return PGlite.create(this.dataDir, {
             ...this.opts,
-            parsers: { [types.INT8]: decodeWideNumber, ...this.opts?.parsers },
+            parsers: {
+                [types.INT8]: decodeWideNumber,
+                [types.TIMESTAMP]: decodeDate,
+                [types.DATE]: decodeDate,
+                ...this.opts?.parsers,
+            },
         });
     }
     buildQuerier(db) {

package/dist/postgres/pgQuerierPool.js

@@ -1,12 +1,12 @@
 import { Pool, types } from 'pg';
 import { dialectOptionsFrom } from '../dialect/abstractDialect.js';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
-import { numericTypes } from './pgNumericTypes.js';
+import { wireTypes } from './pgWireTypes.js';
 import { PostgresDialect } from './postgresDialect.js';
 export class PgQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // keepAlive reduces (but can't eliminate) idle connections being silently
         // dropped by NATs/firewalls on long-lived remote connections.
-        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
+        super(new PostgresDialect(dialectOptionsFrom(extra)), new Pool({ keepAlive: true, types: wireTypes(types), ...opts }), extra);
     }
 }

package/dist/postgres/{pgNumericTypes.d.ts → pgWireTypes.d.ts}

@@ -11,8 +11,9 @@ type PgTypes = {
 };
 /**
  * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
- * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
- * Per pool, never a global parser, and a caller's own `types` win.
+ * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
+ * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
+ * never a global parser, and a caller's own `types` win.
  */
-export declare function numericTypes(types: PgTypes): CustomTypesConfig;
+export declare function wireTypes(types: PgTypes): CustomTypesConfig;
 export {};

package/dist/postgres/{pgNumericTypes.js → pgWireTypes.js}

@@ -1,14 +1,18 @@
+import { decodeDate } from '../util/date.js';
 import { decodeWideNumber } from '../util/wideNumber.js';
 /**
  * Decodes `INT8` by `decodeWideNumber` and `FLOAT8` as the float64 it is, since `type: Number` maps to
- * BIGINT. At the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field.
- * Per pool, never a global parser, and a caller's own `types` win.
+ * BIGINT, and a zoneless `TIMESTAMP` or a `DATE` as UTC, where `pg` reads both in the process's zone. At
+ * the wire, which every result crosses; `NUMERIC` is left to hydration, which knows the field. Per pool,
+ * never a global parser, and a caller's own `types` win.
  */
-export function numericTypes(types) {
+export function wireTypes(types) {
     // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
     const decoders = new Map([
         [types.builtins['INT8'], decodeWideNumber],
         [types.builtins['FLOAT8'], Number],
+        [types.builtins['TIMESTAMP'], decodeDate],
+        [types.builtins['DATE'], decodeDate],
     ]);
     return {
         getTypeParser: (oid, format) => (format === 'text' && decoders.get(oid)) || types.getTypeParser(oid, format),

package/dist/schema/canonicalType.d.ts

@@ -1,6 +1,7 @@
 import type { AbstractDialect } from '../dialect/abstractDialect.js';
 import type { VectorCast } from '../dialect/vectorCast.js';
 import type { ColumnType, EntityGetter, FieldMeta, FieldOptions } from '../type/entity.js';
+import { type DialectName } from '../type/index.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;
@@ -29,6 +30,8 @@ export declare function canonicalToSql(type: CanonicalType, dialect: AbstractDia
  * Convert a canonical type to a TypeScript type string.
  */
 export declare function canonicalToTypeScript(type: CanonicalType): string;
+/** The fractional-second digits an engine's timestamp holds when its type states none; `undefined` where it counts none. */
+export declare function defaultTimestampPrecision(dialectName: DialectName): number | undefined;
 /**
  * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
  * the engine settles an unstated bound. Migrations and drift both compare through it.

package/dist/schema/canonicalType.js

@@ -120,7 +120,8 @@ const MYSQL_SCALAR_MAP = {
     boolean: 'TINYINT(1)',
     date: 'DATE',
     time: 'TIME',
-    timestamp: 'DATETIME',
+    // The milliseconds a `Date` holds, which a bare `DATETIME` rounds away.
+    timestamp: 'DATETIME(3)',
     json: 'JSON',
     uuid: 'CHAR(36)',
     blob: 'BLOB',
@@ -193,25 +194,28 @@ const ENGINE_TYPES = {
     postgres: {
         scalars: { ...PG_SCALAR_MAP, vector: 'VECTOR', halfvec: 'HALFVEC', sparsevec: 'SPARSEVEC' },
         sizes: PG_SIZES,
+        timestampPrecision: 6,
     },
     // CockroachDB's VECTOR is native, no extension needed.
-    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES },
+    cockroachdb: { scalars: withVectorType(PG_SCALAR_MAP, 'VECTOR'), sizes: PG_SIZES, timestampPrecision: 6 },
     // MySQL does have a `VECTOR` type (26.7), but no distance function outside HeatWave and no vector
     // index, so JSON keeps the column queryable with the JSON operators and needs no conversion.
     mysql: {
         scalars: withVectorType(MYSQL_SCALAR_MAP, 'JSON'),
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
+        timestampPrecision: 0,
     },
     mariadb: {
         scalars: withVectorType(MYSQL_SCALAR_MAP, 'VECTOR'),
         sizes: MYSQL_SIZES,
         decimal: { precision: 10, scale: 2 },
+        timestampPrecision: 0,
     },
     // SQLite uses affinity, so no size variants. `F32_BLOB` is libSQL's vector type; elsewhere just a name of BLOB affinity.
     sqlite: { scalars: withVectorType(SQLITE_SCALAR_MAP, 'F32_BLOB') },
     // 2025 and up; below that the server refuses the type rather than storing it as text.
-    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES },
+    mssql: { scalars: withVectorType(MSSQL_SCALAR_MAP, 'VECTOR'), sizes: MSSQL_SIZES, timestampPrecision: 7 },
     mongodb: { scalars: withVectorType(MONGO_SCALAR_MAP, 'array') },
 };
 /**
@@ -241,8 +245,11 @@ export function sqlToCanonical(sqlType) {
     const normalized = sqlType.toLowerCase().trim();
     const unsigned = normalized.includes('unsigned');
     const withoutUnsigned = normalized.replace(/\s*unsigned\s*/i, ' ').trim();
-    // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"]
-    const match = withoutUnsigned.match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
+    // Extract base type and parameters: "VARCHAR(255)" -> ["varchar", "255"], and Postgres's
+    // "timestamp(3) with time zone", whose parameter sits inside the name, as "timestamp with time zone(3)".
+    const match = withoutUnsigned
+        .replace(/^(\w+)\((\d+)\)\s+(.+)$/, '$1 $3($2)')
+        .match(/^([a-z][a-z0-9_ ]*?)(?:\(([^)]+)\))?$/);
     const base = match ? SQL_TO_CANONICAL[match[1]] : undefined;
     if (!match || !base) {
         return { category: 'string', raw: sqlType };
@@ -260,7 +267,7 @@ export function sqlToCanonical(sqlType) {
         size: measured && params[0] === 'max' ? 'small' : base.size,
         withTimezone: base.withTimezone,
         length: measured ? first : undefined,
-        precision: decimal ? first : undefined,
+        precision: decimal || base.category === 'timestamp' ? first : undefined,
         scale: decimal ? second : undefined,
         unsigned: unsigned || undefined,
     };
@@ -317,6 +324,9 @@ export function canonicalToSql(type, dialect) {
     if (type.category === 'timestamp' && type.withTimezone && features.supportsTimestamptz) {
         sqlType = 'TIMESTAMPTZ';
     }
+    if (type.category === 'timestamp' && type.precision !== undefined && engine.timestampPrecision !== undefined) {
+        sqlType = `${sqlType.replace(/\(\d+\)$/, '')}(${type.precision})`;
+    }
     return type.unsigned && features.supportsUnsigned ? `${sqlType} UNSIGNED` : sqlType;
 }
 /** See {@link DialectFeatures.stringSizing} for what each mode means. */
@@ -343,12 +353,22 @@ function formatDecimalSqlType(type, fallback, baseType) {
 export function canonicalToTypeScript(type) {
     return CANONICAL_TO_TS[type.category];
 }
+/** The fractional-second digits an engine's timestamp holds when its type states none; `undefined` where it counts none. */
+export function defaultTimestampPrecision(dialectName) {
+    return ENGINE_TYPES[dialectName].timestampPrecision;
+}
 /**
  * A type as `dialect` stores it, rendered and read back: several types share one storage type, and only
  * the engine settles an unstated bound. Migrations and drift both compare through it.
  */
 export function engineType(dialect) {
-    return (type) => sqlToCanonical(canonicalToSql(type, dialect));
+    const timestampPrecision = defaultTimestampPrecision(dialect.dialectName);
+    return (type) => {
+        const stored = sqlToCanonical(canonicalToSql(type, dialect));
+        return stored.category === 'timestamp' && stored.precision === undefined
+            ? { ...stored, precision: timestampPrecision }
+            : stored;
+    };
 }
 /**
  * Convert UQL FieldOptions to a canonical type.
@@ -363,14 +383,16 @@ export function fieldOptionsToCanonical(options) {
     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`).
+            // to happen, and the pools decode it back to a JS number at the wire (see `pgWireTypes`).
             return isIntegerColumn(options)
                 ? { category: 'integer', size: 'big' }
                 : { category: 'decimal', precision: options.precision, scale: options.scale };
         case 'boolean':
             return { category: 'boolean' };
+        // An instant: uql reads a zoneless timestamp as UTC, but the database's own clock and every other
+        // client read one in the session's zone.
         case 'date':
-            return { category: 'timestamp' };
+            return { category: 'timestamp', withTimezone: true, precision: options.precision };
         // `String`, and anything a reflected type left unrecognised.
         default:
             return { category: 'string', length: options.length };

package/dist/schema/schemaASTDiffer.js

@@ -124,7 +124,9 @@ function diffColumn(tableName, source, target, opts) {
     // inconsistently (`BIGINT(20)`, SQLite's `notnull: 0` rowid), so neither is compared.
     const generatedType = source.isAutoIncrement && target.isAutoIncrement;
     const impliedNotNull = source.isPrimaryKey && target.isPrimaryKey;
-    const typeChanged = !generatedType && !areTypesEqual(opts.normalizeType(source.type), opts.normalizeType(target.type));
+    const expectedType = opts.normalizeType(source.type);
+    const actualType = opts.normalizeType(target.type);
+    const typeChanged = !generatedType && !areTypesEqual(expectedType, actualType);
     if (typeChanged) {
         differences.push(`type: ${formatType(source.type)} -> ${formatType(target.type)}`);
     }
@@ -158,7 +160,7 @@ function diffColumn(tableName, source, target, opts) {
         // Only the type this diff actually reports: a column altered for its default carries no data loss,
         // and a generated key's type - never compared above - reads as unsigned against an entity that
         // cannot say so.
-        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(target.type, source.type),
+        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(actualType, expectedType),
         description: differences.join(', '),
     };
 }

package/dist/sqlite/sqliteDialect.d.ts

@@ -1,4 +1,4 @@
-import { AbstractSqlDialect, type DerivedRelation, type HydrateKind, type RelationRows } from '../dialect/abstractSqlDialect.js';
+import { AbstractSqlDialect, type DerivedRelation, type RelationRows } from '../dialect/abstractSqlDialect.js';
 import { type JsonAccessMode, type JsonSlot } from '../dialect/jsonSql.js';
 import { type EntityMeta, type FieldOptions, type Query, type QueryContext, type QueryPager, type QueryTextSearchOptions, type QueryWhere, type SqlDialectFeatures, type VectorDistance, type VectorMetric } from '../type/index.js';
 /** What SQLite and the engines derived from it have. */
@@ -60,8 +60,6 @@ export declare class SqliteDialect extends AbstractSqlDialect {
         vector: (expr: string) => string;
     };
     private bytesAsText;
-    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
-    protected hydrateKind(field: FieldOptions | undefined): HydrateKind | undefined;
     /**
      * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
      * not create those; declare it outside your entities). The whole query is bound, column filter and all.

package/dist/sqlite/sqliteDialect.js

@@ -3,9 +3,10 @@ import { BYTES_PREFIX } from '../dialect/hydrateColumn.js';
 import { chainedCall, groupsPerCall, jsonSetCall, jsonPath, jsonArraySlotArgs, jsonSlotArgs, jsonRemoveCall, jsonSetTarget, } from '../dialect/jsonSql.js';
 import { QueryRaw, } from '../type/index.js';
 import { indexDistance, isVectorIndexType } from '../type/vector.js';
+import { utcTimestamp } from '../util/date.js';
 import { declaredIndexName } from '../util/ddlExpression.util.js';
 import { findVectorIndex, findVectorSort, textSearchFields, vectorCandidates } from '../util/dialect.util.js';
-import { columnFamily, isIntegerColumn } from '../util/field.util.js';
+import { isIntegerColumn } from '../util/field.util.js';
 /**
  * An FTS5 query over `columns` for what a person typed: each word a quoted string, which FTS5 reads as a
  * term to match and never as syntax, and every one required, as the other engines read plain words.
@@ -128,7 +129,7 @@ export class SqliteDialect extends AbstractSqlDialect {
     }
     normalizeValue(value) {
         if (value instanceof Date)
-            return value.getTime();
+            return utcTimestamp(value);
         return super.normalizeValue(value);
     }
     /**
@@ -169,10 +170,6 @@ export class SqliteDialect extends AbstractSqlDialect {
     bytesAsText(expr) {
         return `${this.escape(BYTES_PREFIX)} || hex(${expr})`;
     }
-    /** A date reads back as SQLite stored it, a number or text, which JSON carries unchanged. */
-    hydrateKind(field) {
-        return columnFamily(field?.type) === 'date' ? undefined : super.hydrateKind(field);
-    }
     /**
      * FTS5 matches the table itself, so this works only where the table *is* an FTS5 virtual table (UQL does
      * not create those; declare it outside your entities). The whole query is bound, column filter and all.

package/dist/type/entity.d.ts

@@ -288,7 +288,7 @@ export type FieldOptions<V = TsTypeOf<FieldType>, E = unknown> = {
     readonly columnType?: ColumnType | QueryRaw;
     /** A string column's length. */
     readonly length?: number;
-    /** A decimal column's precision. */
+    /** A decimal column's digits, or a timestamp's fractional-second digits. */
     readonly precision?: number;
     /** A decimal column's scale. */
     readonly scale?: number;

package/dist/util/date.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, then `zone`: how a date is written, whichever machine writes it. Not
+ * `toISOString` as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
+ */
+export declare function utcTimestamp(date: Date, zone?: string): string;
+/**
+ * A timestamp's text as the `Date` it names, the one rule every driver and hydration read dates by: UTC
+ * where it names no zone, its own offset where it does, a bare day at UTC midnight, and the fraction cut
+ * to the milliseconds a `Date` holds. Text that is none of these, such as `infinity`, stays text.
+ */
+export declare function decodeDate(text: string): Date | string;

package/dist/util/date.js

@@ -0,0 +1,19 @@
+/**
+ * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, then `zone`: how a date is written, whichever machine writes it. Not
+ * `toISOString` as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
+ */
+export function utcTimestamp(date, zone = '') {
+    return date.toISOString().replace('T', ' ').replace('Z', zone);
+}
+/** A time of day that names no zone, which `Date` would read in the process's own. */
+const ZONELESS_TIME = /T[\d:.]+$/;
+/**
+ * A timestamp's text as the `Date` it names, the one rule every driver and hydration read dates by: UTC
+ * where it names no zone, its own offset where it does, a bare day at UTC midnight, and the fraction cut
+ * to the milliseconds a `Date` holds. Text that is none of these, such as `infinity`, stays text.
+ */
+export function decodeDate(text) {
+    const iso = text.replace(' ', 'T').replace(/(\.\d{3})\d+/, '$1');
+    const date = new Date(ZONELESS_TIME.test(iso) ? `${iso}Z` : iso);
+    return Number.isNaN(date.getTime()) ? text : date;
+}

package/dist/util/fieldOption.util.d.ts

@@ -1,6 +1,6 @@
 import { type ColumnFamily, type FamilyOf, type FieldOptions, QueryRaw, type StampEvent } from '../type/index.js';
 /**
- * The column family each field option means anything on, or `'*'` where it applies to every column.
+ * The column families each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
  * discipline `INDEX_FEATURE_LABELS` uses for index features.
  */
@@ -23,7 +23,7 @@ declare const FIELD_OPTION_FAMILY: {
     readonly version: 'numeric';
     readonly columnType: '*';
     readonly length: 'string';
-    readonly precision: 'numeric';
+    readonly precision: readonly ["numeric", "date"];
     readonly scale: 'numeric';
     readonly nullable: '*';
     readonly unique: '*';
@@ -91,8 +91,10 @@ type DeadOptions<O> = (O extends {
     readonly nullable: true;
 } ? 'nullable' : never);
 type Given<O> = Extract<keyof O, keyof FieldOptions>;
+/** The families option `K` applies to, `'*'` for every one. */
+type OptionFamilies<K extends keyof FieldOptions> = (typeof FIELD_OPTION_FAMILY)[K] extends readonly (infer F)[] ? F : (typeof FIELD_OPTION_FAMILY)[K];
 type Offending<O> = {
-    [K in Given<O>]: (typeof FIELD_OPTION_FAMILY)[K] extends OptionsFamily<O> | '*' ? K extends DeadOptions<O> ? K : never : K;
+    [K in Given<O>]: [Extract<OptionFamilies<K>, OptionsFamily<O> | '*'>] extends [never] ? K : K extends DeadOptions<O> ? K : never;
 }[Given<O>];
 /**
  * Every option `O` states but cannot use, mapped to `never`, so one that would be ignored does not compile.

package/dist/util/fieldOption.util.js

@@ -3,7 +3,7 @@ import { columnFamily, isInlinedExpression } from './field.util.js';
 import { getKeys } from './object.util.js';
 import { constantSql } from './raw.js';
 /**
- * The column family each field option means anything on, or `'*'` where it applies to every column.
+ * The column families each field option means anything on, or `'*'` where it applies to every column.
  * Exhaustive over {@link FieldOptions}, so a new option cannot be added without placing it - the
  * discipline `INDEX_FEATURE_LABELS` uses for index features.
  */
@@ -26,7 +26,8 @@ const FIELD_OPTION_FAMILY = {
     version: 'numeric',
     columnType: '*',
     length: 'string',
-    precision: 'numeric',
+    // A decimal's digits, or a timestamp's fractional-second digits.
+    precision: ['numeric', 'date'],
     scale: 'numeric',
     nullable: '*',
     unique: '*',
@@ -116,11 +117,11 @@ export function fieldOptionConflict(opts) {
     // conflicts always reports the same one. An option no rule knows is a typo, which `@Field`'s own check
     // reports where it can still be spelled right.
     for (const key of getKeys(FIELD_OPTION_FAMILY)) {
-        const applies = FIELD_OPTION_FAMILY[key];
+        const applies = [FIELD_OPTION_FAMILY[key]].flat();
         if (opts[key] === undefined)
             continue;
-        if (family && applies !== '*' && applies !== family) {
-            return `cannot use '${key}': it applies to a ${applies} column, not to a ${family} one`;
+        if (family && !applies.includes('*') && !applies.includes(family)) {
+            return `cannot use '${key}': it applies to a ${applies.join(' or ')} column, not to a ${family} one`;
         }
         const dead = deadOn(opts, key);
         if (dead) {

package/dist/util/sqlLiteral.d.ts

@@ -2,7 +2,14 @@
 export declare function escapeSingleQuotes(val: string): string;
 /** The text a MySQL string literal's body stands for: its backslash escapes and doubled quotes undone. */
 export declare function unescapeMysqlString(body: string): string;
-/** Escape `value` for Postgres, SQLite and related dialects (single-quote doubling). */
+/** How a Postgres timestamp says it is UTC. */
+export declare const PG_UTC = "+00";
+/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
 export declare const escapeAnsiSqlLiteral: (value: unknown) => string;
+/**
+ * Escape `value` for the Postgres family: ANSI, a date marked UTC, which a `TIMESTAMPTZ` otherwise reads
+ * in the session's zone.
+ */
+export declare const escapePgSqlLiteral: (value: unknown) => string;
 /** Escape `value` for MySQL and MariaDB (backslash escaping). */
 export declare const escapeMysqlSqlLiteral: (value: unknown) => string;

package/dist/util/sqlLiteral.js

@@ -1,6 +1,7 @@
 // SQL literal escaping for `Dialect.escape`: ANSI quote doubling, or MySQL's backslashes. UQL binds
 // values instead, so this is the hand-written-SQL hatch, and inline MySQL literals break under
 // `NO_BACKSLASH_ESCAPES` or a GBK-like charset: prefer bound parameters. Postgres arrays are separate.
+import { utcTimestamp } from './date.js';
 import { UqlUsageError } from './uqlError.js';
 const SINGLE_QUOTE = /'/g;
 /** Doubles every single quote in `val`, the ANSI escaping shared by string literals and JSON path keys. */
@@ -43,12 +44,8 @@ function bytesToHexLiteral(bytes) {
  * A factory, not a function taking `escapeString` as an argument: threading it through every call
  * measured 1.1-1.5x slower. Rejects unsupported types rather than stringifying them into SQL.
  */
-function createEscaper(escapeString) {
-    /**
-     * `YYYY-MM-DD HH:mm:ss.SSS` in UTC, so the SQL is the same whichever machine wrote it. Not `toISOString`
-     * as it is, whose `T` and `Z` MySQL rejects outright ("Invalid default value").
-     */
-    const dateLiteral = (date) => escapeString(date.toISOString().replace('T', ' ').replace('Z', ''));
+function createEscaper(escapeString, zone = '') {
+    const dateLiteral = (date) => escapeString(utcTimestamp(date, zone));
     const sqlList = (arr) => {
         let sql = '';
         for (let i = 0; i < arr.length; i++) {
@@ -98,7 +95,14 @@ function createEscaper(escapeString) {
     };
     return escapeValue;
 }
-/** Escape `value` for Postgres, SQLite and related dialects (single-quote doubling). */
+/** How a Postgres timestamp says it is UTC. */
+export const PG_UTC = '+00';
+/** Escape `value` for SQLite and SQL Server (single-quote doubling). */
 export const escapeAnsiSqlLiteral = createEscaper(ansiStringLiteral);
+/**
+ * Escape `value` for the Postgres family: ANSI, a date marked UTC, which a `TIMESTAMPTZ` otherwise reads
+ * in the session's zone.
+ */
+export const escapePgSqlLiteral = createEscaper(ansiStringLiteral, PG_UTC);
 /** Escape `value` for MySQL and MariaDB (backslash escaping). */
 export const escapeMysqlSqlLiteral = createEscaper(mysqlStringLiteral);

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -74,7 +74,7 @@ export class Post {
 }
 ```
 
-- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date`, `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
+- Every `@Field` states its `type` (`String`, `Number`, `Boolean`, `Date` (an instant, bound and read as UTC on every engine; `TIMESTAMPTZ` on Postgres and CockroachDB, `DATETIME(3)` on MySQL and MariaDB; `precision` sets its fractional-second digits), `BigInt`, or a column type such as `'uuid'`, `'text'`, `'jsonb'`), except a foreign key, which takes `references` and inherits the target key's type.
 - A column is nullable unless it says `nullable: false`, and its property must admit `null` to match: `title?: string | null`. A property typed without `| null` on a nullable column is a compile error.
 - An engine's own column type is a `raw` constant, ``columnType: raw`tsvector` ``, rendered verbatim and carrying its own `length`/`precision`: never a bare string.
 - Members are named by callbacks, never by strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`.