@fedify/postgres 2.5.0-dev.2500 → 2.5.0-dev.2513

package/README.md

@@ -34,6 +34,12 @@ next initialization converts that table to logged storage.  PostgreSQL rewrites
 the table and takes an `ACCESS EXCLUSIVE` lock during this one-time migration,
 so schedule the upgrade accordingly for a large or busy table.
 
+Expiry cleanup can use an expression index without changing the table schema.
+New empty tables receive it automatically with a pooled client.  Existing
+populated tables and deployments using `initialized: true` need an explicit
+index migration.  See the [expiry-index guide] for concurrent index creation,
+rolling upgrades, and calendar-time semantics.
+
 [JSR badge]: https://jsr.io/badges/@fedify/postgres
 [JSR]: https://jsr.io/@fedify/postgres
 [npm badge]: https://img.shields.io/npm/v/@fedify/postgres?logo=npm
@@ -43,6 +49,7 @@ so schedule the upgrade accordingly for a large or busy table.
 [`MessageQueue`]: https://jsr.io/@fedify/fedify/doc/federation/~/MessageQueue
 [`PostgresKvStore`]: https://jsr.io/@fedify/postgres/doc/~/PostgresKvStore
 [`PostgresMessageQueue`]: https://jsr.io/@fedify/postgres/doc/~/PostgresMessageQueue
+[expiry-index guide]: https://fedify.dev/manual/kv#postgresql-expiry-index
 
 
 Installation

package/dist/kv.cjs

@@ -53,7 +53,7 @@ var PostgresKvStore = class {
 		this.#skipDdl = options.initialized ?? false;
 	}
 	#expire() {
