ddlforge 0.1.1 → 0.2.1

package/dist/src/runner/locksMonitor.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ddlforge - Background lock-queue monitor for PostgreSQL execution supervisor.
+ *
+ * During DDL execution the monitor periodically queries pg_locks and
+ * pg_stat_activity to detect when other backends are queuing behind the
+ * migration's exclusive lock.  If the queue depth exceeds a configurable
+ * threshold the monitor cancels the migration backend via pg_cancel_backend()
+ * and sets the `avalanche` flag so the executor can surface a clear error.
+ *
+ * Design notes
+ * ────────────
+ * • Uses a separate Client connection so it never shares the migration
+ *   transaction (avoids deadlock on the monitor itself).
+ * • All monitor queries use SHORT local timeouts so a hung Postgres cannot
+ *   also jam the monitor.
+ * • The monitor resolves its returned promise with a MonitorResult when it
+ *   self-terminates; callers must await that to detect the avalanche flag.
+ */
+export interface MonitorOptions {
+    /** PID of the migration backend being guarded */
+    migrationPid: number;
+    /**
+     * Factory that returns a fresh client already connected to the database.
+     * The monitor will call end() on it when done.
+     */
+    clientFactory: () => Promise<MonitorClient>;
+    /** Milliseconds between each poll (default: 500 ms) */
+    pollIntervalMs?: number;
+    /**
+     * Number of waiting backends that triggers a cancellation
+     * (default: 1 – i.e. cancel as soon as even one query is blocked).
+     */
+    queueThreshold?: number;
+    /** AbortSignal: when aborted the monitor stops without cancelling */
+    signal?: AbortSignal;
+}
+/**
+ * Minimal pg Client interface required by the monitor.
+ * Using a structural type allows tests to inject simple mocks.
+ */
+export interface MonitorClient {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+    end(): Promise<void>;
+}
+export interface MonitorResult {
+    /** True when the monitor detected a queue avalanche and cancelled the backend */
+    avalanche: boolean;
+    /** Number of waiting backends detected at cancellation time */
+    blockedCount: number;
+    /** ISO timestamp at which cancellation was issued (empty if no cancellation) */
+    cancelledAt: string;
+    /** Reason the monitor stopped */
+    stopReason: 'aborted' | 'avalanche' | 'error' | 'external-stop';
+}
+export interface BlockedBackend {
+    waiterPid: number;
+    waiterQuery: string;
+    waiterState: string;
+    waitEventType: string;
+    waitEvent: string;
+    blockerMode: string;
+}
+/**
+ * Starts a non-blocking background lock-queue monitor.
+ *
+ * Returns a Promise<MonitorResult> that settles when the monitor self-stops
+ * (either via the AbortSignal, an avalanche cancellation, or an internal error).
+ *
+ * Also returns a `stop()` function that callers use to gracefully terminate
+ * the monitor after successful execution.
+ */
+export declare function startLockMonitor(options: MonitorOptions): {
+    result: Promise<MonitorResult>;
+    stop: () => void;
+};
+/**
+ * Determines whether a Postgres error code represents a lock-related failure.
+ *
+ * 55P03 — lock_not_available  (SET LOCAL lock_timeout exceeded)
+ * 57014 — query_canceled      (SET LOCAL statement_timeout exceeded, or pg_cancel_backend)
+ */
+export declare function isLockError(code: string): boolean;
+//# sourceMappingURL=locksMonitor.d.ts.map

package/dist/src/runner/locksMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locksMonitor.d.ts","sourceRoot":"","sources":["../../../src/runner/locksMonitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5C,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;IACrF,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,UAAU,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,eAAe,CAAC;CACjE;AAqCD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG;IACzD,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CA0HA;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/src/runner/locksMonitor.js

