pgserve 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.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/package.json

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

package/src/postgres.js

@@ -709,11 +709,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 = [

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 });
+  }
+});