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
@@ -0,0 +1,103 @@
1
+ import { raw } from '../util/raw.js';
2
+ import { fnv1a } from '../util/string.util.js';
3
+ import { UqlUsageError } from '../util/uqlError.js';
4
+ import { withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
5
+ import { createMigrationsTable, journalIds, LOCK_RECORD } from './storage/databaseStorage.js';
6
+ /** How long `up` and `down` wait for the lock another run holds, unless told otherwise. */
7
+ export const DEFAULT_LOCK_TIMEOUT = 5 * 60_000;
8
+ /** How often a run waiting for the lock asks for it again. */
9
+ const POLL_INTERVAL = 250;
10
+ /** MySQL's lock names are server-wide, so the database prefixes each, cut to the 64 characters it takes. */
11
+ const mysqlLock = (name) => {
12
+ const lock = raw `LEFT(CONCAT(DATABASE(), '.', ${name}), 64)`;
13
+ return { acquire: raw `SELECT 1 FROM DUAL WHERE GET_LOCK(${lock}, 0) = 1`, release: raw `DO RELEASE_LOCK(${lock})` };
14
+ };
15
+ /** Each engine's named lock, as `features.namedLocks` says what holds it. None on CockroachDB and SQLite. */
16
+ const NAMED_LOCK_SQL = {
17
+ postgres: (name) => {
18
+ const key = fnv1a(name);
19
+ return {
20
+ acquire: raw `SELECT 1 WHERE pg_try_advisory_lock(${key})`,
21
+ release: raw `SELECT pg_advisory_unlock(${key})`,
22
+ };
23
+ },
24
+ cockroachdb: undefined,
25
+ mysql: mysqlLock,
26
+ mariadb: mysqlLock,
27
+ mssql: (name) => ({
28
+ acquire: raw `DECLARE @_uql_lock INT;
29
+ EXEC @_uql_lock = sp_getapplock @Resource = ${name}, @LockMode = 'Exclusive', @LockOwner = 'Transaction', @LockTimeout = 0;
30
+ SELECT 1 WHERE @_uql_lock >= 0`,
31
+ release: raw `EXEC sp_releaseapplock @Resource = ${name}, @LockOwner = 'Transaction'`,
32
+ }),
33
+ sqlite: undefined,
34
+ };
35
+ /** The statements of the lock named `name` on `dialect`'s engine, where it has one its sessions can hold. */
36
+ export function namedLockSql(dialect, name) {
37
+ return dialect.features.namedLocks ? NAMED_LOCK_SQL[dialect.dialectName]?.(name) : undefined;
38
+ }
39
+ /**
40
+ * Runs `work` holding `lock`, asking for it until `timeout` passes, and releasing it however `work` ends: a
41
+ * release failing after `work` did is a consequence of its error, and never replaces it.
42
+ */
43
+ export async function holdingLock(lock, { name, timeout }, work) {
44
+ const deadline = Date.now() + timeout;
45
+ while (!(await lock.take())) {
46
+ if (Date.now() >= deadline) {
47
+ throw new UqlUsageError(`Gave up after ${timeout}ms waiting for the migration lock on "${name}", which another run holds. ${lock.stuck}`);
48
+ }
49
+ await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
50
+ }
51
+ const result = await work().catch(async (error) => {
52
+ await lock.release().catch(() => { });
53
+ throw error;
54
+ });
55
+ await lock.release();
56
+ return result;
57
+ }
58
+ /**
59
+ * Runs `work` holding the lock `options` names, the journal created first: on `querier`'s session, in a
60
+ * transaction of its own kept open meanwhile, or, where the engine has no named lock, by a record in the
61
+ * journal, which then has to exist before the lock, created by whichever run gets there.
62
+ */
63
+ export async function withSqlMigrationLock(pool, querier, options, work) {
64
+ const { dialect } = querier;
65
+ const journaled = async () => {
66
+ await createMigrationsTable(querier, options.name);
67
+ return work();
68
+ };
69
+ const sql = namedLockSql(dialect, options.name);
70
+ if (!sql) {
71
+ await createMigrationsTable(querier, options.name);
72
+ return holdingLock(sqlRecordLock(querier, options.name), options, work);
73
+ }
74
+ if (dialect.features.namedLocks === 'session') {
75
+ return holdingLock(statementLock(querier, sql), options, journaled);
76
+ }
77
+ return withSqlQuerierForMigrations(pool, 'Migrator', (own) => own.transaction(() => holdingLock(statementLock(own, sql), options, journaled)));
78
+ }
79
+ /** The engine's named lock, which it releases itself should the connection close. */
80
+ function statementLock(querier, { acquire, release }) {
81
+ return {
82
+ take: async () => (await querier.all(acquire)).length > 0,
83
+ release: () => querier.run(release),
84
+ stuck: 'The engine releases it once that run ends or its connection closes.',
85
+ };
86
+ }
87
+ /** What to do about a lock record no run released, which only a person can tell is stale. */
88
+ export const staleRecord = (what, journal) => `If none is running, one stopped before releasing it: delete the ${what} '${LOCK_RECORD}' from "${journal}".`;
89
+ /**
90
+ * The journal's {@link LOCK_RECORD} row, inserted only where it is absent, which one run alone can: SQLite
91
+ * writes one statement at a time, and CockroachDB serializes them.
92
+ */
93
+ function sqlRecordLock(querier, journal) {
94
+ const { table, name } = journalIds(querier, journal);
95
+ return {
96
+ take: async () => {
97
+ const { changes } = await querier.run `INSERT INTO ${table} (${name}) SELECT ${LOCK_RECORD} WHERE NOT EXISTS (SELECT 1 FROM ${table} WHERE ${name} = ${LOCK_RECORD})`;
98
+ return changes === 1;
99
+ },
100
+ release: () => querier.run `DELETE FROM ${table} WHERE ${name} = ${LOCK_RECORD}`,
101
+ stuck: staleRecord('row', journal),
102
+ };
103
+ }
@@ -1,7 +1,9 @@
1
1
  import type { ForeignKeyAction } from '../schema/types.js';
2
- import { type MigrationStorage, type MigratorDialect, type Querier, type QuerierPool, type SchemaGenerator } from '../type/index.js';
3
- import { MigrationBuilder } from './builder/migrationBuilder.js';
2
+ import { type MigratorDialect, type Querier, type QuerierPool, type SchemaGenerator } from '../type/index.js';
3
+ import type { MigrationBuilder } from './builder/types.js';
4
4
  import { type MigrationSource } from './codegen/migrationFile.js';
5
+ import { type MigrationLockOptions } from './migrationLock.js';
6
+ import { type MigrationStorage } from './storage/databaseStorage.js';
5
7
  /** A migration querier as its engine family drives it. */
6
8
  export type MigrationSession = {
7
9
  readonly querier: Querier;
@@ -17,6 +19,8 @@ export type MigrationTarget = {
17
19
  /** The dialect's schema generator. Async because MongoDB's loads its optional peer. */
18
20
  generator(): Promise<SchemaGenerator>;
19
21
  withSession<T>(task: (session: MigrationSession) => Promise<T>): Promise<T>;
22
+ /** {@link withSession}, holding the lock `lock` names throughout, so a second run waits for this one. */
23
+ withLockedSession<T>(lock: MigrationLockOptions, task: (session: MigrationSession) => Promise<T>): Promise<T>;
20
24
  };
21
25
  export declare function migrationTargetFor(pool: QuerierPool<Querier, MigratorDialect>, defaultForeignKeyAction?: ForeignKeyAction): MigrationTarget;
22
26
  /** A builder running each operation on `querier`, as SQL or as MongoDB driver commands. */
@@ -1,16 +1,18 @@
1
- import { runMongoCommand } from '../mongo/mongoCommand.js';
2
- import { MongoMigrationStorage } from '../mongo/mongoMigrationStorage.js';
3
- import { isMongoQuerier, withMongoQuerierForMigrations } from '../mongo/mongoQuerier.js';
1
+ import { runMongoCommand } from '../mongodb/mongoCommand.js';
2
+ import { MongoMigrationStorage } from '../mongodb/mongoMigrationStorage.js';
3
+ import { isMongoQuerier, withMongoQuerierForMigrations } from '../mongodb/mongoQuerier.js';
4
4
  import { isSqlQuerier, } from '../type/index.js';
5
+ import { raw } from '../util/raw.js';
5
6
  import { UqlUsageError } from '../util/uqlError.js';
6
7
  import { withSqlQuerierForMigrations } from './acquireQuerierForMigrations.js';
7
- import { MigrationBuilder } from './builder/migrationBuilder.js';
8
+ import { MigrationOperationBuilder } from './builder/migrationBuilder.js';
8
9
  import { migrationSource } from './codegen/migrationFile.js';
10
+ import { holdingLock, staleRecord, withSqlMigrationLock, } from './migrationLock.js';
9
11
  import { SqlSchemaGenerator } from './schemaGenerator.js';
10
- import { DatabaseMigrationStorage } from './storage/databaseStorage.js';
12
+ import { DatabaseMigrationStorage, LOCK_RECORD } from './storage/databaseStorage.js';
11
13
  const sqlSession = (querier) => ({
12
14
  querier,
13
- run: (statement) => querier.run(statement),
15
+ run: (statement) => querier.run(raw.text(statement)),
14
16
  transaction: (work) => querier.dialect.features.rebuildsTables ? withForeignKeysOff(querier, work) : querier.transaction(work),
15
17
  });
16
18
  /**
@@ -20,15 +22,15 @@ const sqlSession = (querier) => ({
20
22
  * rebuild's guard refuses.
21
23
  */
22
24
  async function withForeignKeysOff(querier, work) {
23
- const [{ foreign_keys: enforced }] = await querier.all('PRAGMA foreign_keys');
25
+ const [{ foreign_keys: enforced }] = await querier.all `PRAGMA foreign_keys`;
24
26
  if (!enforced) {
25
27
  return querier.transaction(work);
26
28
  }
27
- await querier.run('PRAGMA foreign_keys = OFF');
29
+ await querier.run `PRAGMA foreign_keys = OFF`;
28
30
  try {
29
31
  await querier.transaction(async () => {
30
32
  await work();
31
- const violations = await querier.all('PRAGMA foreign_key_check');
33
+ const violations = await querier.all `PRAGMA foreign_key_check`;
32
34
  if (violations.length) {
33
35
  const [{ table, parent }] = violations;
34
36
  throw new UqlUsageError(`The migration leaves ${violations.length} row(s) referencing a missing one, the first in "${table}" pointing at "${parent}".`);
@@ -36,7 +38,7 @@ async function withForeignKeysOff(querier, work) {
36
38
  });
37
39
  }
38
40
  finally {
39
- await querier.run('PRAGMA foreign_keys = ON');
41
+ await querier.run `PRAGMA foreign_keys = ON`;
40
42
  }
41
43
  }
42
44
  const mongoSession = (querier) => ({
@@ -44,9 +46,21 @@ const mongoSession = (querier) => ({
44
46
  run: (statement) => runMongoCommand(querier.db, statement),
45
47
  transaction: (work) => work(),
46
48
  });
49
+ /** MongoDB has no named lock, so a run holds the journal's record, upserted where absent, which one alone can. */
50
+ function mongoRecordLock(querier, journal) {
51
+ const collection = querier.db.collection(journal);
52
+ return {
53
+ take: async () => {
54
+ const { upsertedCount } = await collection.updateOne({ _id: LOCK_RECORD }, { $setOnInsert: { executed_at: new Date() } }, { upsert: true });
55
+ return upsertedCount === 1;
56
+ },
57
+ release: () => collection.deleteOne({ _id: LOCK_RECORD }),
58
+ stuck: staleRecord('document', journal),
59
+ };
60
+ }
47
61
  /** Imported on use, so the optional `mongodb` peer loads only on MongoDB. */
48
62
  async function mongoSchemaGenerator(namingStrategy) {
49
- const { MongoSchemaGenerator } = await import('../mongo/mongoSchemaGenerator.js');
63
+ const { MongoSchemaGenerator } = await import('../mongodb/mongoSchemaGenerator.js');
50
64
  return new MongoSchemaGenerator(namingStrategy);
51
65
  }
52
66
  export function migrationTargetFor(pool, defaultForeignKeyAction) {
@@ -54,16 +68,18 @@ export function migrationTargetFor(pool, defaultForeignKeyAction) {
54
68
  if (dialect.dialectName === 'mongodb') {
55
69
  return {
56
70
  source: migrationSource.MongoQuerier,
57
- storage: (tableName) => new MongoMigrationStorage(pool, { tableName }),
71
+ storage: (tableName) => new MongoMigrationStorage({ tableName }),
58
72
  generator: () => mongoSchemaGenerator(dialect.namingStrategy),
59
73
  withSession: (task) => withMongoQuerierForMigrations(pool, 'Migrator', (querier) => task(mongoSession(querier))),
74
+ withLockedSession: (lock, task) => withMongoQuerierForMigrations(pool, 'Migrator', (querier) => holdingLock(mongoRecordLock(querier, lock.name), lock, () => task(mongoSession(querier)))),
60
75
  };
61
76
  }
62
77
  return {
63
78
  source: migrationSource.SqlQuerier,
64
- storage: (tableName) => new DatabaseMigrationStorage(pool, { tableName }),
79
+ storage: (tableName) => new DatabaseMigrationStorage({ tableName }),
65
80
  generator: async () => new SqlSchemaGenerator(dialect, defaultForeignKeyAction),
66
81
  withSession: (task) => withSqlQuerierForMigrations(pool, 'Migrator', (querier) => task(sqlSession(querier))),
82
+ withLockedSession: (lock, task) => withSqlQuerierForMigrations(pool, 'Migrator', (querier) => withSqlMigrationLock(pool, querier, lock, () => task(sqlSession(querier)))),
67
83
  };
68
84
  }
69
85
  /** A builder running each operation on `querier`, as SQL or as MongoDB driver commands. */
@@ -78,7 +94,7 @@ export async function migrationBuilderFor(querier) {
78
94
  }
79
95
  /** A builder running each statement `generator` writes for an operation through `run`. */
80
96
  function builderOn(generator, run) {
81
- return new MigrationBuilder(async (operation) => {
97
+ return new MigrationOperationBuilder(async (operation) => {
82
98
  for (const statement of generator.generateOperation(operation)) {
83
99
  await run(statement);
84
100
  }
@@ -1,12 +1,11 @@
1
- import type { Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
1
+ import type { MigrationDefinition, MigrationResult, MigratorDialect, MigratorOptions, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlQuerier, SyncOptions, Type } from '../type/index.js';
2
2
  import { LoggerWrapper } from '../util/index.js';
3
- import type { IMigrationBuilder } from './builder/types.js';
3
+ import type { MigrationBuilder } from './builder/types.js';
4
4
  /**
5
5
  * Main class for managing database migrations
6
6
  */
7
7
  export declare class Migrator {
8
8
  private readonly pool;
9
- readonly storage: MigrationStorage;
10
9
  readonly migrationsPath: string;
11
10
  readonly logger: LoggerWrapper;
12
11
  private readonly _entities?;
@@ -15,42 +14,51 @@ export declare class Migrator {
15
14
  schemaGenerator?: SchemaGenerator;
16
15
  schemaIntrospector: SchemaIntrospector;
17
16
  private readonly target;
17
+ private readonly lock;
18
+ /** The journal of the migrations run: a table, or a collection on MongoDB. */
19
+ private readonly storage;
18
20
  constructor(pool: QuerierPool<Querier, MigratorDialect>, options?: MigratorOptions);
19
21
  /** The schema generator, loaded on first use: MongoDB's needs its optional peer. */
20
22
  getSchemaGenerator(): Promise<SchemaGenerator>;
21
23
  /**
22
- * Get all discovered migrations from the migrations directory
24
+ * The migration files by name, the names the storage records as run, and those on disk it does not, all in
25
+ * name order. Read from names alone: a file is imported only when it is about to run.
23
26
  */
24
- getMigrations(): Promise<Migration<Querier>[]>;
25
- /** The migrations on disk the storage records as run (`applied`) or not (`pending`), and every name it records. */
26
27
  private journal;
27
- /** The migrations not yet run. */
28
- pending(): Promise<Migration<Querier>[]>;
29
28
  /**
30
- * Get list of executed migrations
29
+ * {@link journal} read without the lock, so a run holding it never holds a reader up. Only a run creates the
30
+ * journal, under the lock, so one not created yet has recorded nothing.
31
31
  */
32
- executed(): Promise<string[]>;
32
+ private unlockedJournal;
33
33
  /**
34
- * Run all pending migrations
34
+ * Runs the pending migrations, up to `to` or `step` of them, each in a transaction of its own where the
35
+ * engine has one for its statements, and throws the first one's error, those before it staying applied.
36
+ * It holds the migration lock throughout, so a second run waits, then finds them run.
35
37
  */
36
38
  up(options?: {
37
39
  to?: string;
38
40
  step?: number;
39
41
  }): Promise<MigrationResult[]>;
40
42
  /**
41
- * Rollback migrations
43
+ * Reverts the migrations run, latest first, as {@link up} runs them: down to `to`, or `step` of them, the last
44
+ * one alone where it names neither. `step: Infinity` reverts them all.
42
45
  */
43
- down(options?: {
46
+ down({ to, step }?: {
44
47
  to?: string;
45
48
  step?: number;
46
49
  }): Promise<MigrationResult[]>;
47
- /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
50
+ /**
51
+ * Holding the lock, runs the names narrowed by `to`/`step`, stopping at the first failure: `up` over the
52
+ * pending, `down` over the executed reversed. Every one is loaded before any runs, so a file that cannot be
53
+ * leaves the database as it was.
54
+ */
55
+ private migrate;
48
56
  private runInOrder;
49
57
  /**
50
- * Run a single migration, in a transaction where the dialect has one for it and the migration has not
51
- * declared `transaction: false` - the opt-out a statement an engine refuses inside one needs.
58
+ * Runs one migration, in a transaction where the dialect has one for it and the migration has not declared
59
+ * `transaction: false` - the opt-out a statement an engine refuses inside one needs.
52
60
  */
53
- runMigration(migration: Migration<Querier>, direction: 'up' | 'down'): Promise<MigrationResult>;
61
+ private runMigration;
54
62
  /**
55
63
  * Generate a new migration file
56
64
  */
@@ -79,17 +87,26 @@ export declare class Migrator {
79
87
  /** The table `entity` maps to, as a diff names it. */
80
88
  private tableOf;
81
89
  /**
82
- * The differences between the entities and the database. With `renames`, a column identical to one the
83
- * entity no longer names is renamed in place rather than dropped and added, as a generated migration wants.
90
+ * The differences between the entities and the database. With `renames`, as a generated migration wants, a
91
+ * column whose name another naming strategy spells is renamed in place rather than dropped and added.
84
92
  */
85
93
  getDiffs(options?: {
86
94
  renames?: boolean;
87
95
  }): Promise<SchemaDiff[]>;
96
+ /**
97
+ * Each column dropped while one identical to it but for its name is added: maybe a rename, which only its
98
+ * author can tell, so it is suggested and never written. A wrong guess would carry its data into a column
99
+ * meant for other data.
100
+ */
101
+ private noteRenameCandidates;
88
102
  /**
89
103
  * Each check uql did not install on a table whose entity declares checks: never changed or dropped, so
90
104
  * one an owned check replaces, such as an enum's from before checks were named, goes on enforcing itself.
91
105
  */
92
106
  private noteForeignChecks;
107
+ /** Which of the tables `entities` name exist, by qualified name: one catalogue read per schema. */
108
+ private presentTables;
109
+ private entitiesBySchema;
93
110
  /**
94
111
  * The tables `entities` name, read a schema at a time so each is keyed as its entity spells it. Those
95
112
  * alone: nothing else is diffed, and another table can be dropped mid-scan by whatever else is running.
@@ -97,7 +114,10 @@ export declare class Migrator {
97
114
  private introspectEntities;
98
115
  /** Applies the entity schema: every entity, or the one `entity` names. {@link planSync} answers the same without running it. */
99
116
  sync(options?: SyncOptions): Promise<void>;
100
- /** Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph order. */
117
+ /**
118
+ * Every table dropped and recreated, the whole entity set at once, so foreign keys resolve and drop in graph
119
+ * order. Only where a drop leaves its foreign keys behind are the tables read beyond whether they exist.
120
+ */
101
121
  private forceStatements;
102
122
  /**
103
123
  * The DDL for one entity: {@link planSync} narrowed to the table it names. A new table costs one
@@ -133,25 +153,15 @@ export declare class Migrator {
133
153
  executeSyncStatements(statements: string[], options: {
134
154
  logging?: boolean;
135
155
  }): Promise<void>;
136
- /**
137
- * Get migration status
138
- */
156
+ /** The names of the migrations pending and run, read without the lock. */
139
157
  status(): Promise<{
140
158
  pending: string[];
141
159
  executed: string[];
142
160
  }>;
143
- /**
144
- * Get migration files from the migrations directory
145
- */
146
- getMigrationFiles(): Promise<string[]>;
147
- /**
148
- * Load a migration from a file
149
- */
150
- loadMigration(fileName: string): Promise<Migration<Querier> | undefined>;
151
- /**
152
- * Check if an object is a valid migration
153
- */
154
- isMigration(obj: unknown): obj is MigrationDefinition<Querier>;
161
+ /** The migration files in the migrations directory, by the name each runs as; none where it is missing. */
162
+ private migrationFiles;
163
+ /** The migration `name`, from its `file`: a missing file, one that fails to import, or one exporting no migration throws. */
164
+ private loadMigration;
155
165
  }
156
166
  /**
157
167
  * Helper function to define a migration with proper typing
@@ -164,8 +174,8 @@ export declare function defineMigration<Q extends Querier = SqlQuerier>(migratio
164
174
  */
165
175
  export interface BuilderMigrationDefinition<Q extends Querier = SqlQuerier> {
166
176
  readonly name?: string;
167
- up(builder: IMigrationBuilder, querier: Q): Promise<void>;
168
- down(builder: IMigrationBuilder, querier: Q): Promise<void>;
177
+ up(builder: MigrationBuilder, querier: Q): Promise<void>;
178
+ down(builder: MigrationBuilder, querier: Q): Promise<void>;
169
179
  }
170
180
  /**
171
181
  * Defines a migration with the builder: