pgserve 2.1.1 → 2.1.3

package/bin/postgres-server.js

@@ -132,6 +132,7 @@ function parseDaemonArgs(daemonArgs) {
     autoProvision: true,
     tcpListens: [],
     enablePgvector: false,
+    maxConnections: null,
   };
   for (let i = 0; i < daemonArgs.length; i++) {
     const arg = daemonArgs[i];
@@ -156,6 +157,21 @@ function parseDaemonArgs(daemonArgs) {
       case '--pgvector':
         opts.enablePgvector = true;
         break;
+      case '--max-connections': {
+        // Accept the same flag the foreground/router mode takes so callers
+        // (genie's `getOrStartDaemon`, anything that spawns `pgserve daemon`
+        // with a tuned cap) can override the postmaster's `max_connections`.
+        // The `PgserveDaemon` constructor already honors `options.maxConnections`
+        // (see src/daemon.js — defaults to 1000); we just plumb it through.
+        const raw = daemonArgs[++i];
+        const parsed = Number.parseInt(raw, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+          console.error(`--max-connections: expected a positive integer, got "${raw}"`);
+          process.exit(1);
+        }
+        opts.maxConnections = parsed;
+        break;
+      }
       case '--help':
         console.log(`
 pgserve daemon — singleton control-socket mode
@@ -167,13 +183,14 @@ USAGE:
   pgserve daemon revoke-token <id>
 
 OPTIONS:
-  --data <path>   Persistent data directory (default: in-memory)
-  --ram           Use /dev/shm storage (Linux only)
-  --log <level>   Log level: error|warn|info|debug (default: info)
-  --no-provision  Disable auto-provisioning of databases
-  --listen [host:]port  Bind opt-in TCP listener (repeatable)
-  --pgvector      Auto-enable pgvector extension on new databases
-  --help          Show this help
+  --data <path>          Persistent data directory (default: in-memory)
+  --ram                  Use /dev/shm storage (Linux only)
+  --log <level>          Log level: error|warn|info|debug (default: info)
+  --no-provision         Disable auto-provisioning of databases
+  --listen [host:]port   Bind opt-in TCP listener (repeatable)
+  --pgvector             Auto-enable pgvector extension on new databases
+  --max-connections <n>  Override the postmaster's max_connections (default: 1000)
+  --help                 Show this help
 
 The daemon binds $XDG_RUNTIME_DIR/pgserve/control.sock (fallback /tmp/pgserve/control.sock).
 A second invocation while the first is running exits with "already running".

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.1",
+  "version": "2.1.3",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",

package/src/cli-install.cjs

@@ -179,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

@@ -137,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)', () => {

package/tests/daemon-args.test.js

@@ -0,0 +1,86 @@
+/**
+ * Integration tests for `pgserve daemon` argv parsing.
+ *
+ * `parseDaemonArgs` lives inside `bin/postgres-server.js` (the script
+ * entry point) and isn't exported, so we exercise it via subprocess
+ * invocations of the wrapper. Each test runs in <100ms — they only ask
+ * the daemon to print help or reject an invalid argument; no real
+ * postgres backend is started.
+ *
+ * Background: every recent CLI-flag mismatch between callers and
+ * `pgserve daemon` exited the daemon child with code 1 immediately,
+ * surfacing upstream as the unhelpful "pgserve v2 daemon exited before
+ * binding …" error. These tests pin the daemon's accepted flag set
+ * explicitly so the next mismatch fails CI here, not at runtime.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'bun:test';
+
+const REPO_ROOT = join(fileURLToPath(import.meta.url), '..', '..');
+const PGSERVE_BIN = join(REPO_ROOT, 'bin', 'pgserve-wrapper.cjs');
+
+function runDaemon(args, timeoutMs = 3000) {
+  return spawnSync('node', [PGSERVE_BIN, 'daemon', ...args], {
+    encoding: 'utf-8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+describe('pgserve daemon — argv parser', () => {
+  test('--help lists every flag the daemon accepts', () => {
+    const result = runDaemon(['--help']);
+    expect(result.status).toBe(0);
+    const help = result.stdout;
+    // Every flag the parser accepts must appear in --help so callers
+    // (and the next operator running `pgserve daemon --help`) discover them.
+    expect(help).toContain('--data');
+    expect(help).toContain('--ram');
+    expect(help).toContain('--log');
+    expect(help).toContain('--no-provision');
+    expect(help).toContain('--listen');
+    expect(help).toContain('--pgvector');
+    expect(help).toContain('--max-connections');
+    expect(help).toContain('--help');
+  });
+
+  test('--max-connections accepts a positive integer (no "Unknown option" error)', () => {
+    // Use a bogus --data path so the daemon never actually starts postgres
+    // — the parser runs, accepts --max-connections, then PgserveDaemon
+    // tries to start and fails on the missing/invalid data dir. We only
+    // care that the parser doesn't reject the flag.
+    const result = runDaemon(['--data', '/nonexistent/pgserve-test-dir', '--max-connections', '5000', '--log', 'error']);
+    // The daemon may exit non-zero because the data dir is invalid, but
+    // it MUST NOT exit with "Unknown daemon option" — that's the
+    // pre-fix behavior we're guarding against.
+    const stderr = result.stderr ?? '';
+    expect(stderr).not.toContain('Unknown daemon option: --max-connections');
+  });
+
+  test('--max-connections rejects non-numeric values with a clear error', () => {
+    const result = runDaemon(['--max-connections', 'abc']);
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('--max-connections: expected a positive integer');
+  });
+
+  test('--max-connections rejects zero / negative values', () => {
+    const zero = runDaemon(['--max-connections', '0']);
+    expect(zero.status).toBe(1);
+    expect(zero.stderr).toContain('--max-connections: expected a positive integer');
+
+    const negative = runDaemon(['--max-connections', '-50']);
+    expect(negative.status).toBe(1);
+    expect(negative.stderr).toContain('--max-connections: expected a positive integer');
+  });
+
+  test('unknown flags still exit 1 with the documented "Unknown daemon option" error', () => {
+    // Sanity: the parser hasn't become permissive. Genuinely unknown
+    // flags must still error out so callers learn about the mismatch.
+    const result = runDaemon(['--definitely-not-a-flag']);
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('Unknown daemon option: --definitely-not-a-flag');
+  });
+});