uql-orm 0.99.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 +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
@@ -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,6 +14,9 @@ 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>;
@@ -23,36 +25,40 @@ export declare class Migrator {
23
25
  * name order. Read from names alone: a file is imported only when it is about to run.
24
26
  */
25
27
  private journal;
26
- /** The names of the migrations not yet run, in the order `up` runs them. */
27
- pending(): Promise<string[]>;
28
28
  /**
29
- * 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.
30
31
  */
31
- executed(): Promise<string[]>;
32
+ private unlockedJournal;
32
33
  /**
33
- * 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.
34
37
  */
35
38
  up(options?: {
36
39
  to?: string;
37
40
  step?: number;
38
41
  }): Promise<MigrationResult[]>;
39
42
  /**
40
- * 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.
41
45
  */
42
- down(options?: {
46
+ down({ to, step }?: {
43
47
  to?: string;
44
48
  step?: number;
45
49
  }): Promise<MigrationResult[]>;
46
50
  /**
47
- * Runs the names narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over
48
- * the executed reversed. Every one is loaded before any runs, so a file that cannot be leaves the database as it was.
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.
49
54
  */
55
+ private migrate;
50
56
  private runInOrder;
51
57
  /**
52
- * Run a single migration, in a transaction where the dialect has one for it and the migration has not
53
- * 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.
54
60
  */
55
- runMigration(migration: Migration<Querier>, direction: 'up' | 'down'): Promise<MigrationResult>;
61
+ private runMigration;
56
62
  /**
57
63
  * Generate a new migration file
58
64
  */
@@ -81,17 +87,26 @@ export declare class Migrator {
81
87
  /** The table `entity` maps to, as a diff names it. */
82
88
  private tableOf;
83
89
  /**
84
- * The differences between the entities and the database. With `renames`, a column identical to one the
85
- * 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.
86
92
  */
87
93
  getDiffs(options?: {
88
94
  renames?: boolean;
89
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;
90
102
  /**
91
103
  * Each check uql did not install on a table whose entity declares checks: never changed or dropped, so
92
104
  * one an owned check replaces, such as an enum's from before checks were named, goes on enforcing itself.
93
105
  */
94
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;
95
110
  /**
96
111
  * The tables `entities` name, read a schema at a time so each is keyed as its entity spells it. Those
97
112
  * alone: nothing else is diffed, and another table can be dropped mid-scan by whatever else is running.
@@ -99,7 +114,10 @@ export declare class Migrator {
99
114
  private introspectEntities;
100
115
  /** Applies the entity schema: every entity, or the one `entity` names. {@link planSync} answers the same without running it. */
101
116
  sync(options?: SyncOptions): Promise<void>;
102
- /** 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
+ */
103
121
  private forceStatements;
104
122
  /**
105
123
  * The DDL for one entity: {@link planSync} narrowed to the table it names. A new table costs one
@@ -135,9 +153,7 @@ export declare class Migrator {
135
153
  executeSyncStatements(statements: string[], options: {
136
154
  logging?: boolean;
137
155
  }): Promise<void>;
138
- /**
139
- * Get migration status
140
- */
156
+ /** The names of the migrations pending and run, read without the lock. */
141
157
  status(): Promise<{
142
158
  pending: string[];
143
159
  executed: string[];
@@ -158,8 +174,8 @@ export declare function defineMigration<Q extends Querier = SqlQuerier>(migratio
158
174
  */
159
175
  export interface BuilderMigrationDefinition<Q extends Querier = SqlQuerier> {
160
176
  readonly name?: string;
161
- up(builder: IMigrationBuilder, querier: Q): Promise<void>;
162
- down(builder: IMigrationBuilder, querier: Q): Promise<void>;
177
+ up(builder: MigrationBuilder, querier: Q): Promise<void>;
178
+ down(builder: MigrationBuilder, querier: Q): Promise<void>;
163
179
  }
164
180
  /**
165
181
  * Defines a migration with the builder: