pgserve 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to `pgserve` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.5
+
+### Fixed
+
+- `PostgresManager` now extends `EventEmitter` and emits `backendExited`
+  with `{ code, expected }` when the postgres child exits. `expected=true`
+  is reserved for shutdowns initiated by `stop()`; everything else is
+  treated as a fault. `PgserveDaemon` re-emits unexpected exits as
+  `backendDiedUnexpectedly`, and the daemon CLI wrapper subscribes and
+  exits non-zero so a process supervisor (`genie serve`, pm2, systemd)
+  can restart the daemon cleanly. Previously, an external SIGKILL of
+  the postgres backend left the wrapper alive in `epoll_wait` while the
+  control socket accepted connections forever — pgserve#45.
+
+## 2.0.4
+
+### Fixed
+
+- `_startPostgres()` now removes a stale `postmaster.pid` from the data
+  directory before spawning postgres. Previously, an unclean shutdown
+  (SIGKILL, machine reboot, OOM) left a `postmaster.pid` whose recorded
+  PID was no longer alive, and postgres refused to start with
+  `FATAL: lock file "postmaster.pid" already exists` on the next boot.
+  Operators had to `rm postmaster.pid` manually to recover. A live PID
+  is never touched, so a real concurrent postmaster still surfaces the
+  normal lock conflict. ([#46](https://github.com/namastexlabs/pgserve/pull/46),
+  fixes [#45](https://github.com/namastexlabs/pgserve/issues/45))
+
 ## 2.0.0 — Unreleased
 
 > The release date will replace "Unreleased" when the v2.0.0 release workflow

package/bin/postgres-server.js

@@ -83,6 +83,20 @@ async function runDaemonSubcommand(daemonArgs) {
   // `pgserve daemon` (long-running)
   const opts = parseDaemonArgs(daemonArgs);
   const daemon = new PgserveDaemon(opts);
+
+  // When the postgres backend dies on us (SIGKILL, OOM, segfault, anything
+  // other than a clean stop()), exit non-zero so a process supervisor can
+  // restart the daemon cleanly. Without this, the wrapper sat alive in
+  // epoll_wait while postgres was dead, and clients got "control.sock
+  // accepts but never replies" — pgserve#45.
+  daemon.on('backendDiedUnexpectedly', ({ code }) => {
+    console.error(
+      `pgserve daemon: postgres backend exited unexpectedly (code=${code}); ` +
+      `the wrapper is exiting so a process supervisor can restart it.`
+    );
+    process.exit(1);
+  });
+
   try {
     await daemon.start();
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",

package/src/daemon.js

@@ -257,6 +257,18 @@ export class PgserveDaemon extends EventEmitter {
       enablePgvector: options.enablePgvector || false,
     });
 
+    // Forward unexpected backend deaths to wrapper-level supervisors. A clean
+    // stop() sets PostgresManager._stopping=true so the event arrives with
+    // expected=true and we leave the daemon alone; an external SIGKILL / OOM
+    // / segfault arrives with expected=false and we re-emit so the wrapper
+    // can exit non-zero and let a process supervisor (genie serve, pm2,
+    // systemd) restart us cleanly. See pgserve#45.
+    this.pgManager.on('backendExited', (info) => {
+      if (!info.expected) {
+        this.emit('backendDiedUnexpectedly', info);
+      }
+    });
+
     this.server = null;
     this.tcpServers = [];
     this.connections = new Set();

package/src/postgres.js

@@ -14,6 +14,7 @@
  */
 
 /* global fetch, Bun */
+import { EventEmitter } from 'events';
 import os from 'os';
 import path from 'path';
 import fs from 'fs';
@@ -419,8 +420,9 @@ function findAvailableTcpPort() {
   return port;
 }
 
-export class PostgresManager {
+export class PostgresManager extends EventEmitter {
   constructor(options = {}) {
+    super();
     this.dataDir = options.dataDir || null; // null = memory mode (temp dir)
     this.port = options.port ?? 5433; // Internal PG port (router listens on different port)
     this.user = options.user || 'postgres';
@@ -709,11 +711,57 @@ export class PostgresManager {
     }
   }
 
+  /**
+   * Detect and remove a stale postmaster.pid that postgres would otherwise
+   * refuse to start against. Stale = the PID written into the file is not
+   * alive on this host. Called at the top of _startPostgres so that crash
+   * / SIGKILL / unclean reboot recovery is automatic.
+   *
+   * Real running backends are NEVER touched — if the PID is alive we leave
+   * the file alone and let postgres surface its normal "lock file already
+   * exists" error so the operator sees the conflict.
+   */
+  async _ensureNoStalePostmasterLock() {
+    const pidFile = path.join(this.databaseDir, 'postmaster.pid');
+    let raw;
+    try {
+      raw = await fs.promises.readFile(pidFile, 'utf-8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return;
+      throw err;
+    }
+    const firstLine = (raw.split('\n')[0] ?? '').trim();
+    const pid = Number.parseInt(firstLine, 10);
+    if (!Number.isInteger(pid) || pid <= 0) {
+      this.logger.warn(
+        { pidFile, firstLine },
+        'postmaster.pid is unparseable; removing as stale'
+      );
+      await fs.promises.unlink(pidFile).catch(() => {});
+      return;
+    }
+    let alive = false;
+    try {
+      process.kill(pid, 0);
+      alive = true;
+    } catch (err) {
+      // EPERM = process exists but we can't signal it — still alive.
+      alive = err.code === 'EPERM';
+    }
+    if (alive) return;
+    this.logger.info(
+      { pidFile, stalePid: pid },
+      'Removing stale postmaster.pid (PID not running) before postgres start'
+    );
+    await fs.promises.unlink(pidFile).catch(() => {});
+  }
+
   /**
    * Start the PostgreSQL server process
    * Uses Bun.spawn() for ~40% faster process startup
    */
   async _startPostgres() {
+    await this._ensureNoStalePostmasterLock();
     return new Promise((resolve, reject) => {
       // Build PostgreSQL arguments
       const pgArgs = [
@@ -817,6 +865,7 @@ export class PostgresManager {
       // the exit is unexpected (external kill, crash, OOM).
       this.process.exited.then((code) => {
         processExited = true;
+        const expected = !!this._stopping;
         if (!started) {
           reject(new Error(`PostgreSQL exited with code ${code} before starting: ${startupOutput}`));
         }
@@ -824,7 +873,7 @@ export class PostgresManager {
         // On unexpected exit (not via stop()), reset cached paths so that
         // getSocketPath() returns null and callers can fall back to TCP
         // or force a fresh start().
-        if (!this._stopping) {
+        if (!expected) {
           this.socketDir = null;
           this.databaseDir = null;
           this.logger?.warn(
@@ -832,6 +881,10 @@ export class PostgresManager {
             'PostgreSQL subprocess exited unexpectedly — socketDir/databaseDir reset'
           );
         }
+        // Notify supervisors. `expected=true` means stop() initiated the exit
+        // (clean shutdown); `expected=false` means the backend died on its
+        // own — supervisors should treat the latter as a fault signal.
+        this.emit('backendExited', { code, expected });
       });
 
       // Method 1: TCP connection polling (preferred, works on Linux/macOS)

package/tests/stale-postmaster-pid.test.js

@@ -0,0 +1,85 @@
+/**
+ * Stale postmaster.pid cleanup
+ *
+ * Verifies that PostgresManager._ensureNoStalePostmasterLock removes
+ * a postmaster.pid file whose recorded PID is no longer alive, and
+ * leaves alone a postmaster.pid whose recorded PID is alive.
+ *
+ * Regression coverage: postgres refuses to start when postmaster.pid
+ * exists, even if the writer crashed. After unclean shutdowns this
+ * required manual `rm` to recover.
+ */
+
+import { PostgresManager } from '../src/postgres.js';
+import { test, expect } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+function makeMgr(dataDir) {
+  const mgr = new PostgresManager({ dataDir });
+  mgr.databaseDir = dataDir;
+  mgr.logger = {
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+  };
+  return mgr;
+}
+
+function makePidFile(dir, contents) {
+  fs.mkdirSync(dir, { recursive: true });
+  const pidFile = path.join(dir, 'postmaster.pid');
+  fs.writeFileSync(pidFile, contents, 'utf-8');
+  return pidFile;
+}
+
+test('removes postmaster.pid when recorded PID is dead', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-stale-'));
+  try {
+    // PID 999999999 will not exist on any sane system
+    const pidFile = makePidFile(dir, '999999999\n/some/data\n123\n');
+    const mgr = makeMgr(dir);
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(pidFile)).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('keeps postmaster.pid when recorded PID is the current (alive) process', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-alive-'));
+  try {
+    const pidFile = makePidFile(dir, `${process.pid}\n/some/data\n123\n`);
+    const mgr = makeMgr(dir);
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(pidFile)).toBe(true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('removes postmaster.pid when first line is unparseable', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-garbage-'));
+  try {
+    const pidFile = makePidFile(dir, 'garbage\nnot-a-pid\n');
+    const mgr = makeMgr(dir);
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(pidFile)).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('no-ops when postmaster.pid does not exist', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-missing-'));
+  try {
+    const mgr = makeMgr(dir);
+    // Should resolve without throwing
+    await mgr._ensureNoStalePostmasterLock();
+    expect(fs.existsSync(path.join(dir, 'postmaster.pid'))).toBe(false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/tests/wrapper-supervision.test.js

@@ -0,0 +1,107 @@
+/**
+ * Wrapper supervision: postgres backend death surfaces to the wrapper
+ *
+ * Verifies that:
+ *  1. PostgresManager extends EventEmitter and emits `backendExited` when
+ *     the postgres child exits.
+ *  2. `expected: true` is reported when the exit was initiated by stop().
+ *  3. `expected: false` is reported when the child was killed externally
+ *     (the case the wrapper needs to react to per pgserve#45).
+ *  4. PgserveDaemon re-emits `backendDiedUnexpectedly` only for unexpected
+ *     exits, not for clean stop().
+ *
+ * Tests use the real Bun.spawn'd postgres binary via PostgresManager because
+ * the supervision contract is end-to-end — a unit test with a mocked process
+ * would prove only that the JS plumbing fires.
+ */
+
+import { PostgresManager } from '../src/postgres.js';
+import { PgserveDaemon } from '../src/daemon.js';
+import { EventEmitter } from 'events';
+import { test, expect } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+function quietLogger() {
+  return {
+    info: () => {}, warn: () => {}, error: () => {}, debug: () => {},
+    child: () => quietLogger(),
+  };
+}
+
+test('PostgresManager extends EventEmitter', () => {
+  const mgr = new PostgresManager({});
+  expect(mgr).toBeInstanceOf(EventEmitter);
+});
+
+test('PostgresManager emits backendExited with expected=true after stop()', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-supv-stop-'));
+  const mgr = new PostgresManager({ dataDir: dir, logger: quietLogger() });
+  let event = null;
+  mgr.on('backendExited', (info) => { event = info; });
+  await mgr.start();
+  await mgr.stop();
+  // Give event loop a tick to flush exited.then handler if not already drained
+  await new Promise((r) => setTimeout(r, 50));
+  expect(event).not.toBeNull();
+  expect(event.expected).toBe(true);
+  fs.rmSync(dir, { recursive: true, force: true });
+}, 60000);
+
+// External-SIGKILL integration coverage runs on Linux only. On macOS,
+// Bun.spawn'd postgres reliably refuses to surface its `exited` promise
+// within the test deadline when killed by SIGKILL — Bun's posix_spawn
+// path on darwin holds parent reaping until grandchildren reap, which
+// postgres never does fast enough for a deterministic test. The
+// `expected=false` branch is still covered cross-platform by the
+// daemon-level re-emit test below, which feeds a synthetic
+// `backendExited` payload through a fake EventEmitter and bypasses the
+// OS signal-handling variability entirely.
+const linuxOnly = process.platform === 'linux' ? test : test.skip;
+linuxOnly('PostgresManager emits backendExited with expected=false on external SIGKILL (linux)', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-supv-kill-'));
+  const mgr = new PostgresManager({ dataDir: dir, logger: quietLogger() });
+  let event = null;
+  mgr.on('backendExited', (info) => { event = info; });
+  await mgr.start();
+  const childPid = mgr.process?.pid;
+  expect(childPid).toBeGreaterThan(0);
+  // External kill — _stopping stays false, so the handler must mark unexpected
+  process.kill(childPid, 'SIGKILL');
+  // Wait for the exit handler to fire (max 3s)
+  for (let i = 0; i < 60 && event === null; i++) {
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  expect(event).not.toBeNull();
+  expect(event.expected).toBe(false);
+  // Cleanup: paths were nulled by the unexpected-exit branch, so stop() is a no-op
+  await mgr.stop().catch(() => {});
+  fs.rmSync(dir, { recursive: true, force: true });
+}, 60000);
+
+test('PgserveDaemon re-emits backendDiedUnexpectedly only on unexpected exit', () => {
+  // Pure plumbing test — synthesize PgserveDaemon and a fake pgManager that
+  // is just an EventEmitter; verify the wiring.
+  const fakePgManager = new EventEmitter();
+  // PgserveDaemon constructor needs a baseDir; passing a tmp dir avoids
+  // touching real config.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pgserve-supv-daemon-'));
+  const daemon = new PgserveDaemon({
+    baseDir: dir,
+    logger: quietLogger(),
+    pgManager: fakePgManager,
+    enforcementDisabled: true,
+  });
+  const events = [];
+  daemon.on('backendDiedUnexpectedly', (info) => events.push(info));
+
+  fakePgManager.emit('backendExited', { code: 0, expected: true });
+  expect(events).toHaveLength(0); // clean stop — no re-emit
+
+  fakePgManager.emit('backendExited', { code: 137, expected: false });
+  expect(events).toHaveLength(1);
+  expect(events[0]).toEqual({ code: 137, expected: false });
+
+  fs.rmSync(dir, { recursive: true, force: true });
+});