-		const callerOwned = "savepoint" in this.#sql && typeof this.#sql.savepoint === "function" || "release" in this.#sql && typeof this.#sql.release === "function";
+		const callerOwned = this.#callerOwned();
 		if (this.#expiring) return callerOwned ? this.#expiring : void 0;
 		if (performance.now() < this.#nextExpiry) return;
 		this.#expiring = (async () => {
@@ -85,7 +85,10 @@ var PostgresKvStore = class {
         SELECT tableoid AS relation, ctid AS tid
         FROM ${this.#sql(this.#tableName)}
         WHERE (SELECT acquired FROM sweep_lock)
-          AND ttl IS NOT NULL AND created + ttl < statement_timestamp()
+          AND ttl IS NOT NULL
+          AND timezone('UTC', timezone('UTC', created) + ttl)
+            < statement_timestamp()
+          AND created + ttl < statement_timestamp()
         LIMIT ${expiryBatchSize} FOR UPDATE SKIP LOCKED
       ), deleted AS (
         DELETE FROM ${this.#sql(this.#tableName)}
@@ -221,6 +224,7 @@ var PostgresKvStore = class {
 		this.#initializing ??= (async () => {
 			logger.debug("Initializing the key–value store table {tableName}...", { tableName: this.#tableName });
 			if (!this.#skipDdl) await this.#initializeTable();
+			if (!this.#skipDdl && !this.#callerOwned()) await this.#initializeExpiryIndex();
 			this.#driverSerializesJson = await require_utils.driverSerializesJson(this.#sql);
 			this.#initialized = true;
 			logger.debug("Initialized the key–value store table {tableName}.", { tableName: this.#tableName });
@@ -259,6 +263,94 @@ var PostgresKvStore = class {
         `;
 		}
 	}
+	#callerOwned() {
+		return "savepoint" in this.#sql && typeof this.#sql.savepoint === "function" || "release" in this.#sql && typeof this.#sql.release === "function";
+	}
+	async #initializeExpiryIndex() {
+		try {
+			await this.#sql.begin("isolation level read committed", async (sql) => {
+				await sql`SET LOCAL lock_timeout = '250ms'`;
+				await sql`SET LOCAL statement_timeout = '2s'`;
+				const [table] = await sql`
+          SELECT c.oid, c.relkind, c.relrowsecurity,
+            pg_has_role(current_user, c.relowner, 'USAGE') AS owner,
+            EXISTS (SELECT 1 FROM pg_inherits WHERE inhparent = c.oid) AS children,
+            format('%I.%I', n.nspname, c.relname) AS name,
+            'idx_fedify_kv_expiry_' || substr(md5(
+              format('%I.%I', n.nspname, c.relname)
+            ), 1, 16) AS idx
+          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.oid = (SELECT typrelid FROM pg_type
+            WHERE oid = pg_typeof(NULL::${sql(this.#tableName)})::oid)
+        `;
+				const indexed = async () => {
+					const [result] = await sql`
+            SELECT EXISTS (
+              SELECT 1 FROM pg_index i
+              JOIN pg_class c ON c.oid = i.indexrelid
+              JOIN pg_am a ON a.oid = c.relam
+              JOIN pg_opclass o ON o.oid = i.indclass[0]
+              WHERE i.indrelid = ${table.oid}::oid
+                AND i.indisvalid AND i.indisready AND i.indislive
+                AND NOT i.indisunique AND i.indnatts = 1
+                AND a.amname = 'btree' AND i.indkey[0] = 0
+                AND o.opcdefault AND o.opcintype = 'timestamptz'::regtype
+                AND pg_get_indexdef(i.indexrelid, 1, false) IN (
+                  ${"timezone('UTC'::text, (timezone('UTC'::text, created) + ttl))"},
+                  ${"(((created AT TIME ZONE 'UTC'::text) + ttl) AT TIME ZONE 'UTC'::text)"}
+                )
+                AND (i.indpred IS NULL OR
+                  pg_get_expr(i.indpred, i.indrelid) = '(ttl IS NOT NULL)')
+            ) AS present
+          `;
+					return result.present;
+				};
+				if (await indexed()) return;
+				const manual = () => logger.warn("Provision the expiry index for {tableName} manually; see {guide}.", {
+					tableName: table.name,
+					guide: "https://fedify.dev/manual/kv#postgresql-expiry-index"
+				});
+				if (!table.owner || table.relrowsecurity || table.relkind !== "r" && table.relkind !== "p" || table.relkind === "r" && table.children) {
+					manual();
+					return;
+				}
+				const empty = async () => {
+					const [result] = await sql.unsafe(`SELECT NOT EXISTS (SELECT 1 FROM ${table.name} LIMIT 1) AS empty`);
+					return result.empty;
+				};
+				if (!await empty()) {
+					manual();
+					return;
+				}
+				const [lock] = await sql`
+          SELECT pg_try_advisory_xact_lock(
+            (hashtext('fedify.postgres.kv.index')::bigint << 32) |
+            ${table.oid}::bigint
+          ) AS acquired
+        `;
+				if (!lock.acquired) return;
+				await sql.unsafe(`LOCK TABLE ${table.name} IN SHARE MODE`);
+				if (await indexed()) return;
+				if (!await empty()) {
+					manual();
+					return;
+				}
+				const [ddl] = await sql`
+          SELECT format(
+            'CREATE INDEX %I ON %s ((timezone(''UTC'', timezone(''UTC'', created) + ttl))) WHERE ttl IS NOT NULL',
+            ${table.idx}::text, ${table.name}::text
+          ) AS command
+        `;
+				await sql.unsafe(ddl.command);
+			});
+		} catch (error) {
+			logger.warn("Failed to provision the expiry index for {tableName}: {error}. See {guide}.", {
+				tableName: this.#tableName,
+				error,
+				guide: "https://fedify.dev/manual/kv#postgresql-expiry-index"
+			});
+		}
+	}
 	/**
 	* Drops the table used by the key–value store.  Does nothing if the table
 	* does not exist.

package/dist/kv.d.cts

@@ -19,6 +19,8 @@ interface PostgresKvStoreOptions {
   * This skips only the table's schema DDL.  Driver-specific runtime setup,
   * such as detecting whether the driver serializes JSON parameters on its
   * own, still runs before the first key is read or written.
+  * It also skips automatic expiry-index provisioning.  See the PostgreSQL
+  * key–value store migration guide for the index to add to your own DDL.
   * @default `false`
   */
   readonly initialized?: boolean;

package/dist/kv.d.ts

@@ -19,6 +19,8 @@ interface PostgresKvStoreOptions {
   * This skips only the table's schema DDL.  Driver-specific runtime setup,
   * such as detecting whether the driver serializes JSON parameters on its
   * own, still runs before the first key is read or written.
+  * It also skips automatic expiry-index provisioning.  See the PostgreSQL
+  * key–value store migration guide for the index to add to your own DDL.
   * @default `false`
   */
   readonly initialized?: boolean;

package/dist/kv.js

@@ -50,7 +50,7 @@ var PostgresKvStore = class {
 		this.#skipDdl = options.initialized ?? false;
 	}
 	#expire() {
-		const callerOwned = "savepoint" in this.#sql && typeof this.#sql.savepoint === "function" || "release" in this.#sql && typeof this.#sql.release === "function";
+		const callerOwned = this.#callerOwned();
 		if (this.#expiring) return callerOwned ? this.#expiring : void 0;
 		if (performance.now() < this.#nextExpiry) return;
 		this.#expiring = (async () => {
@@ -82,7 +82,10 @@ var PostgresKvStore = class {
         SELECT tableoid AS relation, ctid AS tid
         FROM ${this.#sql(this.#tableName)}
         WHERE (SELECT acquired FROM sweep_lock)
-          AND ttl IS NOT NULL AND created + ttl < statement_timestamp()
+          AND ttl IS NOT NULL
+          AND timezone('UTC', timezone('UTC', created) + ttl)
+            < statement_timestamp()
+          AND created + ttl < statement_timestamp()
         LIMIT ${expiryBatchSize} FOR UPDATE SKIP LOCKED
       ), deleted AS (
         DELETE FROM ${this.#sql(this.#tableName)}
@@ -218,6 +221,7 @@ var PostgresKvStore = class {
 		this.#initializing ??= (async () => {
 			logger.debug("Initializing the key–value store table {tableName}...", { tableName: this.#tableName });
 			if (!this.#skipDdl) await this.#initializeTable();
+			if (!this.#skipDdl && !this.#callerOwned()) await this.#initializeExpiryIndex();
 			this.#driverSerializesJson = await driverSerializesJson(this.#sql);
 			this.#initialized = true;
 			logger.debug("Initialized the key–value store table {tableName}.", { tableName: this.#tableName });
@@ -256,6 +260,94 @@ var PostgresKvStore = class {
         `;
 		}
 	}
+	#callerOwned() {
+		return "savepoint" in this.#sql && typeof this.#sql.savepoint === "function" || "release" in this.#sql && typeof this.#sql.release === "function";
+	}
+	async #initializeExpiryIndex() {
+		try {
+			await this.#sql.begin("isolation level read committed", async (sql) => {
+				await sql`SET LOCAL lock_timeout = '250ms'`;
+				await sql`SET LOCAL statement_timeout = '2s'`;
+				const [table] = await sql`
+          SELECT c.oid, c.relkind, c.relrowsecurity,
+            pg_has_role(current_user, c.relowner, 'USAGE') AS owner,
+            EXISTS (SELECT 1 FROM pg_inherits WHERE inhparent = c.oid) AS children,
+            format('%I.%I', n.nspname, c.relname) AS name,
+            'idx_fedify_kv_expiry_' || substr(md5(
+              format('%I.%I', n.nspname, c.relname)
+            ), 1, 16) AS idx
+          FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE c.oid = (SELECT typrelid FROM pg_type
+            WHERE oid = pg_typeof(NULL::${sql(this.#tableName)})::oid)
+        `;
+				const indexed = async () => {
+					const [result] = await sql`
+            SELECT EXISTS (
+              SELECT 1 FROM pg_index i
+              JOIN pg_class c ON c.oid = i.indexrelid
+              JOIN pg_am a ON a.oid = c.relam
+              JOIN pg_opclass o ON o.oid = i.indclass[0]
+              WHERE i.indrelid = ${table.oid}::oid
+                AND i.indisvalid AND i.indisready AND i.indislive
+                AND NOT i.indisunique AND i.indnatts = 1
+                AND a.amname = 'btree' AND i.indkey[0] = 0
+                AND o.opcdefault AND o.opcintype = 'timestamptz'::regtype
+                AND pg_get_indexdef(i.indexrelid, 1, false) IN (
+                  ${"timezone('UTC'::text, (timezone('UTC'::text, created) + ttl))"},
+                  ${"(((created AT TIME ZONE 'UTC'::text) + ttl) AT TIME ZONE 'UTC'::text)"}
+                )
+                AND (i.indpred IS NULL OR
+                  pg_get_expr(i.indpred, i.indrelid) = '(ttl IS NOT NULL)')
+            ) AS present
+          `;
+					return result.present;
+				};
+				if (await indexed()) return;
+				const manual = () => logger.warn("Provision the expiry index for {tableName} manually; see {guide}.", {
+					tableName: table.name,
+					guide: "https://fedify.dev/manual/kv#postgresql-expiry-index"
+				});
+				if (!table.owner || table.relrowsecurity || table.relkind !== "r" && table.relkind !== "p" || table.relkind === "r" && table.children) {
+					manual();
+					return;
+				}
+				const empty = async () => {
+					const [result] = await sql.unsafe(`SELECT NOT EXISTS (SELECT 1 FROM ${table.name} LIMIT 1) AS empty`);
+					return result.empty;
+				};
+				if (!await empty()) {
+					manual();
+					return;
+				}
+				const [lock] = await sql`
+          SELECT pg_try_advisory_xact_lock(
+            (hashtext('fedify.postgres.kv.index')::bigint << 32) |
+            ${table.oid}::bigint
+          ) AS acquired
+        `;
+				if (!lock.acquired) return;
+				await sql.unsafe(`LOCK TABLE ${table.name} IN SHARE MODE`);
+				if (await indexed()) return;
+				if (!await empty()) {
+					manual();
+					return;
+				}
+				const [ddl] = await sql`
+          SELECT format(
+            'CREATE INDEX %I ON %s ((timezone(''UTC'', timezone(''UTC'', created) + ttl))) WHERE ttl IS NOT NULL',
+            ${table.idx}::text, ${table.name}::text
+          ) AS command
+        `;
+				await sql.unsafe(ddl.command);
+			});
+		} catch (error) {
+			logger.warn("Failed to provision the expiry index for {tableName}: {error}. See {guide}.", {
+				tableName: this.#tableName,
+				error,
+				guide: "https://fedify.dev/manual/kv#postgresql-expiry-index"
+			});
+		}
+	}
 	/**
 	* Drops the table used by the key–value store.  Does nothing if the table
 	* does not exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/postgres",
-  "version": "2.5.0-dev.2500+0a9d005b",
+  "version": "2.5.0-dev.2513+d7ab5950",
   "description": "PostgreSQL drivers for Fedify",
   "keywords": [
     "fedify",
@@ -71,15 +71,14 @@
   },
   "peerDependencies": {
     "postgres": "^3.4.7",
-    "@fedify/fedify": "^2.5.0-dev.2500+0a9d005b"
+    "@fedify/fedify": "^2.5.0-dev.2513+d7ab5950"
   },
   "devDependencies": {
     "@js-temporal/polyfill": "^0.5.1",
-    "@std/async": "npm:@jsr/std__async@^1.0.13",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.0",
     "@fedify/fixture": "^2.0.0",
-    "@fedify/testing": "^2.5.0-dev.2500+0a9d005b"
+    "@fedify/testing": "^2.5.0-dev.2513+d7ab5950"
   },
   "scripts": {
     "build:self": "tsdown",