@plakboek/db 0.3.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
@@ -72,7 +80,10 @@ tables (`"user"`, `session`, `account`, `verification`, `two_factor`) and
 the append-only `audit_log`. `0002_content_engine` follows it, creating the
 content engine tables (`content_types`, `content_type_fields`,
 `content_entries`, `entry_revisions` and their history, seed, reference and
-settings tables) used by `@plakboek/content`. See
+settings tables) used by `@plakboek/content`. `0003_page_block_engine`
+creates the page and block-tree tables (`pages`, `page_blocks`,
+`block_revisions`, `page_publications`, `page_url_history`,
+`page_engine_settings`) used by `@plakboek/pages`. 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.

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) {
@@ -143,15 +150,17 @@ async function withMigrationLock(client, fn, options) {
 *
 * `0001_auth_core` is the first shipped entry: the better-auth core tables
 * and the audit log. `0002_content_engine` is the second: the content-type,
-* field and entry tables `@plakboek/content` builds on. 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).
+* field and entry tables `@plakboek/content` builds on. `0003_page_block_engine`
+* is the third: the page and block-tree tables `@plakboek/pages` builds on.
+* 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([{
-	name: "0001_auth_core",
-	transactional: true,
-	sql: `
+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,
@@ -257,10 +266,11 @@ CREATE INDEX IF NOT EXISTS "audit_log_actor_idx"
 CREATE INDEX IF NOT EXISTS "audit_log_created_at_idx"
   ON "audit_log" USING btree ("created_at");
 `
-}, {
-	name: "0002_content_engine",
-	transactional: true,
-	sql: `
+	},
+	{
+		name: "0002_content_engine",
+		transactional: true,
+		sql: `
 CREATE TABLE IF NOT EXISTS "content_types" (
   "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
   "key" text NOT NULL,
@@ -504,7 +514,193 @@ CREATE INDEX IF NOT EXISTS "content_entry_references_target_idx"
 CREATE INDEX IF NOT EXISTS "content_field_key_history_field_idx"
   ON "content_field_key_history" USING btree ("field_id", "id");
 `
-}]);
+	},
+	{
+		name: "0003_page_block_engine",
+		transactional: true,
+		sql: `
+CREATE TABLE IF NOT EXISTS "pages" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "translation_group" uuid NOT NULL,
+  "locale" text NOT NULL,
+  "parent_page_id" uuid REFERENCES "pages" ("id") ON DELETE RESTRICT,
+  "slug" text NOT NULL,
+  "slug_source" text NOT NULL DEFAULT 'generated',
+  "path" text NOT NULL,
+  "resolved_path" text,
+  "title" text NOT NULL,
+  "status" text NOT NULL DEFAULT 'draft',
+  "seo" jsonb,
+  "version" integer NOT NULL DEFAULT 1,
+  "live_publication_id" uuid,
+  "locked_by" text,
+  "locked_at" timestamp with time zone,
+  "created_by" text,
+  "updated_by" text,
+  "created_at" timestamp with time zone NOT NULL,
+  "updated_at" timestamp with time zone NOT NULL,
+  "published_at" timestamp with time zone,
+  "first_published_at" timestamp with time zone,
+  "scheduled_at" timestamp with time zone,
+  "trashed_at" timestamp with time zone,
+  CONSTRAINT "pages_locked_by_user_id_fk" FOREIGN KEY ("locked_by")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "pages_created_by_user_id_fk" FOREIGN KEY ("created_by")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "pages_updated_by_user_id_fk" FOREIGN KEY ("updated_by")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "pages_locale_path_unique" UNIQUE ("locale", "path"),
+  CONSTRAINT "pages_group_locale_unique" UNIQUE ("translation_group", "locale"),
+  CONSTRAINT "pages_status_check"
+    CHECK ("status" IN ('draft', 'published', 'scheduled', 'trashed')),
+  CONSTRAINT "pages_slug_source_check"
+    CHECK ("slug_source" IN ('generated', 'manual')),
+  CONSTRAINT "pages_scheduled_at_check"
+    CHECK ("status" <> 'scheduled' OR "scheduled_at" IS NOT NULL),
+  CONSTRAINT "pages_resolved_path_check"
+    CHECK ("resolved_path" IS NULL OR "status" = 'published'),
+  CONSTRAINT "pages_lock_pair_check"
+    CHECK (("locked_by" IS NULL) = ("locked_at" IS NULL)),
+  CONSTRAINT "pages_path_check"
+    CHECK ("path" <> '' AND "path" NOT LIKE '/%' AND "path" NOT LIKE '%/')
+);
+
+CREATE TABLE IF NOT EXISTS "page_blocks" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "owner_type" text NOT NULL,
+  "owner_id" uuid NOT NULL,
+  "locale" text NOT NULL,
+  "parent_block_id" uuid REFERENCES "page_blocks" ("id") ON DELETE CASCADE,
+  "block_type" text NOT NULL,
+  "props" jsonb NOT NULL DEFAULT '{}'::jsonb,
+  "schema_version" integer NOT NULL,
+  "depth" integer NOT NULL,
+  "sort_order" integer NOT NULL,
+  "version" integer NOT NULL DEFAULT 1,
+  "created_by" text,
+  "updated_by" text,
+  "created_at" timestamp with time zone NOT NULL,
+  "updated_at" timestamp with time zone NOT NULL,
+  CONSTRAINT "page_blocks_created_by_user_id_fk" FOREIGN KEY ("created_by")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "page_blocks_updated_by_user_id_fk" FOREIGN KEY ("updated_by")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "page_blocks_owner_type_check" CHECK ("owner_type" IN ('page')),
+  CONSTRAINT "page_blocks_props_object_check"
+    CHECK (jsonb_typeof("props") = 'object'),
+  CONSTRAINT "page_blocks_schema_version_check" CHECK ("schema_version" >= 1),
+  CONSTRAINT "page_blocks_depth_check" CHECK ("depth" >= 0)
+);
+
+CREATE TABLE IF NOT EXISTS "block_revisions" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "block_id" uuid REFERENCES "page_blocks" ("id") ON DELETE SET NULL,
+  "owner_type" text NOT NULL,
+  "owner_id" uuid NOT NULL,
+  "locale" text NOT NULL,
+  "revision_batch_id" uuid NOT NULL,
+  "change_type" text NOT NULL,
+  "kind" text NOT NULL,
+  "block_type" text NOT NULL,
+  "parent_block_id" uuid,
+  "sort_order" integer NOT NULL,
+  "depth" integer NOT NULL,
+  "props" jsonb NOT NULL,
+  "schema_version" integer NOT NULL,
+  "author_id" text,
+  "created_at" timestamp with time zone NOT NULL,
+  CONSTRAINT "block_revisions_author_id_user_id_fk" FOREIGN KEY ("author_id")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "block_revisions_change_type_check"
+    CHECK ("change_type" IN ('create', 'update', 'move', 'delete')),
+  CONSTRAINT "block_revisions_kind_check" CHECK ("kind" IN ('save', 'publish')),
+  CONSTRAINT "block_revisions_props_object_check"
+    CHECK (jsonb_typeof("props") = 'object')
+);
+
+CREATE TABLE IF NOT EXISTS "page_publications" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "page_id" uuid NOT NULL,
+  "locale" text NOT NULL,
+  "is_draft" boolean NOT NULL DEFAULT false,
+  "snapshot" jsonb NOT NULL,
+  "revision_manifest" jsonb NOT NULL,
+  "manifest_hash" text NOT NULL,
+  "published_by" text,
+  "published_at" timestamp with time zone NOT NULL,
+  CONSTRAINT "page_publications_page_id_fk" FOREIGN KEY ("page_id")
+    REFERENCES "pages" ("id") ON DELETE CASCADE,
+  CONSTRAINT "page_publications_published_by_user_id_fk" FOREIGN KEY ("published_by")
+    REFERENCES "user" ("id") ON DELETE SET NULL,
+  CONSTRAINT "page_publications_snapshot_object_check"
+    CHECK (jsonb_typeof("snapshot") = 'object'),
+  CONSTRAINT "page_publications_manifest_object_check"
+    CHECK (jsonb_typeof("revision_manifest") = 'object')
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'pages_live_publication_id_fk'
+  ) THEN
+    ALTER TABLE "pages"
+      ADD CONSTRAINT "pages_live_publication_id_fk"
+      FOREIGN KEY ("live_publication_id") REFERENCES "page_publications" ("id") ON DELETE SET NULL;
+  END IF;
+END $$;
+
+CREATE TABLE IF NOT EXISTS "page_url_history" (
+  "id" bigserial PRIMARY KEY,
+  "page_id" uuid,
+  "translation_group" uuid NOT NULL,
+  "locale" text NOT NULL,
+  "old_path" text NOT NULL,
+  "reason" text NOT NULL,
+  "changed_at" timestamp with time zone NOT NULL,
+  CONSTRAINT "page_url_history_page_id_fk" FOREIGN KEY ("page_id")
+    REFERENCES "pages" ("id") ON DELETE SET NULL,
+  CONSTRAINT "page_url_history_reason_check" CHECK (
+    "reason" IN ('slug_changed', 'moved', 'pattern_changed', 'unpublished', 'trashed', 'deleted')
+  )
+);
+
+CREATE TABLE IF NOT EXISTS "page_engine_settings" (
+  "id" smallint PRIMARY KEY DEFAULT 1,
+  "page_edit_locking" boolean NOT NULL DEFAULT true,
+  "url_pattern" text NOT NULL DEFAULT '{locale}/{path}',
+  "updated_at" timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT "page_engine_settings_id_check" CHECK ("id" = 1)
+);
+
+INSERT INTO "page_engine_settings" ("id") VALUES (1) ON CONFLICT ("id") DO NOTHING;
+
+CREATE INDEX IF NOT EXISTS "pages_parent_idx" ON "pages" USING btree ("parent_page_id");
+CREATE INDEX IF NOT EXISTS "pages_locale_status_idx" ON "pages" USING btree ("locale", "status");
+CREATE INDEX IF NOT EXISTS "pages_translation_group_idx" ON "pages" USING btree ("translation_group");
+CREATE INDEX IF NOT EXISTS "pages_locale_path_prefix_idx"
+  ON "pages" USING btree ("locale", "path" text_pattern_ops);
+CREATE UNIQUE INDEX IF NOT EXISTS "pages_locale_resolved_path_unique"
+  ON "pages" USING btree ("locale", "resolved_path")
+  WHERE "resolved_path" IS NOT NULL;
+CREATE INDEX IF NOT EXISTS "page_blocks_owner_idx"
+  ON "page_blocks" USING btree ("owner_type", "owner_id", "locale");
+CREATE INDEX IF NOT EXISTS "page_blocks_parent_sort_idx"
+  ON "page_blocks" USING btree ("parent_block_id", "sort_order");
+CREATE INDEX IF NOT EXISTS "page_blocks_type_version_idx"
+  ON "page_blocks" USING btree ("block_type", "schema_version");
+CREATE INDEX IF NOT EXISTS "block_revisions_owner_created_idx"
+  ON "block_revisions" USING btree ("owner_type", "owner_id", "locale", "created_at" DESC);
+CREATE INDEX IF NOT EXISTS "block_revisions_batch_idx"
+  ON "block_revisions" USING btree ("revision_batch_id");
+CREATE INDEX IF NOT EXISTS "block_revisions_block_idx"
+  ON "block_revisions" USING btree ("block_id", "created_at" DESC);
+CREATE INDEX IF NOT EXISTS "page_publications_page_draft_published_idx"
+  ON "page_publications" USING btree ("page_id", "is_draft", "published_at" DESC);
+CREATE INDEX IF NOT EXISTS "page_url_history_locale_path_idx"
+  ON "page_url_history" USING btree ("locale", "old_path");
+`
+	}
+]);
 //#endregion
 //#region src/migrate.ts
 /**
@@ -652,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);
@@ -661,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);
@@ -678,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.3.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": {