@plakboek/db 0.1.0 → 0.1.2

package/README.md

@@ -8,11 +8,11 @@ for Plakboek CMS installations.
 - `createDb` -- a Drizzle (`drizzle-orm/postgres-js`) connection factory
   over the `postgres` (porsager) driver.
 - `runMigrations` -- applies this package's own statically registered
-  migrations, holding a Postgres advisory lock for the whole run so
-  concurrent migrators can never double-apply (D-03). What Phase 6's deploy
-  step invokes.
-- `withMigrationLock`, `MigrationLockTimeoutError` -- the session-scoped
-  advisory lock primitive `runMigrations` wraps around every run.
+  migrations, taking a session-scoped Postgres advisory lock internally for
+  the whole run so concurrent migrators can never double-apply (D-03). What
+  Phase 6's deploy step invokes.
+- `MigrationLockTimeoutError` -- thrown by `runMigrations` when another
+  migrator still holds that advisory lock after `lockWaitMs`.
 - The migration authoring convention every migration -- this package's own
   and every host/host-extension migration -- follows: see
   [`MIGRATIONS.md`](./MIGRATIONS.md).

package/dist/index.js

@@ -32,6 +32,15 @@ function createDb(options) {
 		}
 	};
 }
+//#endregion
+//#region src/lock.ts
+/**
+* Fixed advisory-lock key reserved for @plakboek/db's migration runner.
+* Postgres advisory locks share a single namespace per database across every
+* caller -- this key must never be reused by another subsystem within a
+* @plakboek/db-managed database.
+*/
+const MIGRATION_LOCK_KEY = "4839120657231098713";
 var MigrationLockTimeoutError = class extends Error {
 	waitedMs;
 	constructor(waitedMs) {
@@ -92,14 +101,26 @@ async function runGuarded(fn) {
 *
 * The unlock query always runs after `fn` settles (success or failure) --
 * this is expressed as unconditional sequential code (not a `try/finally`)
-* so returning `outcome.value` never needs an unsafe cast to narrow `T`.
+* so returning `outcome.value` never needs an unsafe cast to narrow `T`. The
+* unlock query itself is guarded the same way `fn` is: if `fn` already
+* succeeded (its work is already durable in Postgres) and the unlock query
+* then fails -- e.g. the connection drops between commit and unlock -- that
+* failure is logged rather than thrown, so a lock-release problem can never
+* discard an already-successful `outcome.value`. Postgres releases a
+* session-scoped advisory lock automatically once the session disconnects,
+* so a failed unlock does not leave the lock stuck. If `fn` itself failed,
+* `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);
 	const outcome = await runGuarded(fn);
-	const unlocked = (await client.query("SELECT pg_advisory_unlock($1::bigint) AS unlocked", ["4839120657231098713"])).rows[0]?.unlocked ?? false;
+	const unlockOutcome = await runGuarded(() => client.query("SELECT pg_advisory_unlock($1::bigint) AS unlocked", [MIGRATION_LOCK_KEY]));
 	if (outcome.ok) {
-		if (!unlocked) throw new Error("@plakboek/db: migration lock was not held at release -- this indicates a bug in withMigrationLock or an external pg_advisory_unlock call on the same key");
+		if (!unlockOutcome.ok) {
+			console.error("@plakboek/db: migrations applied successfully, but releasing the migration lock failed -- the lock releases automatically once this session disconnects", unlockOutcome.error);
+			return outcome.value;
+		}
+		if (!(unlockOutcome.value.rows[0]?.unlocked ?? false)) throw new Error("@plakboek/db: migration lock was not held at release -- this indicates a bug in withMigrationLock or an external pg_advisory_unlock call on the same key");
 		return outcome.value;
 	}
 	throw outcome.error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plakboek/db",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Postgres connection factory and migration-lock primitives for Plakboek CMS installations",
   "homepage": "https://github.com/flovan/plakboek/tree/main/packages/db#readme",
   "bugs": {
@@ -25,7 +25,8 @@
     "./package.json": "./package.json"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "dependencies": {
     "pg": "^8.23.0",
@@ -45,7 +46,7 @@
     "drizzle-orm": "^0.45.2"
   },
   "engines": {
-    "node": ">=22.16"
+    "node": ">=22.18"
   },
   "scripts": {
     "build": "tsdown",