@dudousxd/nestjs-durable-store-mikro-orm 0.33.1 → 0.33.2

package/dist/index.d.cts

@@ -45,6 +45,13 @@ declare class ScheduleRepository extends EntityRepository<ScheduleEntity> {
  * swap against an existing table.
  */
 type DurableColumnNaming = 'snake_case' | 'preserve' | ((property: string) => string);
+/**
+ * Fractional-second digits on every timestamp column. MySQL's `datetime` defaults to 0 and ROUNDS
+ * the milliseconds away, which moves leases, timers and event order by up to half a second. 6 rather
+ * than 3 because it is Postgres's default `timestamptz` precision, so pinning it changes no
+ * Postgres column; SQLite ignores it.
+ */
+declare const DATETIME_PRECISION = 6;
 declare class WorkflowRunEntity {
     [EntityRepositoryType]?: WorkflowRunRepository;
     id: string;
@@ -171,7 +178,27 @@ interface DurableSchemaLogger {
 interface EnsureMikroOrmDurableSchemaOptions {
     /** Sink for the schema-repair warning. Defaults to `console`. */
     logger?: DurableSchemaLogger | undefined;
+    /**
+     * MySQL only: the largest estimated row count (`information_schema.tables.table_rows`) of an
+     * existing durable table on which the boot-time heal will run a column TYPE change. MySQL runs a
+     * type change (e.g. `datetime` -> `datetime(6)`) as a full table copy that blocks writes until it
+     * finishes, so on a bigger table the statement is skipped and logged for you to run out of band
+     * (a maintenance window, `gh-ost`, `pt-online-schema-change`); every boot logs it again until the
+     * column matches. Defaults to {@link DEFAULT_BLOCKING_ALTER_ROW_LIMIT}. `Infinity` always applies.
+     */
+    blockingAlterRowLimit?: number | undefined;
 }
+/** Default {@link EnsureMikroOrmDurableSchemaOptions.blockingAlterRowLimit}: a copy of this many rows takes seconds. */
+declare const DEFAULT_BLOCKING_ALTER_ROW_LIMIT = 100000;
+/**
+ * The warning logged when the heal skipped a MySQL column type change because the table is too big
+ * to rebuild at boot (see {@link EnsureMikroOrmDurableSchemaOptions.blockingAlterRowLimit}).
+ */
+declare function mikroOrmDeferredAlterWarning(deferred: ReadonlyArray<{
+    table: string;
+    rows: number;
+    statement: string;
+}>, limit: number): string;
 /**
  * The warning logged when the boot-time heal changed an EXISTING durable schema: created a table
  * that was missing next to ones that exist, added a column or index, changed a column type, or
@@ -234,10 +261,16 @@ interface MikroOrmStateStoreOptions {
      * satisfies it.
      */
     schemaLogger?: DurableSchemaLogger | undefined;
+    /**
+     * MySQL: the largest existing durable table `ensureSchema()` will rebuild for a column type
+     * change at boot; bigger ones are logged for you to run out of band. See
+     * `blockingAlterRowLimit` on `ensureMikroOrmDurableSchema`.
+     */
+    schemaBlockingAlterRowLimit?: number | undefined;
 }
 /**
  * MikroORM-backed `StateStore`. Works on any MikroORM driver — Postgres, MySQL, SQLite (tested);
- * timestamps and `wakeAt` use native datetime columns. Each operation runs on a forked
+ * timestamps and `wakeAt` use native datetime columns with microsecond precision (MySQL `datetime(6)`). Each operation runs on a forked
  * EntityManager so it owns its unit of work.
  *
  * Pass `opts.scope.namespace` to confine all reads to a single tenant namespace. Omit for the
@@ -413,4 +446,4 @@ declare class MikroOrmStateStore implements StateStore {
     removeBufferedEvent(id: string): Promise<boolean>;
 }
 
-export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, type DurableColumnNaming, type DurableSchemaLogger, ENTITIES, type EnsureMikroOrmDurableSchemaOptions, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, ScheduleEntity, ScheduleRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema, mikroOrmSchemaRepairWarning };
+export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, DATETIME_PRECISION, DEFAULT_BLOCKING_ALTER_ROW_LIMIT, type DurableColumnNaming, type DurableSchemaLogger, ENTITIES, type EnsureMikroOrmDurableSchemaOptions, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, ScheduleEntity, ScheduleRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema, mikroOrmDeferredAlterWarning, mikroOrmSchemaRepairWarning };

package/dist/index.d.ts

@@ -45,6 +45,13 @@ declare class ScheduleRepository extends EntityRepository<ScheduleEntity> {
  * swap against an existing table.
  */
 type DurableColumnNaming = 'snake_case' | 'preserve' | ((property: string) => string);
+/**
+ * Fractional-second digits on every timestamp column. MySQL's `datetime` defaults to 0 and ROUNDS
+ * the milliseconds away, which moves leases, timers and event order by up to half a second. 6 rather
+ * than 3 because it is Postgres's default `timestamptz` precision, so pinning it changes no
+ * Postgres column; SQLite ignores it.
+ */
+declare const DATETIME_PRECISION = 6;
 declare class WorkflowRunEntity {
     [EntityRepositoryType]?: WorkflowRunRepository;
     id: string;
@@ -171,7 +178,27 @@ interface DurableSchemaLogger {
 interface EnsureMikroOrmDurableSchemaOptions {
     /** Sink for the schema-repair warning. Defaults to `console`. */
     logger?: DurableSchemaLogger | undefined;
+    /**
+     * MySQL only: the largest estimated row count (`information_schema.tables.table_rows`) of an
+     * existing durable table on which the boot-time heal will run a column TYPE change. MySQL runs a
+     * type change (e.g. `datetime` -> `datetime(6)`) as a full table copy that blocks writes until it
+     * finishes, so on a bigger table the statement is skipped and logged for you to run out of band
+     * (a maintenance window, `gh-ost`, `pt-online-schema-change`); every boot logs it again until the
+     * column matches. Defaults to {@link DEFAULT_BLOCKING_ALTER_ROW_LIMIT}. `Infinity` always applies.
+     */
+    blockingAlterRowLimit?: number | undefined;
 }
+/** Default {@link EnsureMikroOrmDurableSchemaOptions.blockingAlterRowLimit}: a copy of this many rows takes seconds. */
+declare const DEFAULT_BLOCKING_ALTER_ROW_LIMIT = 100000;
+/**
+ * The warning logged when the heal skipped a MySQL column type change because the table is too big
+ * to rebuild at boot (see {@link EnsureMikroOrmDurableSchemaOptions.blockingAlterRowLimit}).
+ */
+declare function mikroOrmDeferredAlterWarning(deferred: ReadonlyArray<{
+    table: string;
+    rows: number;
+    statement: string;
+}>, limit: number): string;
 /**
  * The warning logged when the boot-time heal changed an EXISTING durable schema: created a table
  * that was missing next to ones that exist, added a column or index, changed a column type, or
@@ -234,10 +261,16 @@ interface MikroOrmStateStoreOptions {
      * satisfies it.
      */
     schemaLogger?: DurableSchemaLogger | undefined;
+    /**
+     * MySQL: the largest existing durable table `ensureSchema()` will rebuild for a column type
+     * change at boot; bigger ones are logged for you to run out of band. See
+     * `blockingAlterRowLimit` on `ensureMikroOrmDurableSchema`.
+     */
+    schemaBlockingAlterRowLimit?: number | undefined;
 }
 /**
  * MikroORM-backed `StateStore`. Works on any MikroORM driver — Postgres, MySQL, SQLite (tested);
- * timestamps and `wakeAt` use native datetime columns. Each operation runs on a forked
+ * timestamps and `wakeAt` use native datetime columns with microsecond precision (MySQL `datetime(6)`). Each operation runs on a forked
  * EntityManager so it owns its unit of work.
  *
  * Pass `opts.scope.namespace` to confine all reads to a single tenant namespace. Omit for the
@@ -413,4 +446,4 @@ declare class MikroOrmStateStore implements StateStore {
     removeBufferedEvent(id: string): Promise<boolean>;
 }
 
-export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, type DurableColumnNaming, type DurableSchemaLogger, ENTITIES, type EnsureMikroOrmDurableSchemaOptions, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, ScheduleEntity, ScheduleRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema, mikroOrmSchemaRepairWarning };
+export { BufferedEventEntity, BufferedEventRepository, BufferedSignalEntity, BufferedSignalRepository, DATETIME_PRECISION, DEFAULT_BLOCKING_ALTER_ROW_LIMIT, type DurableColumnNaming, type DurableSchemaLogger, ENTITIES, type EnsureMikroOrmDurableSchemaOptions, MikroOrmStateStore, type MikroOrmStateStoreOptions, RunAttributeEntity, RunAttributeRepository, ScheduleEntity, ScheduleRepository, SignalWaiterEntity, SignalWaiterRepository, StepCheckpointEntity, StepCheckpointRepository, WorkflowRunEntity, WorkflowRunRepository, durableEntities, durableManagedTables, ensureMikroOrmDurableSchema, mikroOrmDeferredAlterWarning, mikroOrmSchemaRepairWarning };

package/dist/index.js

@@ -47,6 +47,7 @@ function snakeCase(property) {
   return property.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
 }
 __name(snakeCase, "snakeCase");
+var DATETIME_PRECISION = 6;
 function columnNamer(naming) {
   if (naming === "snake_case") return snakeCase;
   if (naming === "preserve") return (property) => property;
@@ -253,6 +254,7 @@ function durableEntities(options = {}) {
       },
       wakeAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         nullable: true,
         fieldName: col("wakeAt")
       },
@@ -263,6 +265,7 @@ function durableEntities(options = {}) {
       },
       lockedUntil: {
         type: "Date",
+        length: DATETIME_PRECISION,
         nullable: true,
         fieldName: col("lockedUntil")
       },
@@ -325,10 +328,12 @@ function durableEntities(options = {}) {
       },
       createdAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         fieldName: col("createdAt")
       },
       updatedAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         fieldName: col("updatedAt")
       }
     }
@@ -417,20 +422,24 @@ function durableEntities(options = {}) {
       },
       wakeAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         nullable: true,
         fieldName: col("wakeAt")
       },
       enqueuedAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         nullable: true,
         fieldName: col("enqueuedAt")
       },
       startedAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         fieldName: col("startedAt")
       },
       finishedAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         fieldName: col("finishedAt")
       }
     }
@@ -575,6 +584,7 @@ function durableEntities(options = {}) {
       },
       publishedAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         fieldName: col("publishedAt")
       }
     }
@@ -633,10 +643,12 @@ function durableEntities(options = {}) {
       },
       createdAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         fieldName: col("createdAt")
       },
       updatedAt: {
         type: "Date",
+        length: DATETIME_PRECISION,
         fieldName: col("updatedAt")
       }
     }
@@ -679,6 +691,21 @@ var MARKER_TABLE = "durable_schema_meta";
 var MARKER_ROW_ID = "durable";
 var SCHEMA_LOCK_NAME = "durable_schema";
 var SCHEMA_REVISION = 1;
+var DEFAULT_BLOCKING_ALTER_ROW_LIMIT = 1e5;
+function deferredAlterWarning(store, deferred, limit) {
+  return [
+    `[nestjs-durable] ${store} did NOT apply ${deferred.length} durable-schema column type change(s) at boot.`,
+    `MySQL rebuilds a table to change a column type and blocks writes to it until the copy ends, and these tables hold more than blockingAlterRowLimit (${limit}) rows:`,
+    ...deferred.map((d) => `  -- ${d.table}, ~${d.rows} rows
+  ${d.statement};`),
+    "Run them in a maintenance window or with an online schema change tool (gh-ost, pt-online-schema-change), or raise blockingAlterRowLimit to let a boot run them. Until then the store keeps working on the old column types, and this warning repeats on every boot."
+  ].join("\n");
+}
+__name(deferredAlterWarning, "deferredAlterWarning");
+function mikroOrmDeferredAlterWarning(deferred, limit) {
+  return deferredAlterWarning("store-mikro-orm", deferred, limit);
+}
+__name(mikroOrmDeferredAlterWarning, "mikroOrmDeferredAlterWarning");
 function mikroOrmSchemaRepairWarning(repairs) {
   return [
     `[nestjs-durable] store-mikro-orm repaired the durable schema at boot: ${repairs.join("; ")}.`,
@@ -883,29 +910,43 @@ async function ensureMikroOrmDurableSchema(orm, options = {}) {
     if (await readStoredFingerprint(orm) === expected) {
       return;
     }
-    const { repairs, freshInstall } = await healDurableSchema(orm);
-    await writeFingerprint(orm, dialect, expected);
+    const limit = options.blockingAlterRowLimit ?? DEFAULT_BLOCKING_ALTER_ROW_LIMIT;
+    const { repairs, freshInstall, deferred } = await healDurableSchema(orm, dialect, limit);
+    if (deferred.length === 0) await writeFingerprint(orm, dialect, expected);
     if (repairs.length > 0 && !freshInstall) logger.warn(mikroOrmSchemaRepairWarning(repairs));
+    if (deferred.length > 0) logger.warn(mikroOrmDeferredAlterWarning(deferred, limit));
   } finally {
     await releaseSchemaLock(orm, dialect);
   }
 }
 __name(ensureMikroOrmDurableSchema, "ensureMikroOrmDurableSchema");
-async function healDurableSchema(orm) {
+async function healDurableSchema(orm, dialect, blockingAlterRowLimit) {
   const sql = await orm.schema.getUpdateSchemaSQL({
     safe: true
   });
-  const ours = sql.split(";").map((statement) => statement.trim()).filter((statement) => {
+  const ours = mergeColumnTypeChanges(sql.split(";").map((statement) => statement.trim()).filter((statement) => {
     const table = targetTable(statement);
     return table !== void 0 && DURABLE_TABLE_NAMES.has(table);
-  });
+  }));
   const connection = orm.em.getConnection();
   const created = new Set(ours.filter((statement) => /^create\s+table\b/i.test(statement)).map((statement) => targetTable(statement)));
   const repairs = [];
+  const deferred = [];
   for (const statement of ours) {
+    const table = targetTable(statement);
+    if (dialect === "mysql" && !created.has(table) && isColumnTypeChange(statement)) {
+      const rows = await estimatedRowCount(orm, table);
+      if (rows > blockingAlterRowLimit) {
+        deferred.push({
+          table,
+          rows,
+          statement
+        });
+        continue;
+      }
+    }
     try {
       await connection.execute(statement);
-      const table = targetTable(statement);
       const isCreateTable = /^create\s+table\b/i.test(statement);
       if (isCreateTable || !created.has(table)) repairs.push(...describeDurableStatement(statement));
     } catch (err) {
@@ -925,10 +966,45 @@ async function healDurableSchema(orm) {
   ].every((table) => created.has(table));
   return {
     repairs,
-    freshInstall
+    freshInstall,
+    deferred
   };
 }
 __name(healDurableSchema, "healDurableSchema");
+function mergeColumnTypeChanges(statements) {
+  const merged = [];
+  const at = /* @__PURE__ */ new Map();
+  for (const statement of statements) {
+    const table = targetTable(statement);
+    if (!table || !isColumnTypeChange(statement)) {
+      merged.push(statement);
+      continue;
+    }
+    const actions = statement.replace(/^alter\s+table\s+[`"']?[\w$]+[`"']?\s*/i, "");
+    const index = at.get(table);
+    if (index === void 0) {
+      at.set(table, merged.length);
+      merged.push(statement);
+    } else {
+      merged[index] = `${merged[index]}, ${actions}`;
+    }
+  }
+  return merged;
+}
+__name(mergeColumnTypeChanges, "mergeColumnTypeChanges");
+function isColumnTypeChange(statement) {
+  if (!/^alter\s+table\b/i.test(statement)) return false;
+  const actions = splitTopLevel(statement.replace(/^alter\s+table\s+[`"']?[\w$]+[`"']?\s*/i, ""));
+  return actions.length > 0 && actions.every((action) => /^modify\b/i.test(action));
+}
+__name(isColumnTypeChange, "isColumnTypeChange");
+async function estimatedRowCount(orm, table) {
+  const rows = await orm.em.getConnection().execute("select table_rows as table_rows from information_schema.tables where table_schema = database() and table_name = ? limit 1", [
+    table
+  ]);
+  return Number(rows[0]?.table_rows ?? 0);
+}
+__name(estimatedRowCount, "estimatedRowCount");
 function isSafeSqlIdentifier(value) {
   return /^[A-Za-z0-9_]+$/.test(value);
 }
@@ -1012,7 +1088,8 @@ var MikroOrmStateStore = class _MikroOrmStateStore {
   }
   async ensureSchema() {
     await ensureMikroOrmDurableSchema(this.orm, {
-      logger: this.opts.schemaLogger
+      logger: this.opts.schemaLogger,
+      blockingAlterRowLimit: this.opts.schemaBlockingAlterRowLimit
     });
   }
   async tryAdmitSingleton(runId, tag, workflow, limit, retryWakeAt) {
@@ -2242,6 +2319,8 @@ export {
   BufferedEventRepository,
   BufferedSignalEntity,
   BufferedSignalRepository,
+  DATETIME_PRECISION,
+  DEFAULT_BLOCKING_ALTER_ROW_LIMIT,
   ENTITIES,
   MikroOrmStateStore,
   RunAttributeEntity,
@@ -2257,6 +2336,7 @@ export {
   durableEntities,
   durableManagedTables,
   ensureMikroOrmDurableSchema,
+  mikroOrmDeferredAlterWarning,
   mikroOrmSchemaRepairWarning
 };
 //# sourceMappingURL=index.js.map