@plakboek/db 0.4.0 → 0.5.0

package/README.md

@@ -54,12 +54,20 @@ const result = await runMigrations({
   connectionString: process.env.DATABASE_URL!,
   lockWaitMs: 60_000, // optional, default 60000
   lockPollIntervalMs: 250, // optional, default 250
+  onLockWait: () => console.log('Waiting for the migration lock'), // optional
+  onMigrationStart: (name) => console.log(`Applying ${name}`), // optional
 });
 
 // result.applied: names of migrations applied by this call
 // result.alreadyApplied: names that were already applied before this call
 ```
 
+`onLockWait` fires once, the first time another migrator holds the lock, however
+long the wait lasts. `onMigrationStart(name)` fires once per pending migration,
+just before it applies, and never for an already-applied one. Hooks receive
+migration names only. A hook that throws is ignored: it never aborts, rolls back
+or reorders the run.
+
 `runMigrations` is safe to call from every instance of a rolling deploy: it
 opens its own connection, holds the advisory lock for the duration of the
 run, and applies this package's statically registered `MIGRATIONS` in

package/dist/index.d.ts

@@ -24,6 +24,9 @@ export declare class MigrationLockTimeoutError extends Error {
 type LockOptions = {
   readonly waitMs?: number;
   readonly pollIntervalMs?: number;
+  /** Called once, the first time the lock is not immediately available. A
+   * hook that throws is ignored: it never aborts the wait. */
+  readonly onWait?: () => void;
 };
 //#endregion
 //#region src/migrate.d.ts
@@ -75,6 +78,13 @@ type RunMigrationsOptions = {
   readonly connectionString: string;
   readonly lockWaitMs?: number;
   readonly lockPollIntervalMs?: number;
+  /** Called once, the first time the migration lock is held by another
+   * migrator. A hook that throws is ignored: it never aborts the run. */
+  readonly onLockWait?: () => void;
+  /** Called with a pending migration's name just before it applies; never for
+   * an already-applied migration. A hook that throws is ignored: it never
+   * aborts, rolls back or reorders the run. */
+  readonly onMigrationStart?: (name: string) => void;
 };
 type RunMigrationsResult = {
   readonly applied: readonly string[];

package/dist/index.js

@@ -64,10 +64,17 @@ async function tryAcquire(client) {
 * is a session setting: it would persist on this client for every statement
 * run afterwards, including the migrations `withMigrationLock` wraps.
 */
-async function acquire(client, waitMs, pollIntervalMs) {
+async function acquire(client, waitMs, pollIntervalMs, onWait) {
 	const start = Date.now();
+	let reported = false;
 	for (;;) {
 		if (await tryAcquire(client)) return;
+		if (!reported) {
+			reported = true;
+			try {
+				onWait?.();
+			} catch {}
+		}
 		const elapsedMs = Date.now() - start;
 		if (elapsedMs >= waitMs) throw new MigrationLockTimeoutError(elapsedMs);
 		await sleep(pollIntervalMs);
@@ -112,7 +119,7 @@ async function runGuarded(fn) {
 * `fn`'s error is what gets thrown regardless of the unlock outcome.
 */
 async function withMigrationLock(client, fn, options) {
-	await acquire(client, options?.waitMs ?? DEFAULT_WAIT_MS, options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+	await acquire(client, options?.waitMs ?? DEFAULT_WAIT_MS, options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS, options?.onWait);
 	const outcome = await runGuarded(fn);
 	const unlockOutcome = await runGuarded(() => client.query("SELECT pg_advisory_unlock($1::bigint) AS unlocked", [MIGRATION_LOCK_KEY]));
 	if (outcome.ok) {
@@ -841,7 +848,7 @@ async function applyNonTransactional(client, migration) {
 * registry order. Does not acquire any lock -- callers that need
 * concurrency safety use `migrateWithRegistry`. Exported directly so tests
 * can prove the unlocked case has no safety (the negative control). */
-async function applyPendingMigrations(client, migrations) {
+async function applyPendingMigrations(client, migrations, onMigrationStart) {
 	await ensureBookkeepingTable(client);
 	const appliedRows = await readAppliedRows(client);
 	validateAppliedHistory(appliedRows, migrations);
@@ -850,6 +857,9 @@ async function applyPendingMigrations(client, migrations) {
 	const pending = migrations.filter((migration) => !alreadyAppliedSet.has(migration.name));
 	const applied = [];
 	for (const migration of pending) {
+		try {
+			onMigrationStart?.(migration.name);
+		} catch {}
 		if (migration.transactional) await applyTransactional(client, migration);
 		else await applyNonTransactional(client, migration);
 		applied.push(migration.name);
@@ -867,9 +877,10 @@ async function migrateWithRegistry(options) {
 	const client = new Client({ connectionString: options.connectionString });
 	await client.connect();
 	try {
-		return await withMigrationLock(client, () => applyPendingMigrations(client, options.migrations), {
+		return await withMigrationLock(client, () => applyPendingMigrations(client, options.migrations, options.onMigrationStart), {
 			waitMs: options.lockWaitMs,
-			pollIntervalMs: options.lockPollIntervalMs
+			pollIntervalMs: options.lockPollIntervalMs,
+			onWait: options.onLockWait
 		});
 	} finally {
 		await client.end();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plakboek/db",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Postgres connection factory and migration-lock primitives for Plakboek CMS installations",
   "homepage": "https://github.com/flovan/plakboek/tree/main/packages/db#readme",
   "bugs": {