pgserve 2.1.0 → 2.1.2

package/install.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# ============================================================================
+# pgserve — Canonical PostgreSQL backbone installer
+#
+# Bootstraps a single shared pgserve instance under pm2 supervision. Used as
+# a prerequisite by `omni/install.sh` and `genie/install.sh` so every
+# automagik service on a host points at the same Postgres.
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/namastexlabs/pgserve/main/install.sh | bash
+#
+# With pinned version:
+#   PGSERVE_VERSION=^2.1.1 curl -fsSL .../install.sh | bash
+#
+# Local checkout:
+#   bash install.sh
+#
+# Idempotent — re-running is a no-op success when pgserve is already
+# registered under pm2 with a healthy entry.
+# ============================================================================
+set -euo pipefail
+
+PGSERVE_VERSION="${PGSERVE_VERSION:-^2.1.0}"
+
+# Colors (no-op when stdout isn't a tty)
+if [[ -t 1 ]]; then
+  RED='\033[0;31m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  BLUE='\033[0;34m'
+  CYAN='\033[0;36m'
+  BOLD='\033[1m'
+  NC='\033[0m'
+else
+  RED='' GREEN='' YELLOW='' BLUE='' CYAN='' BOLD='' NC=''
+fi
+
+info() { printf "${BLUE}ℹ${NC}  %s\n" "$*"; }
+ok()   { printf "${GREEN}✓${NC}  %s\n" "$*"; }
+warn() { printf "${YELLOW}⚠${NC}  %s\n" "$*"; }
+fail() { printf "${RED}✗${NC}  %s\n" "$*" >&2; exit 1; }
+step() { printf "\n${BOLD}${CYAN}▸ %s${NC}\n" "$*"; }
+
+has_cmd() { command -v "$1" >/dev/null 2>&1; }
+
+# ============================================================================
+# Prerequisites: bun + pm2
+# ============================================================================
+
+ensure_bun() {
+  if has_cmd bun; then
+    ok "bun $(bun --version 2>/dev/null || echo '?')"
+    return 0
+  fi
+  info "Installing bun (https://bun.sh)..."
+  curl -fsSL https://bun.sh/install | bash >/dev/null 2>&1 || fail "bun install failed — see https://bun.sh"
+  # Make bun available to the rest of this script without requiring a re-login.
+  export PATH="$HOME/.bun/bin:$PATH"
+  has_cmd bun || fail "bun installed but not on PATH — restart your shell and re-run."
+  ok "bun $(bun --version)"
+}
+
+ensure_pm2() {
+  if has_cmd pm2; then
+    ok "pm2 $(pm2 --version 2>/dev/null || echo '?')"
+    return 0
+  fi
+  info "Installing pm2 (process supervisor)..."
+  bun add -g pm2 >/dev/null 2>&1 || fail "pm2 install failed — try: bun add -g pm2"
+  has_cmd pm2 || fail "pm2 installed but not on PATH — restart your shell and re-run."
+  ok "pm2 installed"
+}
+
+# ============================================================================
+# pgserve binary + pm2 registration
+# ============================================================================
+
+ensure_pgserve_binary() {
+  # Probe via `pgserve port` (real subcommand). `pgserve --version` doesn't
+  # exist in 2.1.x — using it would false-negative and trigger a redundant
+  # reinstall every time install.sh runs.
+  if has_cmd pgserve && pgserve port >/dev/null 2>&1; then
+    ok "pgserve binary present (port $(pgserve port 2>/dev/null))"
+    return 0
+  fi
+  info "Installing pgserve@${PGSERVE_VERSION} globally..."
+  bun add -g "pgserve@${PGSERVE_VERSION}" >/dev/null 2>&1 \
+    || fail "pgserve install failed — try: bun add -g pgserve@${PGSERVE_VERSION}"
+  has_cmd pgserve || fail "pgserve installed but not on PATH — restart your shell and re-run."
+  ok "pgserve $(pgserve port 2>/dev/null || echo '?')"
+}
+
+register_pgserve_pm2() {
+  info "Registering pgserve under pm2 (idempotent)..."
+  # `pgserve install` prints its own success/already-installed line and exits
+  # 0 in both cases. We pipe stderr through so any pm2 errors surface to the
+  # operator (the pm2-6.x --min-uptime breakage we hit on 2026-04-30 was
+  # invisible because stderr was being captured).
+  pgserve install || fail "pgserve install failed — see ~/.pgserve/logs/pgserve-error.log"
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+
+main() {
+  step "Installing canonical pgserve"
+  ensure_bun
+  ensure_pm2
+  ensure_pgserve_binary
+  register_pgserve_pm2
+
+  echo ""
+  ok "Canonical pgserve ready"
+  info "URL:  $(pgserve url 2>/dev/null || echo '<run: pgserve url>')"
+  info "Port: $(pgserve port 2>/dev/null || echo '?')"
+  info "Logs: ~/.pgserve/logs/"
+  echo ""
+  info "Other automagik services on this host (omni, genie, ...) will share this pgserve."
+  echo ""
+}
+
+main "$@"

package/package.json

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

package/src/cli-install.cjs

@@ -47,8 +47,13 @@ const DEFAULT_PORT = 8432;
  * Revised defaults:
  *   - 4G memory ceiling — covers realistic load while still bounded so
  *     a runaway query can't eat the host.
- *   - 50 max restarts BUT only counted when min_uptime < 10s ("rapid"
- *     failures). Healthy long-uptime crashes don't count against the cap.
+ *   - 50 max restarts. Earlier drafts paired this with `--min-uptime` to
+ *     only count rapid failures, but pm2 ≥ 6.0 dropped `--min-uptime` from
+ *     the CLI surface (it survives only inside ecosystem files now). We
+ *     keep the budget generous enough that occasional long-uptime crashes
+ *     don't burn through it; if you observe restart-budget exhaustion
+ *     from non-rapid crashes, raise `maxRestarts` rather than reintroducing
+ *     `--min-uptime` (which would break install on pm2 6.x).
  *   - Exponential backoff on repeated failures (100ms → 60s) so we don't
  *     hammer on persistent issues.
  *   - 60s graceful shutdown window — Postgres needs time to flush WAL.
@@ -62,7 +67,6 @@ const DEFAULT_PORT = 8432;
  */
 const HARDENED_DEFAULTS = {
   maxRestarts: 50,
-  minUptimeMs: 10_000,
   restartDelayMs: 4000,
   expBackoffRestartDelayMs: 100,
   // pm2 caps `--exp-backoff-restart-delay` ramp at the current backoff
@@ -149,11 +153,14 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     'none',
     '--max-restarts',
     String(HARDENED_DEFAULTS.maxRestarts),
-    // `--min-uptime` makes `--max-restarts` count only RAPID failures
-    // (process crashed within N ms of starting). Healthy long-uptime
-    // crashes don't burn the budget.
-    '--min-uptime',
-    String(HARDENED_DEFAULTS.minUptimeMs),
+    // NOTE: pm2 ≥ 6.0 dropped `--min-uptime` from the CLI surface — passing
+    // it produces `error: unknown option --min-uptime` and aborts the
+    // install. The flag still works inside an ecosystem file, but per the
+    // canonical-pm2-supervision wish we keep `pgserve install` as a pure
+    // CLI flow (no extra files for operators to manage). The trade-off is
+    // that `--max-restarts` now counts every restart (rapid or not) rather
+    // than only sub-`min_uptime` ones; the budget of 50 above is sized
+    // accordingly.
     '--restart-delay',
     String(HARDENED_DEFAULTS.restartDelayMs),
     // Exponential backoff between successive failures: starts at 100ms,
@@ -172,7 +179,24 @@ function buildPm2StartArgs({ scriptPath, port, dataDir }) {
     '--error',
     logs.error,
     '--',
-    'daemon',
+    // Foreground multi-tenant mode (`pgserve [options]`), NOT daemon mode.
+    //
+    // Daemon mode binds a unix control socket and requires libpq peers to
+    // authenticate via a fingerprint+token handshake (`pgserve daemon
+    // issue-token`). Downstream services that connect with a plain
+    // `postgres://` URL (omni, genie, anything that doesn't speak the
+    // fingerprint protocol) cannot reach a daemon-mode listener. We also
+    // observed live: `pgserve install` was passing `--port` to the daemon
+    // parser, which only accepts `--data | --ram | --log | --no-provision
+    // | --listen | --pgvector` — every install attempt crashed with
+    // `Unknown daemon option: --port` and pm2 burned its restart budget.
+    //
+    // Foreground mode (the default `pgserve [options]` invocation in
+    // postgres-server.js) accepts `--port`, auto-provisions databases on
+    // first connect, runs the cluster on multi-core hosts, and binds TCP
+    // on `127.0.0.1:<port>` with no auth dance — exactly what canonical
+    // pgserve consumers expect. Pass the same flags pgserve already
+    // documents in its own `pgserve --help` output.
     '--port',
     String(port),
     '--data',

package/tests/cli-install.test.js

@@ -124,7 +124,12 @@ describe('pgserve install', () => {
     expect(startCall).toContain('pgserve');
     expect(startCall).toContain('--max-restarts');
     expect(startCall).toContain('50');
-    expect(startCall).toContain('--min-uptime');
+    // pm2 ≥ 6.0 dropped `--min-uptime` from the CLI surface — it now lives
+    // only inside ecosystem files. Passing it on the command line aborts
+    // `pm2 start` with `error: unknown option --min-uptime`. Lock that out:
+    // `pgserve install` must NOT pass `--min-uptime` so it stays compatible
+    // across pm2 5.x → 6.x. See cli-install.cjs:HARDENED_DEFAULTS.
+    expect(startCall).not.toContain('--min-uptime');
     expect(startCall).toContain('--exp-backoff-restart-delay');
     expect(startCall).toContain('--max-memory-restart');
     expect(startCall).toContain('4G');
@@ -132,6 +137,22 @@ describe('pgserve install', () => {
     expect(startCall).toContain('60000');
     expect(startCall).toContain('--interpreter');
     expect(startCall).toContain('none');
+
+    // pgserve install must launch the foreground multi-tenant server, NOT
+    // the daemon. Daemon mode rejects `--port` (it only accepts --data,
+    // --ram, --log, --no-provision, --listen, --pgvector) and its TCP
+    // listeners require fingerprint+token auth which downstream services
+    // (omni, genie) don't speak. Foreground mode binds plain TCP on
+    // 127.0.0.1:<port> with auto-provisioning. Lock that out:
+    expect(startCall).not.toContain('daemon');
+    // The script-arg handover (after `--`) must include `--port` so the
+    // foreground parser binds the right TCP port.
+    const dashDashIdx = startCall.indexOf('--');
+    const scriptArgs = startCall.slice(dashDashIdx + 1);
+    expect(scriptArgs).toContain('--port');
+    expect(scriptArgs).toContain('--data');
+    expect(scriptArgs).toContain('--log');
+    expect(scriptArgs).not.toContain('daemon');
   });
 
   test('second install is idempotent (no second pm2 start)', () => {