uql-orm 0.86.0 → 0.88.0

package/dist/migrate/triggerSql.js

@@ -53,8 +53,9 @@ function triggerStatements(dialect, meta, trigger, name) {
     const table = dialect.escapedTableName(meta);
     const names = rowNames(dialect);
     const rows = [rowRefs(meta.entity, names.$new), rowRefs(meta.entity, names.$old)];
-    const sql = dialect.compileDdl(body(...rows), meta.entity, { rows: rowsFrom(dialect, meta, operation) });
-    const guard = triggerGuard(dialect, meta, trigger, rows, names);
+    const source = rowsFrom(dialect, meta, operation, trigger.of ?? []);
+    const sql = dialect.compileDdl(body(...rows), meta.entity, { rows: source });
+    const guard = triggerGuard(dialect, meta, trigger, rows, names, source);
     const inBody = features.guards !== 'clause';
     const guarded = !guard || !inBody
         ? sql
@@ -115,12 +116,16 @@ function triggerBody(dialect, meta, trigger, before) {
     }
     return body;
 }
-/** The one condition both guards reduce to: any watched column that moved, and whatever `where` asks. */
-function triggerGuard(dialect, meta, trigger, rows, names) {
+/**
+ * The one condition both guards reduce to: any watched column that moved, and whatever `where` asks. On a
+ * set-based engine a watched column narrows `source` already, so the guard asks whether it holds a row.
+ */
+function triggerGuard(dialect, meta, trigger, rows, names, source) {
     const moved = movedColumns(dialect, meta, trigger.of ?? [], names);
+    const watched = moved && (source ? `EXISTS (SELECT 1 ${source})` : moved);
     return [
-        ...(moved ? [moved] : []),
-        ...(trigger.where ? condition(dialect, meta, trigger.where, rows, names, Boolean(moved)) : []),
+        ...(watched ? [watched] : []),
+        ...(trigger.where ? condition(dialect, meta, trigger.where, rows, names, Boolean(watched)) : []),
     ].join(' AND ');
 }
 /** The PL/pgSQL function holding a body. `OR REPLACE`, since a dropped table leaves its function behind. */
@@ -210,7 +215,7 @@ function dollarQuote(body) {
 }
 /**
  * Whether any watched column moved, null-safely, or `undefined` where none is watched: the two records
- * compared on a row-based engine, and on a set-based one the same question over a join of its two tables.
+ * compared on a row-based engine, the two tables' rows on a set-based one.
  */
 function movedColumns(dialect, meta, of, { $new: newName, $old: oldName }) {
     if (!of.length) {
@@ -220,16 +225,15 @@ function movedColumns(dialect, meta, of, { $new: newName, $old: oldName }) {
         const column = dialect.escapedColumnName(meta, key);
         return dialect.neExpr(`${oldName}.${column}`, `${newName}.${column}`);
     });
-    const moved = differs.length > 1 ? `(${differs.join(' OR ')})` : differs.join('');
-    const source = rowsFrom(dialect, meta, 'UPDATE');
-    return source ? `EXISTS (SELECT 1 ${source} WHERE ${moved})` : moved;
+    return differs.length > 1 ? `(${differs.join(' OR ')})` : differs.join('');
 }
 /**
  * Where a set-based engine's body reads the rows it fires for, as the `FROM` a statement names them in:
- * `inserted` on an insert, `deleted` on a delete, and on an update both, joined on the whole key. None on a
- * row-based engine, whose body reads `NEW` and `OLD` bare.
+ * `inserted` on an insert, `deleted` on a delete, and on an update both, joined on the whole key and on a
+ * watched column having moved, so the body writes for those rows alone, as a per-row engine fires for them.
+ * None on a row-based engine, whose body reads `NEW` and `OLD` bare.
  */
-function rowsFrom(dialect, meta, operation) {
+function rowsFrom(dialect, meta, operation, of) {
     if (dialect.features.triggers.rows !== 'set') {
         return undefined;
     }
@@ -241,5 +245,6 @@ function rowsFrom(dialect, meta, operation) {
         const column = dialect.escapedColumnName(meta, id);
         return `${$new}.${column} = ${$old}.${column}`;
     });
-    return `FROM ${$new} JOIN ${$old} ON ${keyed.join(' AND ')}`;
+    const moved = movedColumns(dialect, meta, of, { $new, $old });
+    return `FROM ${$new} JOIN ${$old} ON ${[...keyed, ...(moved ? [moved] : [])].join(' AND ')}`;
 }

package/dist/mongo/mongoDialect.js

@@ -19,9 +19,7 @@ export const mongoDialectFeatures = {
     indexIfNotExists: false,
     schemas: false, // the connection picks the database, and a collection name takes no dot
     dropTableCascade: false,
-    foreignKeyAlter: false,
-    primaryKeyAlter: false,
-    generatedColumnAdd: false,
+    rebuildsTables: false,
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: false,

package/dist/mssql/mssqlDialect.js

@@ -17,9 +17,7 @@ const MSSQL_FEATURES = {
     indexIfNotExists: true,
     schemas: true,
     dropTableCascade: false,
-    foreignKeyAlter: true,
-    primaryKeyAlter: true,
-    generatedColumnAdd: true,
+    rebuildsTables: false,
     // Extended properties are out-of-band metadata with their own procedures, not comments.
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,

package/dist/schema/indexDifferences.d.ts

@@ -30,7 +30,7 @@ export declare function pairIndexes<S extends ComparableIndex, T extends Compara
 /**
  * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
  * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
- * dropped: any other may have been made outside the ORM.
+ * dropped: any other may have been made outside the ORM, so it is `kept`.
  */
 export declare function indexChanges<I extends IndexSchema>(table: string, declared: readonly I[], current: readonly IndexNode[], facets: ReadonlySet<IndexFacet>): {
     toAdd: I[];
@@ -39,6 +39,7 @@ export declare function indexChanges<I extends IndexSchema>(table: string, decla
         from: IndexNode;
         to: I;
     }[];
+    kept: IndexNode[];
 };
 /**
  * What two indexes differ by, comparing only what both sides state structurally: an expression, a JSON

package/dist/schema/indexDifferences.js

@@ -38,7 +38,7 @@ export function pairIndexes(source, target, normalizeName = (name) => name) {
 /**
  * The indexes a table lacks, the ones it no longer needs, and the ones to rebuild, differing in what
  * `facets` let the engine report. Only an unpaired index uql named, or whose name the entity claims, is
- * dropped: any other may have been made outside the ORM.
+ * dropped: any other may have been made outside the ORM, so it is `kept`.
  */
 export function indexChanges(table, declared, current, facets) {
     const { created, dropped, matched } = pairIndexes(declared, current);
@@ -47,6 +47,7 @@ export function indexChanges(table, declared, current, facets) {
     return {
         toAdd: created,
         toDrop: dropped.filter(owned),
+        kept: dropped.filter((index) => !owned(index)),
         toAlter: matched.flatMap(([to, from]) => (describeIndexDifferences(to, from, facets).length ? [{ from, to }] : [])),
     };
 }

package/dist/schema/matchByKey.d.ts

@@ -8,3 +8,12 @@ export declare function matchByKey<S, T>(source: Iterable<S>, target: Iterable<T
     dropped: T[];
     matched: (readonly [S, T])[];
 };
+/**
+ * What {@link matchByKey} left unpaired, paired where `same` finds exactly one counterpart on each side:
+ * an item two others could be is ambiguous, so it stays created or dropped.
+ */
+export declare function pairUnique<S, T>(created: readonly S[], dropped: readonly T[], same: (source: S, target: T) => boolean): {
+    created: S[];
+    dropped: T[];
+    matched: (readonly [S, T & ({} | null)])[];
+};

package/dist/schema/matchByKey.js

@@ -16,3 +16,21 @@ export function matchByKey(source, target, key) {
     }
     return { created, dropped: [...unpaired.values()].flat(), matched };
 }
+/**
+ * What {@link matchByKey} left unpaired, paired where `same` finds exactly one counterpart on each side:
+ * an item two others could be is ambiguous, so it stays created or dropped.
+ */
+export function pairUnique(created, dropped, same) {
+    const matched = created.flatMap((source) => {
+        const [target, ...others] = dropped.filter((candidate) => same(source, candidate));
+        return target !== undefined && !others.length && created.filter((other) => same(other, target)).length === 1
+            ? [[source, target]]
+            : [];
+    });
+    const paired = new Set(matched.flat());
+    return {
+        created: created.filter((item) => !paired.has(item)),
+        dropped: dropped.filter((item) => !paired.has(item)),
+        matched,
+    };
+}

package/dist/schema/schemaAST.js

@@ -9,6 +9,7 @@ export function createTableNode(name, schema, indexFacets = new Set()) {
         columns: new Map(),
         indexes: [],
         checks: [],
+        externalForeignKeys: [],
         incomingRelations: [],
         outgoingRelations: [],
     };

package/dist/schema/schemaASTDiffer.d.ts

@@ -1,3 +1,4 @@
+import type { ColumnRenames, Rename } from '../type/migration.js';
 import type { SchemaAST } from './schemaAST.js';
 import type { CanonicalType } from './types.js';
 import type { ColumnDiff, ForeignKeyAction, IndexDiff, RelationshipDiff, RelationshipNode, SchemaDiffResult, TableDiff, TableNode } from './types.js';
@@ -28,6 +29,18 @@ export declare function diffTable(source: TableNode, target: TableNode, options?
     readonly columnDiffs: ColumnDiff[];
     readonly indexDiffs: IndexDiff[];
 }) | undefined;
+/**
+ * The columns renamed in the tables both sides name, by qualified table:
+ * a new column identical to exactly one the entity no longer names, and to no other. The dropped side is
+ * always the entity's own table, so a wrong guess renames, keeping the data, and never drops it.
+ */
+export declare function columnRenames(desired: SchemaAST, actual: SchemaAST, options?: DiffOptions): ColumnRenames;
+/**
+ * Tables the database holds that a new one is identical to but for its name, each only where it is the one
+ * match on both sides. Suggested, never applied: the database's side is a table no entity names, which may
+ * be another application's rather than one this schema renamed.
+ */
+export declare function tableRenameCandidates(desired: SchemaAST, actual: SchemaAST, options?: DiffOptions): Rename[];
 /** The differences between two lists of foreign keys, matched by their columns and never by the name the engine gave them. */
 export declare function diffRelationshipNodes(source: readonly RelationshipNode[], target: readonly RelationshipNode[], opts?: DiffOptions): RelationshipDiff[];
 /** A relationship's `ON DELETE` and `ON UPDATE`, an unstated one read as the action the database applies. */

package/dist/schema/schemaASTDiffer.js

@@ -1,6 +1,7 @@
+import { qualifyName } from '../util/sql.util.js';
 import { areTypesEqual, isBreakingTypeChange } from './canonicalType.js';
 import { describeIndexDifferences, pairIndexes } from './indexDifferences.js';
-import { matchByKey } from './matchByKey.js';
+import { matchByKey, pairUnique } from './matchByKey.js';
 import { DEFAULT_FOREIGN_KEY_ACTION } from './types.js';
 /**
  * Default diff options.
@@ -23,9 +24,7 @@ function relationEnds(relation) {
 /** The differences between the expected schema (the entities) and the actual one (the database). */
 export function diffSchemas(source, target, options = {}) {
     const opts = { ...DEFAULT_OPTIONS, ...options };
-    const normalizeName = nameNormalizer(opts);
-    const included = (tables) => [...tables].filter((table) => !opts.excludeTables.includes(table.name));
-    const { created: tablesToCreate, dropped: tablesToDrop, matched, } = matchByKey(included(source.tables.values()), included(target.tables.values()), (table) => normalizeName(table.name));
+    const { created: tablesToCreate, dropped: tablesToDrop, matched } = matchTables(source, target, opts);
     const tablesToAlter = matched
         .map(([sourceTable, targetTable]) => diffTable(sourceTable, targetTable, opts))
         .filter((tableDiff) => tableDiff !== undefined);
@@ -104,6 +103,38 @@ function diffTableColumns(source, target, opts) {
             .filter((diff) => diff !== undefined),
     ];
 }
+/**
+ * The columns renamed in the tables both sides name, by qualified table:
+ * a new column identical to exactly one the entity no longer names, and to no other. The dropped side is
+ * always the entity's own table, so a wrong guess renames, keeping the data, and never drops it.
+ */
+export function columnRenames(desired, actual, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const normalizeName = nameNormalizer(opts);
+    return new Map(matchTables(desired, actual, opts).matched.flatMap(([expected, current]) => {
+        const { created, dropped } = matchByKey(expected.columns.values(), current.columns.values(), (column) => normalizeName(column.name));
+        const { matched } = pairUnique(created, dropped, (to, from) => !diffColumn(expected.name, to, from, opts));
+        const table = qualifyName(current.name, current.schema);
+        return matched.length ? [[table, matched.map(([to, from]) => ({ from: from.name, to: to.name }))]] : [];
+    }));
+}
+/**
+ * Tables the database holds that a new one is identical to but for its name, each only where it is the one
+ * match on both sides. Suggested, never applied: the database's side is a table no entity names, which may
+ * be another application's rather than one this schema renamed.
+ */
+export function tableRenameCandidates(desired, actual, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const { created, dropped } = matchTables(desired, actual, opts);
+    const same = (to, from) => to.schema === from.schema && !diffTable(to, from, { ...opts, compareIndexes: false });
+    return pairUnique(created, dropped, same).matched.map(([to, from]) => ({ from: from.name, to: to.name }));
+}
+/** The two sides' tables paired by name, those `excludeTables` names left out of both. */
+function matchTables(desired, actual, opts) {
+    const normalizeName = nameNormalizer(opts);
+    const included = (tables) => [...tables].filter((table) => !opts.excludeTables.includes(table.name));
+    return matchByKey(included(desired.tables.values()), included(actual.tables.values()), (table) => normalizeName(table.name));
+}
 /** Compare indexes between two tables, paired by {@link pairIndexes}, in what the target's reader reports. */
 function diffTableIndexes(source, target, opts) {
     const { created, dropped, matched } = pairIndexes(source.indexes, target.indexes, nameNormalizer(opts));

package/dist/schema/types.d.ts

@@ -1,4 +1,4 @@
-import type { IndexSchema, PrimaryKeySchema } from '../type/migration.js';
+import type { ForeignKeySchema, IndexSchema, PrimaryKeySchema, StoredDefinition } from '../type/migration.js';
 import type { IndexFacet } from './indexDifferences.js';
 /**
  * Type categories universal across SQL dialects.
@@ -123,6 +123,10 @@ export interface TableNode {
     readonly checks: CheckSchema[];
     /** Optional table comment */
     readonly comment?: string;
+    /** The statements the engine keeps for the table, where it keeps them; none on a table built from entities. */
+    definition?: readonly StoredDefinition[];
+    /** The foreign keys to tables this AST does not hold, which a rebuild keeps as they are. */
+    readonly externalForeignKeys: ForeignKeySchema[];
     /** Relationships pointing TO this table (other tables referencing this one) */
     incomingRelations: RelationshipNode[];
     /** Relationships pointing FROM this table (this table referencing others) */

package/dist/sqlite/sqliteDialect.d.ts

@@ -13,7 +13,6 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     readonly commitTransactionCommand = "COMMIT";
     readonly rollbackTransactionCommand = "ROLLBACK";
     readonly isolationLevelStrategy = "none";
-    readonly alterColumnSyntax = "none";
     readonly booleanLiteral = "integer";
     /** SQLite's own cap on a function call before 3.48, which libSQL and `bun:sqlite`'s build still have. */
     readonly maxFunctionArgs: number;

package/dist/sqlite/sqliteDialect.js

@@ -21,9 +21,7 @@ export const SQLITE_FEATURES = {
     indexIfNotExists: true,
     schemas: false, // SQLite's namespaces are attached database files, not declared objects
     dropTableCascade: false,
-    foreignKeyAlter: false, // SQLite does not support adding FKs to existing tables
-    primaryKeyAlter: false, // nor changing a key: the only route is rebuilding the table
-    generatedColumnAdd: false, // accepted in a CREATE TABLE, rejected in an ALTER
+    rebuildsTables: true,
     commentSyntax: 'none',
     vectorIndexRequiresNotNull: false,
     vectorSupportsLength: true,
@@ -62,7 +60,6 @@ export class SqliteDialect extends AbstractSqlDialect {
     commitTransactionCommand = 'COMMIT';
     rollbackTransactionCommand = 'ROLLBACK';
     isolationLevelStrategy = 'none';
-    alterColumnSyntax = 'none';
     booleanLiteral = 'integer';
     /** SQLite's own cap on a function call before 3.48, which libSQL and `bun:sqlite`'s build still have. */
     maxFunctionArgs = 127;

package/dist/type/dialect.d.ts

@@ -87,18 +87,12 @@ export interface DialectFeatures {
      */
     readonly schemas: boolean;
     readonly dropTableCascade: boolean;
-    readonly foreignKeyAlter: boolean;
     /**
-     * Whether a table's primary key can be changed on an existing table. False on SQLite, whose only
-     * route is rebuilding the table - so a migration that would change one is refused by name rather
-     * than emitting DDL the engine rejects.
+     * Whether the engine changes a column, a key or a foreign key, or adds a stored generated column, only
+     * by rebuilding the table, as SQLite does: a generated migration copies the table into a new one, and
+     * the migration builder refuses the change by name.
      */
-    readonly primaryKeyAlter: boolean;
-    /**
-     * Whether a stored generated column can be added to an existing table. SQLite takes one only in a
-     * `CREATE TABLE`, so a sync that would add one is refused by name.
-     */
-    readonly generatedColumnAdd: boolean;
+    readonly rebuildsTables: boolean;
     /** Where a comment goes: in the declaration (MySQL family), a `COMMENT ON` of its own (Postgres family), or nowhere. */
     readonly commentSyntax: 'inline' | 'statement' | 'none';
     /**

package/dist/type/migration.d.ts

@@ -1,6 +1,7 @@
 import type { AnyMigrationOperation } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
+import type { DiffOptions } from '../schema/schemaASTDiffer.js';
 import type { ColumnNode, ForeignKeyAction, IndexType, TableNode } from '../schema/types.js';
 import type { EntityMeta, EntityWhereMeta, FieldOptions, IndexColumnSchema, IndexedVectorField, LoggingOptions, Querier, SqlQuerier, Type, VectorIndexOptions } from './index.js';
 /**
@@ -121,7 +122,20 @@ export interface TableSchema {
     readonly primaryKey?: PrimaryKeySchema;
     readonly indexes?: IndexSchema[];
     readonly foreignKeys?: ForeignKeySchema[];
+    /** The statements the engine keeps for the table, where it keeps them: SQLite's `sqlite_master`. */
+    readonly definition?: readonly StoredDefinition[];
 }
+/** A statement exactly as the engine keeps it, which only it can say all of: a `CHECK`, an index over an expression. */
+export type StoredDefinition = {
+    readonly kind: 'table' | 'index' | 'trigger';
+    readonly name: string;
+    readonly sql: string;
+};
+/** One side of a rebuilt table: its `CREATE TABLE` and what goes back on it, and the columns holding stored values, under this side's names. */
+export type RebuiltTable = {
+    readonly statements: readonly string[];
+    readonly columns: readonly string[];
+};
 /**
  * Represents an index in a database table
  */
@@ -173,6 +187,17 @@ export interface ForeignKeySchema {
  * change is undone by swapping its ends. No engine alters an index, a key or a foreign key in place, so
  * an alter of one is its drop and its add, which safe mode holds back together.
  */
+/** A column's change, and whether it can lose what the column holds: a drop, or a retype that narrows it. */
+export type ColumnChange = Change<ColumnSchema> & {
+    readonly isBreaking?: boolean;
+};
+/** A name changed, `from` the database's `to` the entity's. */
+export type Rename = {
+    readonly from: string;
+    readonly to: string;
+};
+/** Renamed columns by qualified table name. */
+export type ColumnRenames = ReadonlyMap<string, readonly Rename[]>;
 export interface Change<T> {
     readonly from?: T;
     readonly to?: T;
@@ -199,9 +224,19 @@ export interface SchemaDiff {
     readonly schema?: string;
     readonly type: 'create' | 'alter' | 'drop';
     readonly primaryKey?: Change<PrimaryKeySchema>;
-    readonly columns?: readonly Change<ColumnSchema>[];
+    readonly columns?: readonly ColumnChange[];
     readonly indexes?: readonly Change<IndexSchema>[];
     readonly foreignKeys?: readonly Change<ForeignKeySchema>[];
+    /** Columns renamed in place, `from` the database's name `to` the entity's, which the other changes already use. */
+    readonly renamedColumns?: readonly Rename[];
+    /**
+     * The table copied into a new one, which is how an engine that {@link DialectFeatures.rebuildsTables}
+     * applies the changes above. Its column renames are carried by the copy.
+     */
+    readonly rebuild?: {
+        readonly from: RebuiltTable;
+        readonly to: RebuiltTable;
+    };
 }
 /**
  * What every sync entry point takes: `safe` keeps it additive, `drop` lets it remove a column, and
@@ -288,10 +323,13 @@ export interface SchemaGenerator {
     /**
      * An entity's differences from its table. `desiredAst`, from {@link buildAST}, has to span every entity
      * a foreign key here points at, or those keys read as matching.
+     * `renamedColumns` are columns `currentTable` already holds under their new names.
      */
-    diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
+    diffSchema(entity: Type<object>, currentTable: TableNode | undefined, desiredAst?: SchemaAST, renamedColumns?: readonly Rename[]): SchemaDiff | undefined;
     /** The entities as one AST, built once per run for every {@link diffSchema}. Absent on MongoDB, which diffs only indexes. */
     buildAST?(entities: readonly Type<object>[]): SchemaAST;
+    /** How this engine's diff compares types and defaults. Absent where {@link buildAST} is. */
+    diffOptions?(): DiffOptions;
     /**
      * The table's key: {@link resolveTableAlias} behind {@link resolveSchema}, which is how a
      * `SchemaAST` stores it and how a diff finds it again.
@@ -326,8 +364,11 @@ export interface SchemaIntrospector {
      * the database side never reports it, and no migration can close the gap.
      */
     readonly indexFacets: ReadonlySet<IndexFacet>;
-    /** The whole database, or just the tables named. Names nothing matches are left out. */
-    introspect(tables?: readonly string[]): Promise<SchemaAST>;
+    /**
+     * The whole database, or just the tables named. Names nothing matches are left out. `renames` reads
+     * each column under the name it is being renamed to, so a diff compares it as the column it becomes.
+     */
+    introspect(tables?: readonly string[], renames?: ColumnRenames): Promise<SchemaAST>;
     /**
      * Get all table names in the database
      */

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "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.86.0",
+  "version": "0.88.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/skills/uql-orm/SKILL.md

@@ -154,7 +154,7 @@ transaction. A querier from `pool.getQuerier()` is yours to release: bind it wit
 ## Migrations
 
 `npx uql-migrate` reads `uql.config.ts`. `sync` creates what the entities imply (development only);
-`generate:entities` writes the diff as a migration file to review; `up` applies migrations; `generate:from-db`
+`generate:entities` writes the diff as a migration file to review, renaming a column its field was renamed from, printing `renameTable` for a table that may have been, rebuilding a SQLite table for what it cannot alter, and refusing a required column with no default on a table holding rows; `up` applies migrations; `generate:from-db`
 writes entity classes from an existing database; `drift:check` fails when the database no longer matches.
 Triggers are part of the diff: uql installs its own under `_uql_`-prefixed names and never touches another.