uql-orm 0.95.0 → 0.96.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/dist/browser/uql-browser.min.js +2 -2
  2. package/dist/browser/uql-browser.min.js.map +3 -3
  3. package/dist/d1/d1Querier.d.ts +2 -0
  4. package/dist/d1/d1Querier.js +4 -0
  5. package/dist/dialect/abstractSqlDialect.d.ts +4 -4
  6. package/dist/dialect/abstractSqlDialect.js +28 -20
  7. package/dist/dialect/mysqlLikeSqlDialect.js +3 -6
  8. package/dist/dialect/pgLikeSqlDialect.d.ts +2 -2
  9. package/dist/dialect/pgLikeSqlDialect.js +4 -4
  10. package/dist/dialect/queryContext.d.ts +0 -2
  11. package/dist/dialect/queryContext.js +0 -6
  12. package/dist/libsql/libsqlDialect.d.ts +4 -1
  13. package/dist/libsql/libsqlDialect.js +4 -1
  14. package/dist/libsql/libsqlQuerierPool.d.ts +1 -1
  15. package/dist/libsql/libsqlQuerierPool.js +1 -1
  16. package/dist/maria/mariadbQuerier.d.ts +4 -0
  17. package/dist/maria/mariadbQuerier.js +14 -2
  18. package/dist/maria/mariadbQuerierPool.js +1 -1
  19. package/dist/migrate/bin.js +2 -4
  20. package/dist/migrate/cli.js +8 -4
  21. package/dist/migrate/codegen/entityTypes.js +6 -15
  22. package/dist/migrate/ddl/indexDdl.d.ts +1 -6
  23. package/dist/migrate/ddl/indexDdl.js +0 -10
  24. package/dist/migrate/ddl/mysqlIndexDdl.d.ts +5 -5
  25. package/dist/migrate/ddl/mysqlIndexDdl.js +11 -6
  26. package/dist/migrate/ddl/tableDdl.d.ts +8 -2
  27. package/dist/migrate/ddl/tableDdl.js +11 -3
  28. package/dist/migrate/drift/driftDetector.js +2 -10
  29. package/dist/migrate/introspection/sqliteIntrospector.d.ts +1 -1
  30. package/dist/migrate/introspection/sqliteIntrospector.js +4 -7
  31. package/dist/migrate/migrator.d.ts +2 -4
  32. package/dist/migrate/migrator.js +12 -20
  33. package/dist/migrate/schemaGenerator.d.ts +5 -0
  34. package/dist/migrate/schemaGenerator.js +18 -9
  35. package/dist/mongo/mongoDialect.d.ts +2 -2
  36. package/dist/mongo/mongoDialect.js +2 -3
  37. package/dist/mongo/mongoIntrospector.js +3 -4
  38. package/dist/mongo/mongoMigrationStorage.d.ts +2 -3
  39. package/dist/mongo/mongoMigrationStorage.js +2 -3
  40. package/dist/mongo/mongoSchemaGenerator.d.ts +6 -4
  41. package/dist/mongo/mongoSchemaGenerator.js +5 -10
  42. package/dist/mongo/mongodbQuerier.js +1 -1
  43. package/dist/mssql/mssqlDialect.d.ts +1 -1
  44. package/dist/mssql/mssqlDialect.js +1 -1
  45. package/dist/mssql/mssqlQuerier.d.ts +6 -3
  46. package/dist/mssql/mssqlQuerier.js +6 -8
  47. package/dist/mssql/mssqlQuerierPool.d.ts +1 -5
  48. package/dist/mssql/mssqlQuerierPool.js +21 -10
  49. package/dist/mysql/mysql2Querier.d.ts +5 -1
  50. package/dist/mysql/mysql2Querier.js +8 -5
  51. package/dist/mysql/mysql2QuerierPool.d.ts +0 -1
  52. package/dist/mysql/mysql2QuerierPool.js +6 -18
  53. package/dist/pglite/pgliteQuerier.d.ts +2 -2
  54. package/dist/pglite/pgliteQuerier.js +1 -1
  55. package/dist/postgres/abstractPgQuerierPool.d.ts +3 -2
  56. package/dist/postgres/abstractPgQuerierPool.js +3 -0
  57. package/dist/postgres/pgQuerier.d.ts +1 -0
  58. package/dist/querier/abstractQuerier.d.ts +10 -5
  59. package/dist/querier/abstractQuerier.js +44 -37
  60. package/dist/querier/abstractSqlQuerier.d.ts +4 -3
  61. package/dist/querier/abstractSqlQuerier.js +46 -41
  62. package/dist/schema/indexColumns.d.ts +8 -0
  63. package/dist/schema/indexColumns.js +28 -0
  64. package/dist/schema/indexDifferences.js +4 -7
  65. package/dist/schema/schemaASTBuilder.js +18 -23
  66. package/dist/schema/sqlExpression.d.ts +2 -2
  67. package/dist/schema/sqlExpression.js +2 -2
  68. package/dist/sqlite/hranaQuerier.d.ts +5 -6
  69. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  70. package/dist/sqlite/sqliteDialect.js +1 -1
  71. package/dist/turso/tursoDialect.d.ts +3 -3
  72. package/dist/turso/tursoDialect.js +5 -10
  73. package/dist/type/dialect.d.ts +7 -3
  74. package/dist/type/entity.d.ts +2 -2
  75. package/dist/type/migration.d.ts +2 -9
  76. package/dist/util/object.util.js +3 -0
  77. package/dist/util/sql.util.d.ts +0 -2
  78. package/dist/util/sql.util.js +0 -6
  79. package/package.json +6 -6
  80. package/skills/uql-orm/SKILL.md +2 -2
