uql-orm 0.99.0 → 0.100.1

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 +11 -1
  45. package/dist/migrate/cli-config.js +20 -6
  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 +39 -23
  74. package/dist/migrate/migrator.js +110 -74
  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() {
@@ -48,41 +57,49 @@ export class Migrator {
48
57
  * The migration files by name, the names the storage records as run, and those on disk it does not, all in
49
58
  * name order. Read from names alone: a file is imported only when it is about to run.
50
59
  */
51
- async journal() {
52
- const [files, recorded] = await Promise.all([this.migrationFiles(), this.storage.executed()]);
60
+ async journal(recorded) {
61
+ const files = await this.migrationFiles();
53
62
  const executed = recorded.toSorted();
54
63
  const ran = new Set(executed);
55
64
  return { files, executed, pending: [...files.keys()].sort().filter((name) => !ran.has(name)) };
56
65
  }
57
- /** The names of the migrations not yet run, in the order `up` runs them. */
58
- async pending() {
59
- return (await this.journal()).pending;
60
- }
61
66
  /**
62
- * Get list of executed migrations
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.
63
69
  */
64
- async executed() {
65
- return this.storage.executed();
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);
66
75
  }
67
76
  /**
68
- * Run all pending 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.
69
80
  */
70
- async up(options = {}) {
71
- const { files, pending } = await this.journal();
72
- return this.runInOrder(files, pending, 'up', options);
81
+ up(options = {}) {
82
+ return this.migrate('up', options);
73
83
  }
74
84
  /**
75
- * Rollback 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.
76
87
  */
77
- async down(options = {}) {
78
- const { files, executed } = await this.journal();
79
- return this.runInOrder(files, executed.reverse(), 'down', options);
88
+ down({ to, step = to ? undefined : 1 } = {}) {
89
+ return this.migrate('down', { to, step });
80
90
  }
81
91
  /**
82
- * Runs the names narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over
83
- * the executed reversed. Every one is loaded before any runs, so a file that cannot be leaves the database as it was.
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.
84
95
  */
85
- async runInOrder(files, names, direction, 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
+ });
101
+ }
102
+ async runInOrder(session, files, names, direction, options) {
86
103
  let selected = names;
87
104
  if (options.to) {
88
105
  const toIndex = selected.indexOf(options.to);
@@ -97,50 +114,37 @@ export class Migrator {
97
114
  const migrations = await Promise.all(selected.map((name) => this.loadMigration(name, files.get(name))));
98
115
  const results = [];
99
116
  for (const migration of migrations) {
100
- const result = await this.runMigration(migration, direction);
101
- results.push(result);
102
- if (!result.success) {
103
- break;
104
- }
117
+ results.push(await this.runMigration(session, migration, direction));
105
118
  }
106
119
  return results;
107
120
  }
108
121
  /**
109
- * Run a single migration, in a transaction where the dialect has one for it and the migration has not
110
- * 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.
111
124
  */
112
- async runMigration(migration, direction) {
125
+ async runMigration({ querier, transaction }, migration, direction) {
113
126
  const startTime = Date.now();
114
- const finished = (error) => ({
115
- name: migration.name,
116
- direction,
117
- duration: Date.now() - startTime,
118
- success: error === undefined,
119
- ...(error && { error }),
120
- });
121
- return this.target.withSession(async ({ querier, transaction }) => {
122
- try {
123
- this.logger.logMigration(`${direction === 'up' ? 'Running' : 'Reverting'} migration: ${migration.name}`);
124
- const work = async () => {
125
- if (direction === 'up') {
126
- await migration.up(querier);
127
- await this.storage.logWithQuerier(querier, migration.name);
128
- }
129
- else {
130
- await migration.down(querier);
131
- await this.storage.unlogWithQuerier(querier, migration.name);
132
- }
133
- };
134
- await (migration.transaction === false ? work() : transaction(work));
135
- const result = finished();
136
- this.logger.logMigration(`Migration ${migration.name} ${direction === 'up' ? 'applied' : 'reverted'} in ${result.duration}ms`);
137
- 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);
138
132
  }
139
- catch (error) {
140
- this.logger.logError(`Migration ${migration.name} failed: ${error.message}`, error);
141
- return finished(error);
133
+ else {
134
+ await migration.down(querier);
135
+ await this.storage.unlogWithQuerier(querier, migration.name);
142
136
  }
143
- });
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 };
144
148
  }
145
149
  /**
146
150
  * Generate a new migration file
@@ -229,7 +233,7 @@ export class Migrator {
229
233
  const found = [];
230
234
  for (const { tableName, column, nullable } of counts) {
231
235
  const empty = nullable ? ` WHERE ${escapeId(column)} IS NULL` : '';
232
- 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}`));
233
237
  const count = Number(rows);
234
238
  if (count) {
235
239
  found.push(`"${tableName}"."${column}" is required with no default, and ${count} ${count === 1 ? 'row holds' : 'rows hold'} none`);
@@ -263,14 +267,14 @@ export class Migrator {
263
267
  return this.pool.dialect.resolveTableName(getMeta(entity));
264
268
  }
265
269
  /**
266
- * The differences between the entities and the database. With `renames`, a column identical to one the
267
- * 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.
268
272
  */
269
273
  async getDiffs(options = {}) {
270
274
  const generator = await this.getSchemaGenerator();
271
275
  // Both sides built once: the database's here, the entities' below. Left to `diffSchema`, each
272
276
  // entity would rebuild the whole AST, which is quadratic in the number of entities. Absent on a
273
- // 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.
274
278
  const desiredAst = generator.buildAST?.(this.entities);
275
279
  let ast = await this.introspectEntities(this.entities);
276
280
  const diffOptions = generator.diffOptions?.();
@@ -282,12 +286,26 @@ export class Migrator {
282
286
  if (desiredAst) {
283
287
  this.noteForeignChecks(desiredAst, ast);
284
288
  }
289
+ if (options.renames && desiredAst && diffOptions) {
290
+ this.noteRenameCandidates(desiredAst, ast, diffOptions);
291
+ }
285
292
  return this.entities.flatMap((entity) => {
286
293
  const tableName = this.tableOf(entity);
287
294
  const diff = generator.diffSchema(entity, ast.getTable(tableName), desiredAst, renames.get(tableName));
288
295
  return diff ? [diff] : [];
289
296
  });
290
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
+ }
291
309
  /**
292
310
  * Each check uql did not install on a table whose entity declares checks: never changed or dropped, so
293
311
  * one an owned check replaces, such as an enum's from before checks were named, goes on enforcing itself.
@@ -301,15 +319,28 @@ export class Migrator {
301
319
  }
302
320
  }
303
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
+ }
304
336
  /**
305
337
  * The tables `entities` name, read a schema at a time so each is keyed as its entity spells it. Those
306
338
  * alone: nothing else is diffed, and another table can be dropped mid-scan by whatever else is running.
307
339
  */
308
340
  async introspectEntities(entities, renames) {
309
341
  const { dialect } = this.pool;
310
- const bySchema = Map.groupBy(new Set(entities), (entity) => dialect.resolveSchema(getMeta(entity)));
311
342
  const merged = new SchemaAST();
312
- for (const [schema, members] of bySchema) {
343
+ for (const [schema, members] of this.entitiesBySchema(entities)) {
313
344
  const tables = members.map((entity) => dialect.resolveTableAlias(getMeta(entity)));
314
345
  for (const table of (await this.schemaIntrospectorFor(schema).introspect(tables, renames)).getTables()) {
315
346
  merged.addTable(table);
@@ -327,11 +358,18 @@ export class Migrator {
327
358
  this.logger.logSchema('Schema is already in sync.');
328
359
  }
329
360
  }
330
- /** 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
+ */
331
365
  async forceStatements(generator) {
332
- 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;
333
371
  return [
334
- ...generator.generateDropSchema(this.entities, { ifExists: true, cascade: true, existing }),
372
+ ...generator.generateDropSchema(this.entities, { ...drop, present, existing }),
335
373
  ...generator.generateCreateSchema(this.entities),
336
374
  ];
337
375
  }
@@ -458,11 +496,9 @@ export class Migrator {
458
496
  if (options.logging)
459
497
  this.logger.logSchema('Schema synchronization completed');
460
498
  }
461
- /**
462
- * Get migration status
463
- */
499
+ /** The names of the migrations pending and run, read without the lock. */
464
500
  async status() {
465
- const { pending, executed } = await this.journal();
501
+ const { pending, executed } = await this.unlockedJournal();
466
502
  return { pending, executed };
467
503
  }
468
504
  /** The migration files in the migrations directory, by the name each runs as; none where it is missing. */
@@ -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
+ };
@@ -1,69 +1,51 @@
1
- import { currentTimestamp } from '../../util/raw.js';
2
- import { withSqlQuerierForMigrations } from '../acquireQuerierForMigrations.js';
3
- import { TableBuilder } from '../builder/tableBuilder.js';
1
+ import { currentTimestamp, raw } from '../../util/raw.js';
2
+ import { TableDefinitionBuilder } from '../builder/tableBuilder.js';
4
3
  import { SqlSchemaGenerator } from '../schemaGenerator.js';
5
4
  /** Where executed migrations are recorded when the config does not name a table. */
6
5
  export const DEFAULT_MIGRATIONS_TABLE = 'uql_migrations';
7
6
  /**
8
- * Stores migration state in a database table.
9
- * Uses the querier's dialect for escaping and placeholders.
7
+ * The journal record a run holds the lock by where the engine has no named lock (`migrationLock.ts`). No
8
+ * file name holds a slash, so no migration is named so.
10
9
  */
10
+ export const LOCK_RECORD = 'uql/lock';
11
+ /**
12
+ * Creates the journal `tableName` where it is missing, rendered by the schema generator rather than written
13
+ * out: SQL Server has no `CREATE TABLE IF NOT EXISTS`, and its `TIMESTAMP` is a row version that takes no
14
+ * default. Run under the migration lock, so two runs never race to create it.
15
+ */
16
+ export async function createMigrationsTable(querier, tableName) {
17
+ const table = new TableDefinitionBuilder(tableName);
18
+ table.string('name', { length: 255, primaryKey: true });
19
+ table.timestamptz('executed_at', { defaultValue: currentTimestamp });
20
+ const generator = new SqlSchemaGenerator(querier.dialect);
21
+ for (const sql of generator.generateCreateTableFromDefinition(table.build(), { ifNotExists: true })) {
22
+ await querier.run(raw.text(sql));
23
+ }
24
+ }
25
+ /** Records the migrations run in a table, on the querier each call is handed, which the lock created. */
11
26
  export class DatabaseMigrationStorage {
12
- pool;
13
27
  tableName;
14
- storageInitialized = false;
15
- constructor(pool, options = {}) {
16
- this.pool = pool;
28
+ constructor(options = {}) {
17
29
  this.tableName = options.tableName ?? DEFAULT_MIGRATIONS_TABLE;
18
30
  }
19
- /** Creates the table on first use, once. */
20
- async ensureStorage() {
21
- if (this.storageInitialized) {
22
- return;
23
- }
24
- await withSqlQuerierForMigrations(this.pool, 'DatabaseMigrationStorage', async (querier) => {
25
- await this.createTableIfNotExists(querier);
26
- this.storageInitialized = true;
27
- });
31
+ /** The names recorded, the lock's left out. */
32
+ async executed(querier) {
33
+ const { table, name } = journalIds(querier, this.tableName);
34
+ const rows = await querier.all `SELECT ${name} FROM ${table} WHERE ${name} <> ${LOCK_RECORD} ORDER BY ${name} ASC`;
35
+ return rows.map((row) => row.name);
28
36
  }
29
- /**
30
- * Rendered by the schema generator rather than written out, so each engine gets its own spelling: SQL
31
- * Server has no `CREATE TABLE IF NOT EXISTS`, and its `TIMESTAMP` is a row version that takes no default.
32
- */
33
- async createTableIfNotExists(querier) {
34
- const table = new TableBuilder(this.tableName);
35
- table.string('name', { length: 255, primaryKey: true });
36
- table.timestamptz('executed_at', { defaultValue: currentTimestamp });
37
- const generator = new SqlSchemaGenerator(querier.dialect);
38
- for (const sql of generator.generateCreateTableFromDefinition(table.build(), { ifNotExists: true })) {
39
- await querier.run(sql);
40
- }
41
- }
42
- async executed() {
43
- await this.ensureStorage();
44
- return withSqlQuerierForMigrations(this.pool, 'DatabaseMigrationStorage', async (querier) => {
45
- const { dialect } = querier;
46
- const sql = /*sql*/ `SELECT ${dialect.escapeId('name')} FROM ${dialect.escapeId(this.tableName)} ORDER BY ${dialect.escapeId('name')} ASC`;
47
- const rows = await querier.all(sql);
48
- return rows.map((row) => row.name);
49
- });
50
- }
51
- /**
52
- * Log a migration as executed - uses provided querier (within transaction)
53
- */
37
+ /** Records `migrationName` as run, on the querier that ran it, inside its transaction where there is one. */
54
38
  async logWithQuerier(querier, migrationName) {
55
- await this.ensureStorage();
56
- const { dialect } = querier;
57
- const sql = /*sql*/ `INSERT INTO ${dialect.escapeId(this.tableName)} (${dialect.escapeId('name')}) VALUES (${dialect.placeholder(1)})`;
58
- await querier.run(sql, [migrationName]);
39
+ const { table, name } = journalIds(querier, this.tableName);
40
+ await querier.run `INSERT INTO ${table} (${name}) VALUES (${migrationName})`;
59
41
  }
60
- /**
61
- * Unlog a migration - uses provided querier (within transaction)
62
- */
42
+ /** Removes the record of `migrationName`, on the querier that reverted it. */
63
43
  async unlogWithQuerier(querier, migrationName) {
64
- await this.ensureStorage();
65
- const { dialect } = querier;
66
- const sql = /*sql*/ `DELETE FROM ${dialect.escapeId(this.tableName)} WHERE ${dialect.escapeId('name')} = ${dialect.placeholder(1)}`;
67
- await querier.run(sql, [migrationName]);
44
+ const { table, name } = journalIds(querier, this.tableName);
45
+ await querier.run `DELETE FROM ${table} WHERE ${name} = ${migrationName}`;
68
46
  }
69
47
  }
48
+ /** The journal `tableName` and its one column, escaped as `querier`'s engine spells them. */
49
+ export function journalIds({ dialect }, tableName) {
50
+ return { table: raw.text(dialect.escapeId(tableName)), name: raw.text(dialect.escapeId('name')) };
51
+ }
@@ -1,2 +1 @@
1
1
  export * from './databaseStorage.js';
2
- export * from './jsonStorage.js';
@@ -1,2 +1 @@
1
1
  export * from './databaseStorage.js';
2
- export * from './jsonStorage.js';
@@ -2,6 +2,5 @@ export * from './mongoDialect.js';
2
2
  export * from './mongodbQuerier.js';
3
3
  export * from './mongodbQuerierPool.js';
4
4
  export * from './mongoIntrospector.js';
5
- export * from './mongoMigrationStorage.js';
6
5
  export { isMongoQuerier, type MongoQuerier } from './mongoQuerier.js';
7
6
  export * from './mongoSchemaGenerator.js';
@@ -2,6 +2,5 @@ export * from './mongoDialect.js';
2
2
  export * from './mongodbQuerier.js';
3
3
  export * from './mongodbQuerierPool.js';
4
4
  export * from './mongoIntrospector.js';
5
- export * from './mongoMigrationStorage.js';
6
5
  export { isMongoQuerier } from './mongoQuerier.js';
7
6
  export * from './mongoSchemaGenerator.js';
@@ -1,3 +1,6 @@
1
+ import type { CheckSchema } from '../schema/types.js';
2
+ /** A collection validator in query-filter syntax: every document written has to match it, `{}` none. */
3
+ export type MongoValidator = Readonly<Record<string, unknown>>;
1
4
  /** The direction, or `'text'`, of one field in a MongoDB index key spec. */
2
5
  export type MongoIndexKey = Record<string, 1 | -1 | 'text'>;
3
6
  /** What a `createIndex` command hands the driver beside its key spec. */
@@ -32,6 +35,11 @@ export type MongoSearchIndex = {
32
35
  export type MongoCommand = {
33
36
  readonly action: 'createCollection';
34
37
  readonly name: string;
38
+ readonly validator?: MongoValidator;
39
+ } | {
40
+ readonly action: 'collMod';
41
+ readonly name: string;
42
+ readonly validator: MongoValidator;
35
43
  } | {
36
44
  readonly action: 'dropCollection';
37
45
  readonly name: string;
@@ -58,6 +66,8 @@ export type MongoCommand = {
58
66
  readonly collection: string;
59
67
  readonly name: string;
60
68
  };
69
+ /** A collection's validator as the check it is, named for its JSON, so an edited one is a new name. */
70
+ export declare function validatorCheck(collection: string, validator: MongoValidator): CheckSchema;
61
71
  export declare function serializeMongoCommand(command: MongoCommand): string;
62
72
  /**
63
73
  * What executing these commands needs of a database handle. Declared structurally rather than as the
@@ -65,7 +75,13 @@ export declare function serializeMongoCommand(command: MongoCommand): string;
65
75
  * satisfy it with a plain object.
66
76
  */
67
77
  export type MongoCommandTarget = {
68
- createCollection(name: string): Promise<unknown>;
78
+ createCollection(name: string, options?: {
79
+ readonly validator: MongoValidator;
80
+ }): Promise<unknown>;
81
+ command(command: {
82
+ readonly collMod: string;
83
+ readonly validator: MongoValidator;
84
+ }): Promise<unknown>;
69
85
  renameCollection(from: string, to: string): Promise<unknown>;
70
86
  collection(name: string): {
71
87
  drop(): Promise<unknown>;