uql-orm 0.98.0 → 0.100.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 (174) hide show
  1. package/LICENSE.md +22 -0
  2. package/README.md +1 -1
  3. package/dist/browser/uql-browser.min.js +2 -2
  4. package/dist/browser/uql-browser.min.js.map +5 -5
  5. package/dist/bunSql/bunSql.util.js +2 -2
  6. package/dist/bunSql/bunSqlQuerier.js +0 -1
  7. package/dist/bunSql/bunSqlQuerierPool.js +1 -1
  8. package/dist/cockroachdb/cockroachDialect.js +1 -0
  9. package/dist/context/context.browser.d.ts +5 -0
  10. package/dist/context/context.browser.js +21 -11
  11. package/dist/context/context.d.ts +5 -0
  12. package/dist/context/context.js +8 -3
  13. package/dist/dialect/abstractDialect.js +4 -2
  14. package/dist/dialect/abstractSqlDialect.d.ts +5 -5
  15. package/dist/dialect/abstractSqlDialect.js +26 -18
  16. package/dist/dialect/aliases.d.ts +0 -2
  17. package/dist/dialect/aliases.js +0 -2
  18. package/dist/dialect/hydrateColumn.d.ts +3 -3
  19. package/dist/dialect/hydrateColumn.js +1 -0
  20. package/dist/dialect/index.js +0 -2
  21. package/dist/dialect/jsonSql.d.ts +2 -3
  22. package/dist/dialect/jsonSql.js +4 -6
  23. package/dist/dialect/mysqlLikeSqlDialect.d.ts +1 -1
  24. package/dist/dialect/mysqlLikeSqlDialect.js +5 -3
  25. package/dist/dialect/operators.d.ts +2 -3
  26. package/dist/dialect/operators.js +3 -4
  27. package/dist/dialect/pgLikeSqlDialect.js +12 -12
  28. package/dist/entity/decorator/members.d.ts +4 -12
  29. package/dist/entity/metadata/definition.js +8 -5
  30. package/dist/http/handler.d.ts +6 -6
  31. package/dist/http/handler.js +20 -5
  32. package/dist/index.d.ts +6 -5
  33. package/dist/index.js +6 -5
  34. package/dist/{maria → mariadb}/mariadbQuerier.js +1 -1
  35. package/dist/migrate/builder/columnBuilder.d.ts +3 -3
  36. package/dist/migrate/builder/columnBuilder.js +1 -1
  37. package/dist/migrate/builder/index.d.ts +0 -3
  38. package/dist/migrate/builder/index.js +0 -3
  39. package/dist/migrate/builder/migrationBuilder.d.ts +6 -6
  40. package/dist/migrate/builder/migrationBuilder.js +7 -7
  41. package/dist/migrate/builder/tableBuilder.d.ts +25 -25
  42. package/dist/migrate/builder/tableBuilder.js +5 -5
  43. package/dist/migrate/builder/types.d.ts +37 -37
  44. package/dist/migrate/cli-config.d.ts +9 -0
  45. package/dist/migrate/cli-config.js +14 -4
  46. package/dist/migrate/cli.js +9 -18
  47. package/dist/migrate/codegen/entityCodeGenerator.js +1 -1
  48. package/dist/migrate/codegen/migrationFile.d.ts +7 -7
  49. package/dist/migrate/codegen/migrationFile.js +11 -12
  50. package/dist/migrate/ddl/indexCapabilities.d.ts +2 -0
  51. package/dist/migrate/ddl/indexCapabilities.js +6 -0
  52. package/dist/migrate/ddl/indexDdl.d.ts +8 -0
  53. package/dist/migrate/ddl/indexDdl.js +22 -6
  54. package/dist/migrate/generator/definitionToNode.d.ts +1 -1
  55. package/dist/migrate/generator/definitionToNode.js +1 -1
  56. package/dist/migrate/index.d.ts +1 -3
  57. package/dist/migrate/index.js +0 -3
  58. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts +11 -15
  59. package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js +13 -15
  60. package/dist/migrate/introspection/mssqlIntrospector.d.ts +5 -5
  61. package/dist/migrate/introspection/mssqlIntrospector.js +24 -28
  62. package/dist/migrate/introspection/mysqlIntrospector.d.ts +5 -5
  63. package/dist/migrate/introspection/mysqlIntrospector.js +31 -37
  64. package/dist/migrate/introspection/postgresIntrospector.d.ts +13 -13
  65. package/dist/migrate/introspection/postgresIntrospector.js +35 -39
  66. package/dist/migrate/introspection/registry.js +1 -1
  67. package/dist/migrate/introspection/sqliteIntrospector.d.ts +6 -4
  68. package/dist/migrate/introspection/sqliteIntrospector.js +15 -12
  69. package/dist/migrate/migrationLock.d.ts +38 -0
  70. package/dist/migrate/migrationLock.js +103 -0
  71. package/dist/migrate/migrationTarget.d.ts +6 -2
  72. package/dist/migrate/migrationTarget.js +30 -14
  73. package/dist/migrate/migrator.d.ts +47 -37
  74. package/dist/migrate/migrator.js +154 -131
  75. package/dist/migrate/schemaGenerator.d.ts +3 -1
  76. package/dist/migrate/schemaGenerator.js +14 -5
  77. package/dist/migrate/storage/databaseStorage.d.ts +28 -20
  78. package/dist/migrate/storage/databaseStorage.js +36 -54
  79. package/dist/migrate/storage/index.d.ts +0 -1
  80. package/dist/migrate/storage/index.js +0 -1
  81. package/dist/{mongo → mongodb}/index.d.ts +0 -1
  82. package/dist/{mongo → mongodb}/index.js +0 -1
  83. package/dist/{mongo → mongodb}/mongoCommand.d.ts +17 -1
  84. package/dist/{mongo → mongodb}/mongoCommand.js +15 -2
  85. package/dist/{mongo → mongodb}/mongoDialect.js +8 -12
  86. package/dist/{mongo → mongodb}/mongoIntrospector.js +12 -3
  87. package/dist/{mongo → mongodb}/mongoMigrationStorage.d.ts +5 -5
  88. package/dist/{mongo → mongodb}/mongoMigrationStorage.js +8 -12
  89. package/dist/{mongo → mongodb}/mongoQuerier.d.ts +3 -1
  90. package/dist/{mongo → mongodb}/mongoSchemaGenerator.d.ts +11 -1
  91. package/dist/{mongo → mongodb}/mongoSchemaGenerator.js +56 -11
  92. package/dist/{mongo → mongodb}/mongodbQuerier.d.ts +7 -18
  93. package/dist/{mongo → mongodb}/mongodbQuerier.js +44 -78
  94. package/dist/mssql/mssqlDialect.d.ts +6 -4
  95. package/dist/mssql/mssqlDialect.js +20 -10
  96. package/dist/mssql/mssqlQuerier.d.ts +2 -2
  97. package/dist/mssql/mssqlQuerier.js +3 -3
  98. package/dist/mssql/mssqlQuerierPool.d.ts +1 -1
  99. package/dist/mssql/mssqlQuerierPool.js +2 -2
  100. package/dist/mysql/mysql2Querier.js +1 -5
  101. package/dist/namingStrategy/defaultNamingStrategy.d.ts +0 -1
  102. package/dist/namingStrategy/defaultNamingStrategy.js +0 -3
  103. package/dist/pglite/pgliteDialect.d.ts +3 -0
  104. package/dist/pglite/pgliteDialect.js +3 -1
  105. package/dist/pglite/pgliteQuerier.d.ts +2 -0
  106. package/dist/pglite/pgliteQuerier.js +4 -0
  107. package/dist/postgres/postgresDialect.d.ts +3 -4
  108. package/dist/postgres/postgresDialect.js +5 -6
  109. package/dist/querier/abstractQuerier.d.ts +119 -36
  110. package/dist/querier/abstractQuerier.js +465 -161
  111. package/dist/querier/abstractQuerierPool.d.ts +5 -6
  112. package/dist/querier/abstractQuerierPool.js +20 -6
  113. package/dist/querier/abstractSqlQuerier.d.ts +15 -10
  114. package/dist/querier/abstractSqlQuerier.js +54 -47
  115. package/dist/querier/abstractSqlQuerierPool.d.ts +5 -3
  116. package/dist/querier/abstractSqlQuerierPool.js +7 -4
  117. package/dist/querier/transaction.d.ts +46 -0
  118. package/dist/querier/transaction.js +56 -0
  119. package/dist/schema/canonicalType.js +2 -2
  120. package/dist/schema/schemaASTDiffer.d.ts +11 -3
  121. package/dist/schema/schemaASTDiffer.js +20 -8
  122. package/dist/sqlite/nodeSqliteQuerierPool.d.ts +1 -1
  123. package/dist/sqlite/nodeSqliteQuerierPool.js +1 -1
  124. package/dist/sqlite/sqliteDialect.d.ts +1 -1
  125. package/dist/sqlite/sqliteDialect.js +3 -1
  126. package/dist/sqlite/sqliteQuerier.d.ts +2 -0
  127. package/dist/sqlite/sqliteQuerier.js +4 -0
  128. package/dist/sqlite/sqliteQuerierPool.d.ts +4 -4
  129. package/dist/sqlite/sqliteQuerierPool.js +1 -1
  130. package/dist/type/dialect.d.ts +16 -2
  131. package/dist/type/entity.d.ts +32 -32
  132. package/dist/type/migration.d.ts +10 -27
  133. package/dist/type/namingStrategy.d.ts +0 -4
  134. package/dist/type/querier.d.ts +18 -10
  135. package/dist/type/query.d.ts +7 -22
  136. package/dist/type/queryRaw.d.ts +11 -6
  137. package/dist/type/queryRaw.js +2 -3
  138. package/dist/type/universalQuerier.d.ts +26 -28
  139. package/dist/type/utility.d.ts +7 -2
  140. package/dist/util/dialect.util.d.ts +2 -2
  141. package/dist/util/dialect.util.js +4 -1
  142. package/dist/util/field.util.d.ts +12 -0
  143. package/dist/util/field.util.js +24 -0
  144. package/dist/util/hook.util.d.ts +3 -2
  145. package/dist/util/query.util.d.ts +5 -0
  146. package/dist/util/query.util.js +34 -1
  147. package/dist/util/raw.d.ts +8 -2
  148. package/dist/util/raw.js +22 -0
  149. package/dist/util/relationQuery.util.d.ts +2 -0
  150. package/dist/util/relationQuery.util.js +4 -0
  151. package/dist/util/sql.util.d.ts +0 -5
  152. package/dist/util/sql.util.js +3 -9
  153. package/dist/util/uqlError.d.ts +0 -6
  154. package/dist/util/uqlError.js +0 -5
  155. package/package.json +20 -26
  156. package/skills/uql-orm/SKILL.md +13 -10
  157. package/dist/migrate/storage/jsonStorage.d.ts +0 -14
  158. package/dist/migrate/storage/jsonStorage.js +0 -33
  159. /package/dist/{maria → mariadb}/index.d.ts +0 -0
  160. /package/dist/{maria → mariadb}/index.js +0 -0
  161. /package/dist/{maria → mariadb}/mariaDialect.d.ts +0 -0
  162. /package/dist/{maria → mariadb}/mariaDialect.js +0 -0
  163. /package/dist/{maria → mariadb}/mariadbQuerier.d.ts +0 -0
  164. /package/dist/{maria → mariadb}/mariadbQuerierPool.d.ts +0 -0
  165. /package/dist/{maria → mariadb}/mariadbQuerierPool.js +0 -0
  166. /package/dist/{mongo → mongodb}/mongoDialect.d.ts +0 -0
  167. /package/dist/{mongo → mongodb}/mongoIntrospector.d.ts +0 -0
  168. /package/dist/{mongo → mongodb}/mongoQuerier.js +0 -0
  169. /package/dist/{mongo → mongodb}/mongodbQuerierPool.d.ts +0 -0
  170. /package/dist/{mongo → mongodb}/mongodbQuerierPool.js +0 -0
  171. /package/dist/{mongo → mongodb}/textLanguage.d.ts +0 -0
  172. /package/dist/{mongo → mongodb}/textLanguage.js +0 -0
  173. /package/dist/{mongo → mongodb}/vectorDistance.d.ts +0 -0
  174. /package/dist/{mongo → mongodb}/vectorDistance.js +0 -0