@@ -1,13 +1,13 @@
1
1
  #!/usr/bin/env node
2
2
  import * as fs from 'node:fs';
3
3
  import * as path from 'node:path';
4
+ import { UqlUsageError } from '../util/uqlError.js';
4
5
  import { assertCliConfig } from './assertCliConfig.js';
5
6
  import { loadConfig } from './cli-config.js';
6
7
  import { createEntityCodeGenerator } from './codegen/entityCodeGenerator.js';
7
8
  import { entityTypesSource } from './codegen/entityTypes.js';
8
9
  import { detectDrift } from './drift/driftDetector.js';
9
10
  import { Migrator } from './migrator.js';
10
- import { buildEntityAST } from './schemaGenerator.js';
11
11
  import { DEFAULT_MIGRATIONS_TABLE } from './storage/databaseStorage.js';
12
12
  export async function main(args = process.argv.slice(2)) {
13
13
  let customPath;
@@ -247,11 +247,15 @@ export async function runDriftCheck(migrator, config) {
247
247
  else {
248
248
  console.log('\nChecking for schema drift...');
249
249
  const generator = await migrator.getSchemaGenerator();
250
- const expectedAST = generator.buildAST?.(config.entities) ?? buildEntityAST(generator, config.entities);
250
+ // MongoDB's generator builds no AST: a collection has only its indexes to compare, which a dry run lists.
251
+ if (!generator.buildAST) {
252
+ throw new UqlUsageError('drift:check compares tables, and this database has none: `sync --dry-run` prints the index changes a sync would make');
253
+ }
254
+ const expectedAST = generator.buildAST(config.entities);
251
255
  // Build actual schema from database
252
256
  const actualAST = await migrator.schemaIntrospector.introspect();
253
- // Detect drift. The dialect renders canonical types as SQL - without it every type formats as
254
- // `unknown` and type drift compares equal, silently reporting a mismatched column as in sync.
257
+ // The dialect renders canonical types as SQL: without it no type drift is reported, silently
258
+ // passing a mismatched column as in sync.
255
259
  const report = detectDrift(expectedAST, actualAST, {
256
260
  dialect: config.pool?.dialect,
257
261
  defaultsEqual: generator.defaultsEqual,
@@ -1,6 +1,6 @@
1
1
  import { getMeta } from '../../entity/index.js';
2
2
  import { canonicalToTypeScript, resolveColumnCanonicalType } from '../../schema/canonicalType.js';
3
- import { declaresNotNull, isToManyRelation, upperFirst } from '../../util/index.js';
3
+ import { declaresNotNull, definedEntries, isToManyRelation, upperFirst } from '../../util/index.js';
4
4
  import { isIdentifierName } from './sourceLiteral.js';
5
5
  /**
6
6
  * A `.d.ts` for the entities as registered, so a shape that only exists at runtime reaches the
@@ -14,8 +14,8 @@ export function entityTypesSource(entities) {
14
14
  const names = interfaceNames(metas);
15
15
  const interfaces = metas.map((meta) => {
16
16
  const members = [
17
- ...Object.entries(meta.fields).map(([key, field]) => fieldMember(key, field)),
18
- ...Object.entries(meta.relations).map(([key, rel]) => ` ${propertyName(key)}?: ${relationType(rel, names)};`),
17
+ ...definedEntries(meta.fields).map(([key, field]) => fieldMember(key, field)),
18
+ ...definedEntries(meta.relations).map(([key, rel]) => ` ${propertyName(key)}?: ${relationType(rel, names)};`),
19
19
  ];
20
20
  return `export interface ${names.get(meta.entity)} {\n${members.join('\n')}\n}`;
21
21
  });
@@ -52,13 +52,11 @@ function propertyName(key) {
52
52
  * A field as an entity class declares it: required where every read has it and an insert names it, a
53
53
  * key included, which an insert leaves out anyway; optional where a default fills it or a read skips it
54
54
  * (`eager: false`); `| null` where the column holds NULL; `readonly` where the database computes it.
55
+ * Typed as the DDL resolves it, so a foreign key reads as the key it points at.
55
56
  */
56
57
  function fieldMember(key, field) {
57
- const type = fieldType(field);
58
+ const type = canonicalToTypeScript(resolveColumnCanonicalType(field));
58
59
  const name = propertyName(key);
59
- if (!field) {
60
- return ` ${name}?: ${type};`;
61
- }
62
60
  const written = field.computed === undefined ? '' : 'readonly ';
63
61
  if (!declaresNotNull(field)) {
64
62
  return ` ${written}${name}?: ${type} | null;`;
@@ -66,19 +64,12 @@ function fieldMember(key, field) {
66
64
  const optional = !field.isId && (field.defaultValue !== undefined || field.onInsert !== undefined || field.eager === false);
67
65
  return ` ${written}${name}${optional ? '?' : ''}: ${type};`;
68
66
  }
69
- /**
70
- * The property type a column reads back as, resolved the way the DDL resolves it - so a foreign key
71
- * reports the type of the key it points at rather than the fallback its own options carry.
72
- */
73
- function fieldType(field) {
74
- return field ? canonicalToTypeScript(resolveColumnCanonicalType(field)) : 'unknown';
75
- }
76
67
  /**
77
68
  * A relation is the related interface, a list where the cardinality says so - and `unknown` where the
78
69
  * target is outside the set, since naming an interface the file does not declare would not compile.
79
70
  */
80
71
  function relationType(relation, names) {
81
- const target = relation && names.get(relation.entity());
72
+ const target = names.get(relation.entity());
82
73
  if (!target) {
83
74
  return 'unknown';
84
75
  }
@@ -1,6 +1,6 @@
1
1
  import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
2
2
  import { type IndexType } from '../../schema/types.js';
3
- import { type IndexColumnSchema, type IndexFeature, type IndexJsonArray, type IndexJsonPath, type IndexSchema } from '../../type/index.js';
3
+ import { type IndexColumnSchema, type IndexFeature, type IndexJsonPath, type IndexSchema } from '../../type/index.js';
4
4
  /** Refuses an index of a type `types` lacks, `hints` naming what to declare instead. */
5
5
  export declare function assertIndexType(index: IndexSchema, types: ReadonlySet<IndexType>, dialectName: string, hints?: ReadonlyMap<IndexType, string>): void;
6
6
  /** Refuses an index asking for a feature `features` lacks. */
@@ -52,11 +52,6 @@ export declare class IndexDdl<D extends AbstractSqlDialect = AbstractSqlDialect>
52
52
  protected indexColumnTarget(entry: IndexColumnSchema): string;
53
53
  /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
54
54
  protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
55
- /**
56
- * One key per *element* of the JSON array, which is MySQL's multi-valued index and nothing else's -
57
- * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.
58
- */
59
- protected jsonArrayIndexExpr(_escapedColumn: string, _json: IndexJsonArray): string;
60
55
  /** Postgres-wire dialects put a vector or user-declared operator class here. */
61
56
  protected indexColumnOpsClass(_entry: IndexColumnSchema, _index: IndexSchema): string;
62
57
  /** `ASC` is every engine's default, so only `DESC` is worth emitting. */
@@ -109,22 +109,12 @@ export class IndexDdl {
109
109
  if (entry.jsonPath) {
110
110
  return `(${this.jsonPathIndexExpr(column, entry.jsonPath)})`;
111
111
  }
112
- if (entry.jsonArray) {
113
- return `(${this.jsonArrayIndexExpr(column, entry.jsonArray)})`;
114
- }
115
112
  return entry.length === undefined ? column : `${column}(${entry.length})`;
116
113
  }
117
114
  /** The path read the way a query comparing it reads it, which is how the planner matches the two. */
118
115
  jsonPathIndexExpr(escapedColumn, json) {
119
116
  return this.dialect.jsonPathExpr(escapedColumn, json.path, jsonTypeMode(json.type));
120
117
  }
121
- /**
122
- * One key per *element* of the JSON array, which is MySQL's multi-valued index and nothing else's -
123
- * every other dialect refuses `jsonArray` in {@link assertIndexFeatures} and never reaches this.
124
- */
125
- jsonArrayIndexExpr(_escapedColumn, _json) {
126
- throw new UqlUsageError(`${this.dialect.dialectName} has no multi-valued index`);
127
- }
128
118
  /** Postgres-wire dialects put a vector or user-declared operator class here. */
129
119
  indexColumnOpsClass(_entry, _index) {
130
120
  return '';
@@ -1,5 +1,5 @@
1
1
  import type { IndexType } from '../../schema/types.js';
2
- import type { IndexJsonArray, IndexJsonPath, IndexSchema } from '../../type/index.js';
2
+ import type { IndexColumnSchema, IndexJsonPath, IndexSchema } from '../../type/index.js';
3
3
  import { IndexDdl } from './indexDdl.js';
4
4
  /** `CREATE INDEX ... (cols) USING btree`, plus the types this family spells as a keyword instead. */
5
5
  export declare class MysqlLikeIndexDdl extends IndexDdl {
@@ -23,11 +23,11 @@ export declare class MySqlIndexDdl extends MysqlLikeIndexDdl {
23
23
  */
24
24
  protected jsonPathIndexExpr(escapedColumn: string, json: IndexJsonPath): string;
25
25
  /**
26
- * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
27
- * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`
28
- * indexes the array at that path instead, as `'tags.ids': { $all: [...] }` reads it.
26
+ * A JSON array entry is MySQL's multi-valued index, one key per element: `CAST(col AS CHAR(64) ARRAY)`,
27
+ * over the column itself where the array is the whole document, which is what `$all`'s
28
+ * `JSON_CONTAINS(col, ?)` is matched against. A `path` indexes the array at that path instead.
29
29
  */
30
- protected jsonArrayIndexExpr(escapedColumn: string, json: IndexJsonArray): string;
30
+ protected indexColumnTarget(entry: IndexColumnSchema): string;
31
31
  /**
32
32
  * MySQL 26.7 has `VECTOR` columns and `STRING_TO_VECTOR`, but no distance function outside
33
33
  * HeatWave, hence no vector index to build: `USING hnsw` is a syntax error, `VECTOR INDEX` MariaDB's.
@@ -51,13 +51,18 @@ export class MySqlIndexDdl extends MysqlLikeIndexDdl {
51
51
  return `CAST(${expr} AS CHAR(${json.length}) CHARACTER SET utf8mb4) COLLATE utf8mb4_bin`;
52
52
  }
53
53
  /**
54
- * `CAST(col AS CHAR(64) ARRAY)`, over the column itself where the array is the whole document -
55
- * which is what `$all` reads, and what its `JSON_CONTAINS(col, ?)` is matched against. A `path`
56
- * indexes the array at that path instead, as `'tags.ids': { $all: [...] }` reads it.
54
+ * A JSON array entry is MySQL's multi-valued index, one key per element: `CAST(col AS CHAR(64) ARRAY)`,
55
+ * over the column itself where the array is the whole document, which is what `$all`'s
56
+ * `JSON_CONTAINS(col, ?)` is matched against. A `path` indexes the array at that path instead.
57
57
  */
58
- jsonArrayIndexExpr(escapedColumn, json) {
59
- const source = json.path ? this.dialect.jsonPathExpr(escapedColumn, json.path, 'json') : escapedColumn;
60
- return `CAST(${source} AS ${arrayCastType(json)} ARRAY)`;
58
+ indexColumnTarget(entry) {
59
+ const json = entry.jsonArray;
60
+ if (!json) {
61
+ return super.indexColumnTarget(entry);
62
+ }
63
+ const column = this.dialect.escapeId(entry.column);
64
+ const source = json.path ? this.dialect.jsonPathExpr(column, json.path, 'json') : column;
65
+ return `(CAST(${source} AS ${arrayCastType(json)} ARRAY))`;
61
66
  }
62
67
  /**
63
68
  * MySQL 26.7 has `VECTOR` columns and `STRING_TO_VECTOR`, but no distance function outside
@@ -1,5 +1,6 @@
1
1
  import type { AbstractSqlDialect } from '../../dialect/abstractSqlDialect.js';
2
2
  import type { Alteration, ColumnSchema } from '../../type/index.js';
3
+ import { UqlUsageError } from '../../util/uqlError.js';
3
4
  /**
4
5
  * A column's type with the size it was read back with, unless its spelling already carries one:
5
6
  * introspection reports `VARCHAR` and `255` apart, where a type from an entity is already whole.
@@ -24,8 +25,11 @@ export declare class TableDdl {
24
25
  alterColumn(table: string, column: ColumnSchema, definition: string, from?: ColumnSchema): string[];
25
26
  /** The statements making `alterations` to one table, whose new definitions `render` writes. */
26
27
  alterColumns(table: string, alterations: readonly Alteration<ColumnSchema>[], render: (column: ColumnSchema) => string): string[];
27
- /** The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. */
28
- protected alterClauses(_column: ColumnSchema, definition: string, _from?: ColumnSchema): string[];
28
+ /**
29
+ * The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. None in the portable
30
+ * form: SQLite changes a column only by rebuilding its table, which a diff states as `rebuild`.
31
+ */
32
+ protected alterClauses(column: ColumnSchema, _definition: string, _from?: ColumnSchema): string[];
29
33
  /** One `ALTER TABLE` making every clause, and none for no clause. */
30
34
  protected alterTable(table: string, clauses: readonly string[]): string[];
31
35
  renameColumn(table: string, oldName: string, newName: string): string;
@@ -48,3 +52,5 @@ export declare class TableDdl {
48
52
  }
49
53
  /** `DROP INDEX <index> ON <table>`, for engines that scope index names per table: MySQL and SQL Server. */
50
54
  export declare function dropIndexOnTable(dialect: AbstractSqlDialect, table: string, index: string): string;
55
+ /** What an engine that changes a table only by rebuilding it says to `what`, done in place. */
56
+ export declare function rebuildRefusal(dialect: AbstractSqlDialect, what: string): UqlUsageError;
@@ -47,9 +47,12 @@ export class TableDdl {
47
47
  alterColumns(table, alterations, render) {
48
48
  return this.alterTable(table, alterations.flatMap(({ from, to }) => this.alterClauses(to, render(to), from)));
49
49
  }
50
- /** The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. */
51
- alterClauses(_column, definition, _from) {
52
- return [`ALTER COLUMN ${definition}`];
50
+ /**
51
+ * The `ALTER TABLE` clauses that change a column, as {@link alterColumn} takes it. None in the portable
52
+ * form: SQLite changes a column only by rebuilding its table, which a diff states as `rebuild`.
53
+ */
54
+ alterClauses(column, _definition, _from) {
55
+ throw rebuildRefusal(this.dialect, `Altering the column "${column.name}"`);
53
56
  }
54
57
  /** One `ALTER TABLE` making every clause, and none for no clause. */
55
58
  alterTable(table, clauses) {
@@ -95,3 +98,8 @@ export class TableDdl {
95
98
  export function dropIndexOnTable(dialect, table, index) {
96
99
  return `DROP INDEX ${dialect.escapeId(index)} ON ${dialect.escapeId(table)};`;
97
100
  }
101
+ /** What an engine that changes a table only by rebuilding it says to `what`, done in place. */
102
+ export function rebuildRefusal(dialect, what) {
103
+ return new UqlUsageError(`${dialect.dialectName}: ${what} rebuilds the table, which a migration generated from the entities does ` +
104
+ '(`uql-migrate generate:entities`) and a hand-written one cannot.');
105
+ }
@@ -124,8 +124,8 @@ function addAlterColumnDrifts(colDiff, drifts, opts) {
124
124
  const { changed } = colDiff;
125
125
  // Type drift needs a dialect to render both types.
126
126
  if (opts.checkTypes && opts.dialect && changed.includes('type')) {
127
- const expectedType = formatType(colDiff.to.type, opts.dialect);
128
- const actualType = formatType(colDiff.from.type, opts.dialect);
127
+ const expectedType = canonicalToSql(colDiff.to.type, opts.dialect);
128
+ const actualType = canonicalToSql(colDiff.from.type, opts.dialect);
129
129
  drifts.push({
130
130
  type: 'type_mismatch',
131
131
  severity: colDiff.isBreaking ? 'critical' : 'warning',
@@ -276,11 +276,3 @@ function createSummary(drifts) {
276
276
  info: drifts.filter((d) => d.severity === 'info').length,
277
277
  };
278
278
  }
279
- /**
280
- * Format type for display.
281
- */
282
- function formatType(type, dialect) {
283
- if (!dialect)
284
- return 'unknown';
285
- return canonicalToSql(type, dialect);
286
- }
@@ -31,7 +31,7 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
31
31
  }): string;
32
32
  protected mapColumnsResult(read: TableRowReader, tableName: string, results: SqliteColumnRow[]): Promise<ColumnSchema[]>;
33
33
  protected mapIndexesResult(read: TableRowReader, _tableName: string, results: SqliteIndexRow[]): Promise<IndexSchema[]>;
34
- protected mapForeignKeysResult(_read: TableRowReader, tableName: string, results: SqliteForeignKeyRow[]): Promise<ForeignKeySchema[]>;
34
+ protected mapForeignKeysResult(_read: TableRowReader, _tableName: string, results: SqliteForeignKeyRow[]): Promise<ForeignKeySchema[]>;
35
35
  /** Every statement `sqlite_master` keeps for the table, its `CREATE TABLE` first. An automatic index has none. */
36
36
  protected getDefinition(read: TableRowReader, tableName: string): Promise<StoredDefinition[]>;
37
37
  protected mapPrimaryKeyResult(results: SqliteColumnRow[]): string[] | undefined;
@@ -1,4 +1,3 @@
1
- import { derivedForeignKeyName } from '../../util/sql.util.js';
2
1
  import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.js';
3
2
  /**
4
3
  * SQLite schema introspector
@@ -116,7 +115,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
116
115
  }
117
116
  return indexSchemas;
118
117
  }
119
- async mapForeignKeysResult(_read, tableName, results) {
118
+ async mapForeignKeysResult(_read, _tableName, results) {
120
119
  // Group by id to handle composite foreign keys
121
120
  const grouped = new Map();
122
121
  for (const row of results) {
@@ -128,10 +127,8 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
128
127
  return Array.from(grouped.entries()).map(([, rows]) => {
129
128
  const first = rows[0];
130
129
  const columns = rows.map((r) => r.from);
130
+ // Unnamed: `PRAGMA foreign_key_list` reports none, so the AST derives one from the columns, as the entity side does.
131
131
  return {
132
- // `PRAGMA foreign_key_list` reports no name, so one is derived the same way the entity side
133
- // derives it. Seeded from the columns, not the PRAGMA's row id, which nothing else knows.
134
- name: derivedForeignKeyName(tableName, columns),
135
132
  columns,
136
133
  references: { table: first.table, columns: rows.map((r) => r.to) },
137
134
  onDelete: this.normalizeReferentialAction(first.on_delete),
@@ -286,6 +283,6 @@ function scan(sql, visit) {
286
283
  }
287
284
  /** The name a column definition opens with, however it was quoted. */
288
285
  function leadingIdentifier(entry) {
289
- const [token = ''] = /^\s*(?:"[^"]*"|`[^`]*`|\[[^\]]*\]|[^\s(]+)/.exec(entry) ?? [];
290
- return token.trim().replace(/^["`[]|["`\]]$/g, '');
286
+ const token = entry.trimStart().replace(/^("[^"]*"|`[^`]*`|\[[^\]]*\]|[^\s(]*)[\s\S]*$/, '$1');
287
+ return token.replace(/^["`[]|["`\]]$/g, '');
291
288
  }
@@ -1,4 +1,4 @@
1
- import type { LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
1
+ import type { Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
2
2
  import { LoggerWrapper } from '../util/index.js';
3
3
  import type { IMigrationBuilder } from './builder/types.js';
4
4
  /**
@@ -8,9 +8,7 @@ export declare class Migrator {
8
8
  private readonly pool;
9
9
  readonly storage: MigrationStorage;
10
10
  readonly migrationsPath: string;
11
- private _logger;
12
- get logger(): LoggerWrapper;
13
- set logger(value: LoggingOptions);
11
+ readonly logger: LoggerWrapper;
14
12
  private readonly _entities?;
15
13
  get entities(): Type<object>[];
16
14
  /** The generator given, or this dialect's once {@link getSchemaGenerator} has loaded it. */
@@ -5,13 +5,14 @@ import { getEntities, getMeta } from '../entity/index.js';
5
5
  import { SchemaAST } from '../schema/index.js';
6
6
  import { columnRenames, tableRenameCandidates } from '../schema/schemaASTDiffer.js';
7
7
  import { hasTriggers } from '../util/field.util.js';
8
- import { LoggerWrapper } from '../util/index.js';
8
+ import { definedEntries, isRecord, LoggerWrapper } from '../util/index.js';
9
9
  import { UqlUsageError } from '../util/uqlError.js';
10
10
  import { withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
11
11
  import { buildMigrationModule } from './codegen/migrationFile.js';
12
12
  import { introspectorFor } from './introspection/registry.js';
13
13
  import { migrationBuilderFor, migrationTargetFor } from './migrationTarget.js';
14
14
  import { dropped, lacksValue, newlyRequired, nonEmpty, reverseDiff, sides, withoutRebuild } from './schemaChange.js';
15
+ import { constraintNameOf } from './schemaGenerator.js';
15
16
  /**
16
17
  * Main class for managing database migrations
17
18
  */
@@ -19,13 +20,7 @@ export class Migrator {
19
20
  pool;
20
21
  storage;
21
22
  migrationsPath;
22
- _logger;
23
- get logger() {
24
- return this._logger;
25
- }
26
- set logger(value) {
27
- this._logger = new LoggerWrapper(value);
28
- }
23
+ logger;
29
24
  _entities;
30
25
  get entities() {
31
26
  return this._entities ?? getEntities();
@@ -39,7 +34,7 @@ export class Migrator {
39
34
  this.target = migrationTargetFor(pool, options.defaultForeignKeyAction);
40
35
  this.storage = options.storage ?? this.target.storage(options.tableName);
41
36
  this.migrationsPath = options.migrationsPath ?? './migrations';
42
- this._logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
37
+ this.logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
43
38
  this._entities = options.entities;
44
39
  this.schemaIntrospector = introspectorFor(pool);
45
40
  this.schemaGenerator = options.schemaGenerator;
@@ -392,9 +387,10 @@ export class Migrator {
392
387
  }
393
388
  }
394
389
  /** Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph order. */
395
- forceStatements(generator) {
390
+ async forceStatements(generator) {
391
+ const existing = await this.introspectEntities(this.entities);
396
392
  return [
397
- ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true }),
393
+ ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true, existing }),
398
394
  ...generator.generateCreateSchema(this.entities),
399
395
  ];
400
396
  }
@@ -507,7 +503,7 @@ export class Migrator {
507
503
  primaryKey: safe ? undefined : diff.primaryKey,
508
504
  columns: options.drop ? columns : nonEmpty((columns ?? []).filter((change) => change.to !== undefined)),
509
505
  indexes: additive('index', diff.indexes, (index) => index.name),
510
- foreignKeys: additive('foreign key', diff.foreignKeys, (foreignKey) => foreignKey.name ?? foreignKey.columns.join(', ')),
506
+ foreignKeys: additive('foreign key', diff.foreignKeys, (foreignKey) => constraintNameOf(diff.tableName, foreignKey)),
511
507
  };
512
508
  if (!diff.rebuild || !held) {
513
509
  return filtered;
@@ -566,6 +562,7 @@ export class Migrator {
566
562
  name: this.getMigrationName(fileName),
567
563
  up: migration.up.bind(migration),
568
564
  down: migration.down.bind(migration),
565
+ transaction: migration.transaction,
569
566
  };
570
567
  }
571
568
  this.logger.logWarn(`Warning: ${fileName} is not a valid migration`);
@@ -580,11 +577,7 @@ export class Migrator {
580
577
  * Check if an object is a valid migration
581
578
  */
582
579
  isMigration(obj) {
583
- return (typeof obj === 'object' &&
584
- obj !== undefined &&
585
- obj !== null &&
586
- typeof obj.up === 'function' &&
587
- typeof obj.down === 'function');
580
+ return isRecord(obj) && typeof obj['up'] === 'function' && typeof obj['down'] === 'function';
588
581
  }
589
582
  /**
590
583
  * Extract migration name from filename
@@ -635,9 +628,8 @@ export function defineBuilderMigration(migration) {
635
628
  }
636
629
  /** The entities `meta` points at, through a relation or a foreign key field. */
637
630
  function referencedEntities(meta) {
638
- const fields = Object.values(meta.fields).flatMap((field) => field?.references?.() ?? []);
639
- const relations = Object.values(meta.relations).flatMap((relation) => relation?.entity?.() ?? []);
640
- return [...fields, ...relations];
631
+ const fields = definedEntries(meta.fields).flatMap(([, field]) => field.references?.() ?? []);
632
+ return [...fields, ...definedEntries(meta.relations).map(([, relation]) => relation.entity())];
641
633
  }
642
634
  /** A diff's column renames, through the builder operation every SQL generator already renders. */
643
635
  function renameStatements(generator, { tableName, renamedColumns = [], rebuild }) {
@@ -187,6 +187,11 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
187
187
  */
188
188
  private assertAlterable;
189
189
  }
190
+ /**
191
+ * What a constraint is called: its own name, or one derived from its columns where nothing named it.
192
+ * Shared by the add and the drop so a `DROP CONSTRAINT` names exactly what an `ADD CONSTRAINT` made.
193
+ */
194
+ export declare function constraintNameOf(tableName: string, foreignKey: ForeignKeySchema): string;
190
195
  /**
191
196
  * The entities as an AST, named by `generator`'s resolvers rather than a naming strategy, which would
192
197
  * also rename an explicit `@Entity({ name })` and so compare each table under another name.
@@ -6,11 +6,10 @@ import { diffRelationshipNodes, diffTable } from '../schema/schemaASTDiffer.js';
6
6
  import { DEFAULT_FOREIGN_KEY_ACTION, } from '../schema/types.js';
7
7
  import { qualifyName } from '../util/index.js';
8
8
  import { derivedCheckName, derivedForeignKeyName, derivedPrimaryKeyName, isOwnedName } from '../util/sql.util.js';
9
- import { UqlUsageError } from '../util/uqlError.js';
10
9
  import { splitSqlStatements } from './builder/splitSqlStatements.js';
11
10
  import { formatDefaultValue, sameDefault } from './ddl/defaultSql.js';
12
11
  import { indexDdlFor, tableDdlFor } from './ddl/index.js';
13
- import { sizedType } from './ddl/tableDdl.js';
12
+ import { rebuildRefusal, sizedType } from './ddl/tableDdl.js';
14
13
  import { rebuildTable } from './ddl/tableRebuild.js';
15
14
  import { columnForeignKey, columnIndex, bareColumn, renderIndexDefinition, tableDefinitionToNode, } from './generator/definitionToNode.js';
16
15
  import { indexNodeToSchema } from './generator/indexNodeToSchema.js';
@@ -91,15 +90,14 @@ export class SqlSchemaGenerator {
91
90
  */
92
91
  generateCreateSchema(entities, options = {}) {
93
92
  const tables = this.orderedTables(entities, 'create', options.only);
94
- const withForeignKeys = options.foreignKeys ?? true;
95
93
  // Inline only where a constraint cannot be added afterwards, which is what makes the cyclic case
96
94
  // work everywhere else.
97
- const inline = withForeignKeys && this.features.rebuildsTables;
95
+ const inline = this.features.rebuildsTables;
98
96
  // Namespaces first: a qualified `CREATE TABLE` fails against a schema nobody created, and the
99
97
  // schema is the one part of the layout a migration cannot infer from the table it is making.
100
98
  const statements = this.generateCreateSchemas(tables);
101
99
  statements.push(...tables.flatMap((table) => this.generateCreateTableFromNode(inline ? table : { ...table, outgoingRelations: [] }, options)));
102
- if (withForeignKeys && !inline) {
100
+ if (!inline) {
103
101
  for (const table of tables) {
104
102
  statements.push(...this.addForeignKeyStatements(qualifyName(table.name, table.schema), table.outgoingRelations.map(foreignKeyOf)));
105
103
  }
@@ -157,7 +155,19 @@ export class SqlSchemaGenerator {
157
155
  return [...new Set(named)].map((schema) => this.dialect.createSchemaSql(schema));
158
156
  }
159
157
  generateDropSchema(entities, options = {}) {
160
- return this.orderedTables(entities, 'drop').map((table) => this.generateDropTable(qualifyName(table.name, table.schema), options));
158
+ const tables = this.orderedTables(entities, 'drop').map((table) => qualifyName(table.name, table.schema));
159
+ // A `CASCADE` drop takes the foreign keys with it, and SQLite drops with its constraints off.
160
+ const cascades = options.cascade && this.features.dropTableCascade;
161
+ const existing = cascades || this.features.rebuildsTables ? [] : (options.existing?.getTables() ?? []);
162
+ const foreignKeyDrops = existing.flatMap((table) => {
163
+ const tableName = qualifyName(table.name, table.schema);
164
+ const names = [
165
+ ...table.outgoingRelations.map((relation) => relation.name),
166
+ ...table.externalForeignKeys.map((foreignKey) => constraintNameOf(tableName, foreignKey)),
167
+ ];
168
+ return names.map((name) => this.generateDropForeignKeySql(tableName, name));
169
+ });
170
+ return [...foreignKeyDrops, ...tables.map((tableName) => this.generateDropTable(tableName, options))];
161
171
  }
162
172
  /**
163
173
  * The tables of `entities` in dependency order, optionally narrowed to `only`. The AST always spans
@@ -600,8 +610,7 @@ export class SqlSchemaGenerator {
600
610
  */
601
611
  assertAlterable(what) {
602
612
  if (this.features.rebuildsTables) {
603
- throw new UqlUsageError(`${this.dialect}: ${what} rebuilds the table, which a migration generated from the entities does ` +
604
- '(`uql-migrate generate:entities`) and a hand-written one cannot.');
613
+ throw rebuildRefusal(this.dialect, what);
605
614
  }
606
615
  }
607
616
  }
@@ -609,7 +618,7 @@ export class SqlSchemaGenerator {
609
618
  * What a constraint is called: its own name, or one derived from its columns where nothing named it.
610
619
  * Shared by the add and the drop so a `DROP CONSTRAINT` names exactly what an `ADD CONSTRAINT` made.
611
620
  */
612
- function constraintNameOf(tableName, foreignKey) {
621
+ export function constraintNameOf(tableName, foreignKey) {
613
622
  return foreignKey.name ?? derivedForeignKeyName(tableName, foreignKey.columns);
614
623
  }
615
624
  /**
@@ -15,7 +15,7 @@ export type MongoSortPlan = {
15
15
  /** What a read pipeline contributes to {@link MongoDialect.readStages} beyond the query itself. */
16
16
  type MongoReadStages = {
17
17
  /** Ordering, which runs after the lookups when it reads one of their fields. */
18
- readonly sort?: MongoSortPlan;
18
+ readonly sort: MongoSortPlan;
19
19
  readonly pager?: MongoAggregationPipelineEntry<Document>[];
20
20
  /** A score the read answers as a field, a vector search's or a text search's; a temporary one leaves again. */
21
21
  readonly score?: {
@@ -179,7 +179,7 @@ export declare class MongoDialect extends AbstractDialect {
179
179
  * What a read runs after its entry stage, in the one order that works: the lookups, then the sort and
180
180
  * page that may read them, then the projection. Shared with the `$vectorSearch` pipeline.
181
181
  */
182
- readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra?: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
182
+ readStages<E extends Document>(entity: Type<E>, q: Query<E>, extra: MongoReadStages): MongoAggregationPipelineEntry<Document>[];
183
183
  /**
184
184
  * `$distinct` as a `$group` on the columns the query projects - the same set a SQL dialect puts
185
185
  * after `SELECT DISTINCT` - and the `$replaceRoot` that lifts the grouped key back to the top
@@ -11,7 +11,6 @@ import { UqlUsageError } from '../util/uqlError.js';
11
11
  import { decodeBigIntsExcept } from '../util/wideNumber.js';
12
12
  import { textLanguage } from './textLanguage.js';
13
13
  import { vectorDistanceExpr } from './vectorDistance.js';
14
- const EMPTY_SORT_PLAN = { sort: {}, stages: [], fields: [] };
15
14
  /** A scalar field's operator as the aggregation operator computing it. */
16
15
  const MONGO_ARITHMETIC = { $inc: '$add', $mul: '$multiply' };
17
16
  /** Default {@link DialectFeatures} for MongoDB. */
@@ -734,13 +733,13 @@ export class MongoDialect extends AbstractDialect {
734
733
  * What a read runs after its entry stage, in the one order that works: the lookups, then the sort and
735
734
  * page that may read them, then the projection. Shared with the `$vectorSearch` pipeline.
736
735
  */
737
- readStages(entity, q, extra = {}) {
736
+ readStages(entity, q, extra) {
738
737
  const meta = getMeta(entity);
739
738
  const joins = resolveQueryJoins(meta, q);
740
739
  // The value an ordering by a relation's aggregate reads, and the field it parks it on: both belong
741
740
  // with the lookups, since the `$sort` right after them is what they exist for.
742
741
  const aggregated = this.sortAggregateStages(entity, q.$sort);
743
- const ordering = extra.sort ?? EMPTY_SORT_PLAN;
742
+ const ordering = extra.sort;
744
743
  const lookups = [...this.lookupStages(meta, joins), ...aggregated.stages];
745
744
  // Each to-many and each `$count`, which neither drop nor reorder a row, so they read the page alone.
746
745
  const related = this.relationReadStages(entity, q);
@@ -35,17 +35,16 @@ export class MongoSchemaIntrospector {
35
35
  if (!(await hasCollection(db, tableName))) {
36
36
  return undefined;
37
37
  }
38
- // Annotated rather than inferred: the driver's `indexes()` is overloaded and resolves to `any` on
39
- // some versions, which silently made every field below unchecked.
38
+ // Annotated: the driver types a `listIndexes` entry as `any`, and its `indexes()` leaves `name` optional.
40
39
  const collection = db.collection(tableName);
41
- const indexes = await collection.indexes();
40
+ const indexes = await collection.listIndexes().toArray();
42
41
  const searchIndexes = await listSearchIndexes(collection);
43
42
  return {
44
43
  name: tableName,
45
44
  columns: [],
46
45
  indexes: [
47
46
  ...indexes.map(({ name, key, unique, weights, default_language }) => ({
48
- name: name ?? Object.keys(key).join('_'),
47
+ name,
49
48
  unique: !!unique,
50
49
  ...(weights
51
50
  ? {
@@ -1,7 +1,8 @@
1
1
  import type { MigrationStorage, QuerierPool } from '../type/index.js';
2
2
  import { type MongoQuerier } from './mongoQuerier.js';
3
3
  /**
4
- * Stores migration state in a MongoDB collection, named as the SQL table would be.
4
+ * Stores migration state in a MongoDB collection, named as the SQL table would be, which MongoDB creates
5
+ * on its first insert.
5
6
  */
6
7
  export declare class MongoMigrationStorage implements MigrationStorage {
7
8
  private readonly pool;
@@ -9,8 +10,6 @@ export declare class MongoMigrationStorage implements MigrationStorage {
9
10
  constructor(pool: QuerierPool, options?: {
10
11
  tableName?: string;
11
12
  });
12
- /** Nothing to prepare: MongoDB creates the collection on its first insert. */
13
- ensureStorage(): Promise<void>;
14
13
  executed(): Promise<string[]>;
15
14
  logWithQuerier(querier: MongoQuerier, migrationName: string): Promise<void>;
16
15
  unlogWithQuerier(querier: MongoQuerier, migrationName: string): Promise<void>;
@@ -1,7 +1,8 @@
1
1
  import { DEFAULT_MIGRATIONS_TABLE } from '../migrate/storage/databaseStorage.js';
2
2
  import { withMongoQuerierForMigrations } from './mongoQuerier.js';
3
3
  /**
4
- * Stores migration state in a MongoDB collection, named as the SQL table would be.
4
+ * Stores migration state in a MongoDB collection, named as the SQL table would be, which MongoDB creates
5
+ * on its first insert.
5
6
  */
6
7
  export class MongoMigrationStorage {
7
8
  pool;
@@ -10,8 +11,6 @@ export class MongoMigrationStorage {
10
11
  this.pool = pool;
11
12
  this.collectionName = options.tableName ?? DEFAULT_MIGRATIONS_TABLE;
12
13
  }
13
- /** Nothing to prepare: MongoDB creates the collection on its first insert. */
14
- async ensureStorage() { }
15
14
  executed() {
16
15
  return withMongoQuerierForMigrations(this.pool, 'MongoMigrationStorage', async (querier) => {
17
16
  const documents = await this.collection(querier)