@@ -0,0 +1,183 @@
+/**
+ * ddlforge - Background lock-queue monitor for PostgreSQL execution supervisor.
+ *
+ * During DDL execution the monitor periodically queries pg_locks and
+ * pg_stat_activity to detect when other backends are queuing behind the
+ * migration's exclusive lock.  If the queue depth exceeds a configurable
+ * threshold the monitor cancels the migration backend via pg_cancel_backend()
+ * and sets the `avalanche` flag so the executor can surface a clear error.
+ *
+ * Design notes
+ * ────────────
+ * • Uses a separate Client connection so it never shares the migration
+ *   transaction (avoids deadlock on the monitor itself).
+ * • All monitor queries use SHORT local timeouts so a hung Postgres cannot
+ *   also jam the monitor.
+ * • The monitor resolves its returned promise with a MonitorResult when it
+ *   self-terminates; callers must await that to detect the avalanche flag.
+ */
+/** SQL that detects backends queuing on locks held/waited by our migration PID */
+const BLOCKED_QUERY_SQL = `
+  SELECT COUNT(*) AS blocked_count
+  FROM  pg_locks     blocker
+  JOIN  pg_locks     waiter
+       ON  waiter.relation  = blocker.relation
+       AND waiter.locktype  = blocker.locktype
+       AND waiter.pid      <> blocker.pid
+  WHERE blocker.pid    = $1
+    AND blocker.granted = TRUE
+    AND waiter.granted  = FALSE
+`;
+/** SQL that also captures pg_stat_activity info for richer diagnostics */
+const BLOCKED_QUERY_WITH_ACTIVITY_SQL = `
+  SELECT
+    waiter_act.pid              AS waiter_pid,
+    waiter_act.query            AS waiter_query,
+    waiter_act.state            AS waiter_state,
+    waiter_act.wait_event_type  AS wait_event_type,
+    waiter_act.wait_event       AS wait_event,
+    blocker.mode                AS blocker_mode
+  FROM  pg_locks     blocker
+  JOIN  pg_locks     waiter
+       ON  waiter.relation  = blocker.relation
+       AND waiter.locktype  = blocker.locktype
+       AND waiter.pid      <> blocker.pid
+  JOIN  pg_stat_activity waiter_act
+       ON  waiter_act.pid  = waiter.pid
+  WHERE blocker.pid    = $1
+    AND blocker.granted = TRUE
+    AND waiter.granted  = FALSE
+  LIMIT 20
+`;
+/**
+ * Starts a non-blocking background lock-queue monitor.
+ *
+ * Returns a Promise<MonitorResult> that settles when the monitor self-stops
+ * (either via the AbortSignal, an avalanche cancellation, or an internal error).
+ *
+ * Also returns a `stop()` function that callers use to gracefully terminate
+ * the monitor after successful execution.
+ */
+export function startLockMonitor(options) {
+    const { migrationPid, clientFactory, pollIntervalMs = 500, queueThreshold = 1, signal, } = options;
+    let externalStop = false;
+    let stopResolve;
+    const stopPromise = new Promise(r => { stopResolve = r; });
+    /**
+     * Abort handler — fires when AbortSignal triggers from the outside
+     */
+    function onAbort() {
+        stopResolve?.();
+    }
+    if (signal) {
+        if (signal.aborted) {
+            onAbort();
+        }
+        else {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    }
+    const result = (async () => {
+        let client;
+        try {
+            client = await clientFactory();
+            // Set short timeouts on the monitor connection itself
+            await client.query(`SET statement_timeout = '5000'`);
+            await client.query(`SET lock_timeout = '2000'`);
+            while (true) {
+                // Yield to event loop & honour stop signals
+                await Promise.race([
+                    new Promise(r => setTimeout(r, pollIntervalMs)),
+                    stopPromise,
+                ]);
+                // Check if we were asked to stop externally or via signal
+                if (externalStop || signal?.aborted) {
+                    signal?.removeEventListener('abort', onAbort);
+                    return {
+                        avalanche: false,
+                        blockedCount: 0,
+                        cancelledAt: '',
+                        stopReason: externalStop ? 'external-stop' : 'aborted',
+                    };
+                }
+                // Query queue depth
+                let blockedCount = 0;
+                try {
+                    const countResult = await client.query(BLOCKED_QUERY_SQL, [migrationPid]);
+                    blockedCount = parseInt(String(countResult.rows[0]?.['blocked_count'] ?? '0'), 10);
+                }
+                catch {
+                    // Monitor query failed — skip this cycle rather than crashing
+                    continue;
+                }
+                if (blockedCount >= queueThreshold) {
+                    // Gather rich diagnostics before cancellation
+                    let blockedBackends = [];
+                    try {
+                        const actResult = await client.query(BLOCKED_QUERY_WITH_ACTIVITY_SQL, [migrationPid]);
+                        blockedBackends = actResult.rows.map(row => ({
+                            waiterPid: Number(row['waiter_pid']),
+                            waiterQuery: String(row['waiter_query'] ?? ''),
+                            waiterState: String(row['waiter_state'] ?? ''),
+                            waitEventType: String(row['wait_event_type'] ?? ''),
+                            waitEvent: String(row['wait_event'] ?? ''),
+                            blockerMode: String(row['blocker_mode'] ?? ''),
+                        }));
+                        void blockedBackends; // captured for future extension / structured logging
+                    }
+                    catch {
+                        // diagnostics are best-effort; proceed to cancel regardless
+                    }
+                    // Issue pg_cancel_backend — preferred over pg_terminate_backend
+                    // because it gives the migration client a chance to clean up.
+                    try {
+                        await client.query('SELECT pg_cancel_backend($1)', [migrationPid]);
+                    }
+                    catch {
+                        // If cancellation itself fails (e.g. PID already gone), swallow the error
+                    }
+                    const cancelledAt = new Date().toISOString();
+                    signal?.removeEventListener('abort', onAbort);
+                    return {
+                        avalanche: true,
+                        blockedCount,
+                        cancelledAt,
+                        stopReason: 'avalanche',
+                    };
+                }
+            }
+        }
+        catch (err) {
+            signal?.removeEventListener('abort', onAbort);
+            return {
+                avalanche: false,
+                blockedCount: 0,
+                cancelledAt: '',
+                stopReason: 'error',
+            };
+        }
+        finally {
+            try {
+                await client?.end();
+            }
+            catch { /* ignore */ }
+        }
+    })();
+    return {
+        result,
+        stop: () => {
+            externalStop = true;
+            stopResolve?.();
+        },
+    };
+}
+/**
+ * Determines whether a Postgres error code represents a lock-related failure.
+ *
+ * 55P03 — lock_not_available  (SET LOCAL lock_timeout exceeded)
+ * 57014 — query_canceled      (SET LOCAL statement_timeout exceeded, or pg_cancel_backend)
+ */
+export function isLockError(code) {
+    return code === '55P03' || code === '57014';
+}
+//# sourceMappingURL=locksMonitor.js.map

package/dist/src/runner/locksMonitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locksMonitor.js","sourceRoot":"","sources":["../../../src/runner/locksMonitor.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ddlforge",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Ultra-fast, zero-runtime-dependency Postgres migration lock linter and data-loss prevention engine CLI in Node.js 20+ and TypeScript",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -16,8 +16,8 @@
   "scripts": {
     "build": "tsc && node -e \"const fs=require('fs'); try{fs.chmodSync('dist/bin/ddlforge.js', 0o755)}catch{}\"",
     "test:build": "tsc -p tsconfig.test.json",
-    "test": "npm run test:build && node --test dist/test/analyzer.test.js",
-    "test:watch": "node --test --watch dist/test/analyzer.test.js",
+    "test": "npm run test:build && node --test dist/test/analyzer.test.js dist/test/runner.test.js",
+    "test:watch": "node --test --watch dist/test/analyzer.test.js dist/test/runner.test.js",
     "prepack": "node -e \"const fs=require('fs'); try{fs.rmSync('dist/test', {recursive:true, force:true})}catch{}\"",
     "prepublishOnly": "npm run build && node -e \"const fs=require('fs'); try{fs.rmSync('dist/test', {recursive:true, force:true})}catch{}\""
   },
@@ -39,6 +39,10 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
+    "@types/pg": "^8.23.1",
     "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "pg": "^8.23.0"
   }
 }