@@ -3,22 +3,24 @@ import { basename, extname, join } from 'node:path';
3
3
  import { pathToFileURL } from 'node:url';
4
4
  import { getEntities, getMeta } from '../entity/index.js';
5
5
  import { SchemaAST } from '../schema/schemaAST.js';
6
- import { columnRenames, tableRenameCandidates } from '../schema/schemaASTDiffer.js';
6
+ import { columnRenameCandidates, columnRenames, tableRenameCandidates, } from '../schema/schemaASTDiffer.js';
7
7
  import { definedEntries, isRecord, LoggerWrapper } from '../util/index.js';
8
+ import { raw } from '../util/raw.js';
8
9
  import { isOwnedName, qualifyName } from '../util/sql.util.js';
9
10
  import { UqlUsageError } from '../util/uqlError.js';
10
11
  import { withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
11
12
  import { buildMigrationModule } from './codegen/migrationFile.js';
12
13
  import { introspectorFor } from './introspection/registry.js';
13
- import { migrationBuilderFor, migrationTargetFor } from './migrationTarget.js';
14
+ import { DEFAULT_LOCK_TIMEOUT } from './migrationLock.js';
15
+ import { migrationBuilderFor, migrationTargetFor, } from './migrationTarget.js';
14
16
  import { dropped, lacksValue, newlyRequired, nonEmpty, reverseDiff, sides, withoutRebuild } from './schemaChange.js';
15
- import { constraintNameOf } from './schemaGenerator.js';
17
+ import { constraintNameOf, dropsForeignKeysFirst } from './schemaGenerator.js';
18
+ import { DEFAULT_MIGRATIONS_TABLE } from './storage/databaseStorage.js';
16
19
  /**
17
20
  * Main class for managing database migrations
18
21
  */
19
22
  export class Migrator {
20
23
  pool;
21
- storage;
22
24
  migrationsPath;
23
25
  logger;
24
26
  _entities;
@@ -29,15 +31,22 @@ export class Migrator {
29
31
  schemaGenerator;
30
32
  schemaIntrospector;
31
33
  target;
34
+ lock;
35
+ /** The journal of the migrations run: a table, or a collection on MongoDB. */
36
+ storage;
32
37
  constructor(pool, options = {}) {
33
38
  this.pool = pool;
34
39
  this.target = migrationTargetFor(pool, options.defaultForeignKeyAction);
35
- this.storage = options.storage ?? this.target.storage(options.tableName);
40
+ this.storage = this.target.storage(options.tableName);
36
41
  this.migrationsPath = options.migrationsPath ?? './migrations';
37
42
  this.logger = new LoggerWrapper(options.logger, { logValues: options.logValues, slowQuery: options.slowQuery });
38
43
  this._entities = options.entities;
39
44
  this.schemaIntrospector = introspectorFor(pool);
40
45
  this.schemaGenerator = options.schemaGenerator;
46
+ this.lock = {
47
+ name: options.tableName ?? DEFAULT_MIGRATIONS_TABLE,
48
+ timeout: options.lockTimeout ?? DEFAULT_LOCK_TIMEOUT,
49
+ };
41
50
  }
42
51
  /** The schema generator, loaded on first use: MongoDB's needs its optional peer. */
43
52
  async getSchemaGenerator() {
@@ -45,57 +54,55 @@ export class Migrator {
45
54
  return this.schemaGenerator;
46
55
  }
47
56
  /**
48
- * Get all discovered migrations from the migrations directory
57
+ * The migration files by name, the names the storage records as run, and those on disk it does not, all in
58
+ * name order. Read from names alone: a file is imported only when it is about to run.
49
59
  */
50
- async getMigrations() {
51
- const files = await this.getMigrationFiles();
52
- const migrations = [];
53
- for (const file of files) {
54
- const migration = await this.loadMigration(file);
55
- if (migration) {
56
- migrations.push(migration);
57
- }
58
- }
59
- // Sort by name (which typically includes timestamp)
60
- return migrations.sort((a, b) => a.name.localeCompare(b.name));
61
- }
62
- /** The migrations on disk the storage records as run (`applied`) or not (`pending`), and every name it records. */
63
- async journal() {
64
- const [migrations, executed] = await Promise.all([this.getMigrations(), this.storage.executed()]);
60
+ async journal(recorded) {
61
+ const files = await this.migrationFiles();
62
+ const executed = recorded.toSorted();
65
63
  const ran = new Set(executed);
66
- return {
67
- executed,
68
- applied: migrations.filter((migration) => ran.has(migration.name)),
69
- pending: migrations.filter((migration) => !ran.has(migration.name)),
70
- };
64
+ return { files, executed, pending: [...files.keys()].sort().filter((name) => !ran.has(name)) };
71
65
  }
72
- /** The migrations not yet run. */
73
- async pending() {
74
- return (await this.journal()).pending;
66
+ /**
67
+ * {@link journal} read without the lock, so a run holding it never holds a reader up. Only a run creates the
68
+ * journal, under the lock, so one not created yet has recorded nothing.
69
+ */
70
+ async unlockedJournal() {
71
+ const recorded = (await this.schemaIntrospector.tableExists(this.lock.name))
72
+ ? await this.target.withSession(({ querier }) => this.storage.executed(querier))
73
+ : [];
74
+ return this.journal(recorded);
75
75
  }
76
76
  /**
77
- * Get list of executed migrations
77
+ * Runs the pending migrations, up to `to` or `step` of them, each in a transaction of its own where the
78
+ * engine has one for its statements, and throws the first one's error, those before it staying applied.
79
+ * It holds the migration lock throughout, so a second run waits, then finds them run.
78
80
  */
79
- async executed() {
80
- return this.storage.executed();
81
+ up(options = {}) {
82
+ return this.migrate('up', options);
81
83
  }
82
84
  /**
83
- * Run all pending migrations
85
+ * Reverts the migrations run, latest first, as {@link up} runs them: down to `to`, or `step` of them, the last
86
+ * one alone where it names neither. `step: Infinity` reverts them all.
84
87
  */
85
- async up(options = {}) {
86
- return this.runInOrder(await this.pending(), 'up', options);
88
+ down({ to, step = to ? undefined : 1 } = {}) {
89
+ return this.migrate('down', { to, step });
87
90
  }
88
91
  /**
89
- * Rollback migrations
92
+ * Holding the lock, runs the names narrowed by `to`/`step`, stopping at the first failure: `up` over the
93
+ * pending, `down` over the executed reversed. Every one is loaded before any runs, so a file that cannot be
94
+ * leaves the database as it was.
90
95
  */
91
- async down(options = {}) {
92
- return this.runInOrder((await this.journal()).applied.reverse(), 'down', options);
96
+ migrate(direction, options) {
97
+ return this.target.withLockedSession(this.lock, async (session) => {
98
+ const { files, pending, executed } = await this.journal(await this.storage.executed(session.querier));
99
+ return this.runInOrder(session, files, direction === 'up' ? pending : executed.reverse(), direction, options);
100
+ });
93
101
  }
94
- /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
95
- async runInOrder(migrations, direction, options) {
96
- let selected = migrations;
102
+ async runInOrder(session, files, names, direction, options) {
103
+ let selected = names;
97
104
  if (options.to) {
98
- const toIndex = selected.findIndex((m) => m.name === options.to);
105
+ const toIndex = selected.indexOf(options.to);
99
106
  if (toIndex === -1) {
100
107
  throw new UqlUsageError(`Migration '${options.to}' not found`);
101
108
  }
@@ -104,52 +111,40 @@ export class Migrator {
104
111
  if (options.step !== undefined) {
105
112
  selected = selected.slice(0, options.step);
106
113
  }
114
+ const migrations = await Promise.all(selected.map((name) => this.loadMigration(name, files.get(name))));
107
115
  const results = [];
108
- for (const migration of selected) {
109
- const result = await this.runMigration(migration, direction);
110
- results.push(result);
111
- if (!result.success) {
112
- break;
113
- }
116
+ for (const migration of migrations) {
117
+ results.push(await this.runMigration(session, migration, direction));
114
118
  }
115
119
  return results;
116
120
  }
117
121
  /**
118
- * Run a single migration, in a transaction where the dialect has one for it and the migration has not
119
- * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
122
+ * Runs one migration, in a transaction where the dialect has one for it and the migration has not declared
123
+ * `transaction: false` - the opt-out a statement an engine refuses inside one needs.
120
124
  */
121
- async runMigration(migration, direction) {
125
+ async runMigration({ querier, transaction }, migration, direction) {
122
126
  const startTime = Date.now();
123
- const finished = (error) => ({
124
- name: migration.name,
125
- direction,
126
- duration: Date.now() - startTime,
127
- success: error === undefined,
128
- ...(error && { error }),
129
- });
130
- return this.target.withSession(async ({ querier, transaction }) => {
131
- try {
132
- this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
133
- const work = async () => {
134
- if (direction === 'up') {
135
- await migration.up(querier);
136
- await this.storage.logWithQuerier(querier, migration.name);
137
- }
138
- else {
139
- await migration.down(querier);
140
- await this.storage.unlogWithQuerier(querier, migration.name);
141
- }
142
- };
143
- await (migration.transaction === false ? work() : transaction(work));
144
- const result = finished();
145
- this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${result.duration}ms`);
146
- return result;
127
+ this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
128
+ const work = async () => {
129
+ if (direction === 'up') {
130
+ await migration.up(querier);
131
+ await this.storage.logWithQuerier(querier, migration.name);
147
132
  }
148
- catch (error) {
149
- this.logger.logError(`Migration ${migration.name} failed: ${error.message}`, error);
150
- return finished(error);
133
+ else {
134
+ await migration.down(querier);
135
+ await this.storage.unlogWithQuerier(querier, migration.name);
151
136
  }
152
- });
137
+ };
138
+ try {
139
+ await (migration.transaction === false ? work() : transaction(work));
140
+ }
141
+ catch (error) {
142
+ this.logger.logError(`Migration ${migration.name} failed: ${error.message}`, error);
143
+ throw error;
144
+ }
145
+ const duration = Date.now() - startTime;
146
+ this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${duration}ms`);
147
+ return { name: migration.name, direction, duration };
153
148
  }
154
149
  /**
155
150
  * Generate a new migration file
@@ -238,7 +233,7 @@ export class Migrator {
238
233
  const found = [];
239
234
  for (const { tableName, column, nullable } of counts) {
240
235
  const empty = nullable ? ` WHERE ${escapeId(column)} IS NULL` : '';
241
- const [{ rows }] = await querier.all(`SELECT COUNT(*) AS ${escapeId('rows')} FROM ${escapeId(tableName)}${empty}`);
236
+ const [{ rows }] = await querier.all(raw.text(`SELECT COUNT(*) AS ${escapeId('rows')} FROM ${escapeId(tableName)}${empty}`));
242
237
  const count = Number(rows);
243
238
  if (count) {
244
239
  found.push(`"${tableName}"."${column}" is required with no default, and ${count} ${count === 1 ? 'row holds' : 'rows hold'} none`);
@@ -272,14 +267,14 @@ export class Migrator {
272
267
  return this.pool.dialect.resolveTableName(getMeta(entity));
273
268
  }
274
269
  /**
275
- * The differences between the entities and the database. With `renames`, a column identical to one the
276
- * entity no longer names is renamed in place rather than dropped and added, as a generated migration wants.
270
+ * The differences between the entities and the database. With `renames`, as a generated migration wants, a
271
+ * column whose name another naming strategy spells is renamed in place rather than dropped and added.
277
272
  */
278
273
  async getDiffs(options = {}) {
279
274
  const generator = await this.getSchemaGenerator();
280
275
  // Both sides built once: the database's here, the entities' below. Left to `diffSchema`, each
281
276
  // entity would rebuild the whole AST, which is quadratic in the number of entities. Absent on a
282
- // generator that compares no schema of its own - MongoDB, which reads only indexes.
277
+ // generator that compares no schema of its own - MongoDB, which reads only indexes and a validator.
283
278
  const desiredAst = generator.buildAST?.(this.entities);
284
279
  let ast = await this.introspectEntities(this.entities);
285
280
  const diffOptions = generator.diffOptions?.();
@@ -291,12 +286,26 @@ export class Migrator {
291
286
  if (desiredAst) {
292
287
  this.noteForeignChecks(desiredAst, ast);
293
288
  }
289
+ if (options.renames && desiredAst && diffOptions) {
290
+ this.noteRenameCandidates(desiredAst, ast, diffOptions);
291
+ }
294
292
  return this.entities.flatMap((entity) => {
295
293
  const tableName = this.tableOf(entity);
296
294
  const diff = generator.diffSchema(entity, ast.getTable(tableName), desiredAst, renames.get(tableName));
297
295
  return diff ? [diff] : [];
298
296
  });
299
297
  }
298
+ /**
299
+ * Each column dropped while one identical to it but for its name is added: maybe a rename, which only its
300
+ * author can tell, so it is suggested and never written. A wrong guess would carry its data into a column
301
+ * meant for other data.
302
+ */
303
+ noteRenameCandidates(desired, actual, options) {
304
+ for (const { table, from, to } of columnRenameCandidates(desired, actual, options)) {
305
+ this.logger.logWarn(`"${to}" is identical to "${table}"."${from}", which this migration drops: if one was renamed to the ` +
306
+ `other, replace both with \`renameColumn('${table}', '${from}', '${to}')\`, which keeps its data.`);
307
+ }
308
+ }
300
309
  /**
301
310
  * Each check uql did not install on a table whose entity declares checks: never changed or dropped, so
302
311
  * one an owned check replaces, such as an enum's from before checks were named, goes on enforcing itself.
@@ -310,15 +319,28 @@ export class Migrator {
310
319
  }
311
320
  }
312
321
  }
322
+ /** Which of the tables `entities` name exist, by qualified name: one catalogue read per schema. */
323
+ async presentTables(entities) {
324
+ const present = new Set();
325
+ for (const schema of this.entitiesBySchema(entities).keys()) {
326
+ for (const name of await this.schemaIntrospectorFor(schema).getTableNames()) {
327
+ present.add(qualifyName(name, schema));
328
+ }
329
+ }
330
+ return present;
331
+ }
332
+ entitiesBySchema(entities) {
333
+ const { dialect } = this.pool;
334
+ return Map.groupBy(new Set(entities), (entity) => dialect.resolveSchema(getMeta(entity)));
335
+ }
313
336
  /**
314
337
  * The tables `entities` name, read a schema at a time so each is keyed as its entity spells it. Those
315
338
  * alone: nothing else is diffed, and another table can be dropped mid-scan by whatever else is running.
316
339
  */
317
340
  async introspectEntities(entities, renames) {
318
341
  const { dialect } = this.pool;
319
- const bySchema = Map.groupBy(new Set(entities), (entity) => dialect.resolveSchema(getMeta(entity)));
320
342
  const merged = new SchemaAST();
321
- for (const [schema, members] of bySchema) {
343
+ for (const [schema, members] of this.entitiesBySchema(entities)) {
322
344
  const tables = members.map((entity) => dialect.resolveTableAlias(getMeta(entity)));
323
345
  for (const table of (await this.schemaIntrospectorFor(schema).introspect(tables, renames)).getTables()) {
324
346
  merged.addTable(table);
@@ -336,11 +358,18 @@ export class Migrator {
336
358
  this.logger.logSchema('Schema is already in sync.');
337
359
  }
338
360
  }
339
- /** Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph order. */
361
+ /**
362
+ * Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph
363
+ * order. Only where a drop leaves its foreign keys behind are the tables read beyond whether they exist.
364
+ */
340
365
  async forceStatements(generator) {
341
- const existing = await this.introspectEntities(this.entities);
366
+ const drop = { ifExists: true, cascade: true };
367
+ const present = await this.presentTables(this.entities);
368
+ const existing = dropsForeignKeysFirst(this.pool.dialect.features, drop)
369
+ ? await this.introspectEntities(this.entities)
370
+ : undefined;
342
371
  return [
343
- ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true, existing }),
372
+ ...generator.generateDropSchema(this.entities, { ...drop, present, existing }),
344
373
  ...generator.generateCreateSchema(this.entities),
345
374
  ];
346
375
  }
@@ -467,63 +496,57 @@ export class Migrator {
467
496
  if (options.logging)
468
497
  this.logger.logSchema('Schema synchronization completed');
469
498
  }
470
- /**
471
- * Get migration status
472
- */
499
+ /** The names of the migrations pending and run, read without the lock. */
473
500
  async status() {
474
- const { pending, executed } = await this.journal();
475
- return { pending: pending.map((migration) => migration.name), executed };
501
+ const { pending, executed } = await this.unlockedJournal();
502
+ return { pending, executed };
476
503
  }
477
- /**
478
- * Get migration files from the migrations directory
479
- */
480
- async getMigrationFiles() {
504
+ /** The migration files in the migrations directory, by the name each runs as; none where it is missing. */
505
+ async migrationFiles() {
506
+ let entries;
481
507
  try {
482
- const files = await readdir(this.migrationsPath);
483
- return files
484
- .filter((f) => /\.(ts|js|mjs)$/.test(f))
485
- .filter((f) => !f.endsWith('.d.ts'))
486
- .sort();
508
+ entries = await readdir(this.migrationsPath);
487
509
  }
488
510
  catch (error) {
489
511
  if (error.code === 'ENOENT') {
490
- return [];
512
+ return new Map();
491
513
  }
492
514
  throw error;
493
515
  }
494
- }
495
- /**
496
- * Load a migration from a file
497
- */
498
- async loadMigration(fileName) {
499
- const filePath = join(this.migrationsPath, fileName);
500
- const fileUrl = pathToFileURL(filePath).href;
501
- try {
502
- const module = await import(fileUrl);
503
- const migration = module.default ?? module;
504
- if (this.isMigration(migration)) {
505
- return {
506
- name: basename(fileName, extname(fileName)),
507
- up: migration.up.bind(migration),
508
- down: migration.down.bind(migration),
509
- transaction: migration.transaction,
510
- };
516
+ const files = new Map();
517
+ for (const file of entries.filter((entry) => /\.(ts|js|mjs)$/.test(entry) && !entry.endsWith('.d.ts'))) {
518
+ const name = basename(file, extname(file));
519
+ const other = files.get(name);
520
+ if (other) {
521
+ throw new UqlUsageError(`Migrations ${other} and ${file} share the name '${name}'`);
511
522
  }
512
- this.logger.logWarn(`Warning: ${fileName} is not a valid migration`);
513
- return undefined;
514
- }
515
- catch (error) {
516
- this.logger.logError(`Error loading migration ${fileName}: ${error.message}`, error);
517
- return undefined;
523
+ files.set(name, file);
518
524
  }
525
+ return files;
519
526
  }
520
- /**
521
- * Check if an object is a valid migration
522
- */
523
- isMigration(obj) {
524
- return isRecord(obj) && typeof obj['up'] === 'function' && typeof obj['down'] === 'function';
527
+ /** The migration `name`, from its `file`: a missing file, one that fails to import, or one exporting no migration throws. */
528
+ async loadMigration(name, file) {
529
+ if (!file) {
530
+ throw new UqlUsageError(`Migration '${name}' is recorded as run but has no file in ${this.migrationsPath}`);
531
+ }
532
+ const module = await import(pathToFileURL(join(this.migrationsPath, file)).href).catch((error) => {
533
+ throw new UqlUsageError(`Migration ${file} failed to load: ${error.message}`, { cause: error });
534
+ });
535
+ const migration = module.default ?? module;
536
+ if (!isMigrationDefinition(migration)) {
537
+ throw new UqlUsageError(`Migration ${file} exports no migration: \`up\` and \`down\` functions, as its default export or its own`);
538
+ }
539
+ return {
540
+ name,
541
+ up: migration.up.bind(migration),
542
+ down: migration.down.bind(migration),
543
+ transaction: migration.transaction,
544
+ };
525
545
  }
526
546
  }
547
+ function isMigrationDefinition(value) {
548
+ return isRecord(value) && typeof value['up'] === 'function' && typeof value['down'] === 'function';
549
+ }
527
550
  /** The local time a migration file is named by, `YYYYMMDDHHmmss`, so names sort in the order they were made. */
528
551
  function timestamp() {
529
552
  const now = new Date();
@@ -2,7 +2,7 @@ import type { AbstractSqlDialect } from '../dialect/index.js';
2
2
  import type { SchemaAST } from '../schema/schemaAST.js';
3
3
  import { type DiffOptions } from '../schema/schemaASTDiffer.js';
4
4
  import { type ForeignKeyAction, type TableNode } from '../schema/types.js';
5
- import type { CreateSchemaOptions, DropSchemaOptions, ForeignKeySchema, Rename, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
5
+ import type { CreateSchemaOptions, DialectFeatures, DropSchemaOptions, ForeignKeySchema, Rename, SchemaDiff, SchemaGenerator, Type } from '../type/index.js';
6
6
  import type { AnyMigrationOperation, TableDefinition } from './builder/types.js';
7
7
  import { type IndexDdl, type TableDdl } from './ddl/index.js';
8
8
  /** The SQL schema generator, one for every SQL engine, its spellings taken from the dialect and its DDL classes. */
@@ -118,6 +118,8 @@ export declare class SqlSchemaGenerator implements SchemaGenerator {
118
118
  */
119
119
  private assertAlterable;
120
120
  }
121
+ /** Whether a drop leaves foreign keys to drop first: a `CASCADE` takes them along, and SQLite drops with its constraints off. */
122
+ export declare function dropsForeignKeysFirst(features: DialectFeatures, options: Pick<DropSchemaOptions, 'cascade'>): boolean;
121
123
  /**
122
124
  * What a constraint is called: its own name, or one derived from its columns where nothing named it.
123
125
  * Shared by the add and the drop so a `DROP CONSTRAINT` names exactly what an `ADD CONSTRAINT` made.
@@ -103,9 +103,7 @@ export class SqlSchemaGenerator {
103
103
  */
104
104
  generateDropSchema(entities, options = {}) {
105
105
  const tables = this.orderedTables(entities, 'drop');
106
- // A `CASCADE` drop takes the foreign keys with it, and SQLite drops with its constraints off.
107
- const cascades = options.cascade && this.features.dropTableCascade;
108
- const existing = cascades || this.features.rebuildsTables ? [] : (options.existing?.getTables() ?? []);
106
+ const existing = dropsForeignKeysFirst(this.features, options) ? (options.existing?.getTables() ?? []) : [];
109
107
  const foreignKeyDrops = existing.flatMap((table) => {
110
108
  const tableName = qualifyName(table.name, table.schema);
111
109
  const names = [
@@ -119,7 +117,7 @@ export class SqlSchemaGenerator {
119
117
  ...tables.flatMap((table) => {
120
118
  const name = qualifyName(table.name, table.schema);
121
119
  // A table the database lacks left no function: CockroachDB refuses one named in a schema not made yet.
122
- const triggers = options.existing && !options.existing.getTable(name) ? [] : table.triggers;
120
+ const triggers = options.present && !options.present.has(name) ? [] : table.triggers;
123
121
  return [
124
122
  this.dropTableSql(name, options),
125
123
  ...terminated(triggers.flatMap((trigger) => dropTriggerBody(this.dialect, table.schema, trigger.name))),
@@ -341,12 +339,17 @@ export class SqlSchemaGenerator {
341
339
  const declaredByColumn = this.dialect.features.serialDeclaresPrimaryKey &&
342
340
  key?.columns.length === 1 &&
343
341
  table.columns.get(key.columns[0])?.isAutoIncrement;
342
+ const inline = new Map(table.indexes.flatMap((index) => {
343
+ const definition = this.indexDdl.inlineDefinition(indexNodeToSchema(index));
344
+ return definition ? [[index, definition]] : [];
345
+ }));
344
346
  const definitions = [
345
347
  ...[...table.columns.values()].map((column) => this.tableDdl.columnDefinition(this.columnNodeToSchema(column))),
346
348
  ...(key && !declaredByColumn ? [this.tableDdl.primaryKeyConstraint(table.name, key)] : []),
347
349
  ...table.checks.map((check) => this.checkConstraint(check)),
348
350
  ...table.outgoingRelations.map((relation) => this.foreignKeyConstraint(table.name, foreignKeyOf(relation), this.dialect.escapeQualifiedId(relation.to.table.name, relation.to.table.schema))),
349
351
  ...table.externalForeignKeys.map((foreignKey) => this.foreignKeyConstraint(table.name, foreignKey, this.escapeId(foreignKey.references.table))),
352
+ ...inline.values(),
350
353
  ];
351
354
  const target = this.dialect.escapeQualifiedId(table.name, table.schema);
352
355
  const body = definitions.map((definition) => ` ${definition}`).join(',\n');
@@ -360,7 +363,9 @@ export class SqlSchemaGenerator {
360
363
  ...this.tableDdl.commentStatements(qualifyName(table.name, table.schema), table.comment, [
361
364
  ...table.columns.values(),
362
365
  ]),
363
- ...table.indexes.map((index) => this.createIndexFromNode(index, indexOptions)),
366
+ ...table.indexes
367
+ .filter((index) => !inline.has(index))
368
+ .map((index) => this.createIndexFromNode(index, indexOptions)),
364
369
  ];
365
370
  }
366
371
  /** The `CREATE INDEX` for an index of the AST. */
@@ -452,6 +457,10 @@ export class SqlSchemaGenerator {
452
457
  }
453
458
  }
454
459
  }
460
+ /** Whether a drop leaves foreign keys to drop first: a `CASCADE` takes them along, and SQLite drops with its constraints off. */
461
+ export function dropsForeignKeysFirst(features, options) {
462
+ return !(options.cascade && features.dropTableCascade) && !features.rebuildsTables;
463
+ }
455
464
  /** Statements as a migration runs them, each ended. */
456
465
  function terminated(statements) {
457
466
  return statements.map((sql) => `${sql};`);
@@ -1,31 +1,39 @@
1
- import type { MigrationStorage, QuerierPool, SqlQuerier } from '../../type/index.js';
1
+ import type { Querier, QueryRaw, SqlQuerier } from '../../type/index.js';
2
2
  /** Where executed migrations are recorded when the config does not name a table. */
3
3
  export declare const DEFAULT_MIGRATIONS_TABLE = "uql_migrations";
4
4
  /**
5
- * Stores migration state in a database table.
6
- * Uses the querier's dialect for escaping and placeholders.
5
+ * The journal record a run holds the lock by where the engine has no named lock (`migrationLock.ts`). No
6
+ * file name holds a slash, so no migration is named so.
7
7
  */
8
+ export declare const LOCK_RECORD = "uql/lock";
9
+ /** The journal of the migrations run, each call on the querier the run holds the lock with. */
10
+ export interface MigrationStorage {
11
+ executed(querier: Querier): Promise<string[]>;
12
+ /** Inside the migration's transaction, where it has one. */
13
+ logWithQuerier(querier: Querier, migrationName: string): Promise<void>;
14
+ unlogWithQuerier(querier: Querier, migrationName: string): Promise<void>;
15
+ }
16
+ /**
17
+ * Creates the journal `tableName` where it is missing, rendered by the schema generator rather than written
18
+ * out: SQL Server has no `CREATE TABLE IF NOT EXISTS`, and its `TIMESTAMP` is a row version that takes no
19
+ * default. Run under the migration lock, so two runs never race to create it.
20
+ */
21
+ export declare function createMigrationsTable(querier: SqlQuerier, tableName: string): Promise<void>;
22
+ /** Records the migrations run in a table, on the querier each call is handed, which the lock created. */
8
23
  export declare class DatabaseMigrationStorage implements MigrationStorage {
9
- private readonly pool;
10
24
  private readonly tableName;
11
- private storageInitialized;
12
- constructor(pool: QuerierPool, options?: {
25
+ constructor(options?: {
13
26
  tableName?: string;
14
27
  });
15
- /** Creates the table on first use, once. */
16
- private ensureStorage;
17
- /**
18
- * Rendered by the schema generator rather than written out, so each engine gets its own spelling: SQL
19
- * Server has no `CREATE TABLE IF NOT EXISTS`, and its `TIMESTAMP` is a row version that takes no default.
20
- */
21
- private createTableIfNotExists;
22
- executed(): Promise<string[]>;
23
- /**
24
- * Log a migration as executed - uses provided querier (within transaction)
25
- */
28
+ /** The names recorded, the lock's left out. */
29
+ executed(querier: SqlQuerier): Promise<string[]>;
30
+ /** Records `migrationName` as run, on the querier that ran it, inside its transaction where there is one. */
26
31
  logWithQuerier(querier: SqlQuerier, migrationName: string): Promise<void>;
27
- /**
28
- * Unlog a migration - uses provided querier (within transaction)
29
- */
32
+ /** Removes the record of `migrationName`, on the querier that reverted it. */
30
33
  unlogWithQuerier(querier: SqlQuerier, migrationName: string): Promise<void>;
31
34
  }
35
+ /** The journal `tableName` and its one column, escaped as `querier`'s engine spells them. */
36
+ export declare function journalIds({ dialect }: SqlQuerier, tableName: string): {
37
+ table: QueryRaw;
38
+ name: QueryRaw;
39
+ };