@plakboek/db 0.1.1 → 0.2.0

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).
@@ -67,10 +67,11 @@ order. A second overlapping call either observes the first call's
 migrations as already applied, or throws `MigrationLockTimeoutError` if it
 gives up waiting for the lock before the first call finishes.
 
-`MIGRATIONS` ships empty at `0.1.0` -- no product schema exists before
-Phase 2. See [`MIGRATIONS.md`](./MIGRATIONS.md) for how later phases add to
-it, the transactional-vs-existence-guarded-statement decision, and what
-each thrown error class means.
+`MIGRATIONS` starts with `0001_auth_core`, which creates the authentication
+tables (`"user"`, `session`, `account`, `verification`, `two_factor`) and
+the append-only `audit_log`. See [`MIGRATIONS.md`](./MIGRATIONS.md) for how
+later migrations are added, the transactional-vs-existence-guarded-statement
+decision, and what each thrown error class means.
 
 ## Errors
 

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;
@@ -120,12 +141,121 @@ async function withMigrationLock(client, fn, options) {
 * Corrections are always a new, higher-numbered migration. See
 * ../../MIGRATIONS.md for the full authoring convention.
 *
-* MIGRATIONS ships empty at 0.1.0: no product table exists before Phase 2
-* introduces the first schema. The runner, bookkeeping table, advisory
-* lock, and every safety check are fully exercised through fixture
-* registries in this package's own tests (tests/fixtures/migrations.ts).
+* `0001_auth_core` is the first shipped entry: the better-auth core tables
+* and the audit log. The runner's failure modes (ordering, checksums,
+* partial application, locking) are exercised through fixture registries in
+* this package's own tests (tests/fixtures/migrations.ts).
 */
-const MIGRATIONS = Object.freeze([]);
+const MIGRATIONS = Object.freeze([{
+	name: "0001_auth_core",
+	transactional: true,
+	sql: `
+CREATE TABLE IF NOT EXISTS "user" (
+  "id" text PRIMARY KEY NOT NULL,
+  "name" text NOT NULL,
+  "email" text NOT NULL,
+  "email_verified" boolean DEFAULT false NOT NULL,
+  "image" text,
+  "created_at" timestamp with time zone NOT NULL,
+  "updated_at" timestamp with time zone NOT NULL,
+  "role_key" text,
+  "banned" boolean,
+  "ban_reason" text,
+  "ban_expires" timestamp with time zone,
+  "two_factor_enabled" boolean DEFAULT false NOT NULL,
+  CONSTRAINT "user_email_unique" UNIQUE ("email")
+);
+
+CREATE TABLE IF NOT EXISTS "session" (
+  "id" text PRIMARY KEY NOT NULL,
+  "expires_at" timestamp with time zone NOT NULL,
+  "token" text NOT NULL,
+  "created_at" timestamp with time zone NOT NULL,
+  "updated_at" timestamp with time zone NOT NULL,
+  "ip_address" text,
+  "user_agent" text,
+  "user_id" text NOT NULL,
+  "impersonated_by" text,
+  CONSTRAINT "session_token_unique" UNIQUE ("token"),
+  CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id")
+    REFERENCES "user" ("id") ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS "account" (
+  "id" text PRIMARY KEY NOT NULL,
+  "account_id" text NOT NULL,
+  "provider_id" text NOT NULL,
+  "user_id" text NOT NULL,
+  "access_token" text,
+  "refresh_token" text,
+  "id_token" text,
+  "access_token_expires_at" timestamp with time zone,
+  "refresh_token_expires_at" timestamp with time zone,
+  "scope" text,
+  "password" text,
+  "created_at" timestamp with time zone NOT NULL,
+  "updated_at" timestamp with time zone NOT NULL,
+  CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id")
+    REFERENCES "user" ("id") ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS "verification" (
+  "id" text PRIMARY KEY NOT NULL,
+  "identifier" text NOT NULL,
+  "value" text NOT NULL,
+  "expires_at" timestamp with time zone NOT NULL,
+  "created_at" timestamp with time zone NOT NULL,
+  "updated_at" timestamp with time zone NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS "two_factor" (
+  "id" text PRIMARY KEY NOT NULL,
+  "secret" text NOT NULL,
+  "backup_codes" text NOT NULL,
+  "user_id" text NOT NULL,
+  "verified" boolean DEFAULT true,
+  "failed_verification_count" integer DEFAULT 0 NOT NULL,
+  "locked_until" timestamp with time zone,
+  CONSTRAINT "two_factor_user_id_user_id_fk" FOREIGN KEY ("user_id")
+    REFERENCES "user" ("id") ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS "audit_log" (
+  "id" bigserial PRIMARY KEY NOT NULL,
+  "actor_user_id" text,
+  "actor_role_key" text NOT NULL,
+  "impersonator_user_id" text,
+  "permission" text NOT NULL,
+  "action" text NOT NULL,
+  "entity_type" text NOT NULL,
+  "entity_id" text,
+  "outcome" text NOT NULL,
+  "before" jsonb,
+  "after" jsonb,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "audit_log_actor_user_id_user_id_fk" FOREIGN KEY ("actor_user_id")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "audit_log_impersonator_user_id_user_id_fk"
+    FOREIGN KEY ("impersonator_user_id")
+    REFERENCES "user" ("id") ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS "session_user_id_idx"
+  ON "session" USING btree ("user_id");
+CREATE INDEX IF NOT EXISTS "account_user_id_idx"
+  ON "account" USING btree ("user_id");
+CREATE INDEX IF NOT EXISTS "verification_identifier_idx"
+  ON "verification" USING btree ("identifier");
+CREATE INDEX IF NOT EXISTS "two_factor_user_id_idx"
+  ON "two_factor" USING btree ("user_id");
+CREATE INDEX IF NOT EXISTS "two_factor_secret_idx"
+  ON "two_factor" USING btree ("secret");
+CREATE INDEX IF NOT EXISTS "audit_log_actor_idx"
+  ON "audit_log" USING btree ("actor_user_id", "id");
+CREATE INDEX IF NOT EXISTS "audit_log_created_at_idx"
+  ON "audit_log" USING btree ("created_at");
+`
+}]);
 //#endregion
 //#region src/migrate.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plakboek/db",
-  "version": "0.1.1",
+  "version": "0.2.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": {
@@ -46,7 +46,7 @@
     "drizzle-orm": "^0.45.2"
   },
   "engines": {
-    "node": ">=22.16"
+    "node": ">=22.18"
   },
   "scripts": {
     "build": "tsdown",