pgserve 2.0.0 → 2.0.2

package/.github/workflows/ci.yml

@@ -80,7 +80,7 @@ jobs:
       - name: Build executable
         run: |
           mkdir -p dist
-          bun build --compile bin/pglite-server.js --outfile dist/pgserve
+          bun build --compile bin/postgres-server.js --outfile dist/pgserve
 
       - name: Verify executable
         run: |
@@ -119,4 +119,4 @@ jobs:
           npm init -y
           npm install /tmp/pgserve-*.tgz
           timeout 30 npx pgserve --help
-          echo "npx test passed!"
+          echo "npx test passed!"

package/.github/workflows/release.yml

@@ -86,7 +86,7 @@ jobs:
           TAG="${{ steps.bump.outputs.tag }}"
           git add package.json
           git commit -m "[skip ci] release ${TAG}"
-          git tag "${TAG}"
+          git tag -a "${TAG}" -m "release ${TAG}"
           git push origin HEAD --follow-tags
 
   # ---------------------------------------------------------------------------

package/.github/workflows/version.yml

@@ -87,7 +87,7 @@ jobs:
             --windows-description="Embedded PostgreSQL Server - Zero config, auto-provision, unlimited connections" `
             --windows-version="$WIN_VERSION" `
             --windows-copyright="Copyright (c) 2025 Namastex Labs" `
-            bin/pglite-server.js --outfile dist/${{ matrix.output }}
+            bin/postgres-server.js --outfile dist/${{ matrix.output }}
           Get-ChildItem dist/
         shell: pwsh
 
@@ -97,7 +97,7 @@ jobs:
         run: |
           mkdir -p dist
           VERSION=$(node -p "require('./package.json').version")
-          bun build --compile --define BUILD_VERSION="'$VERSION'" bin/pglite-server.js --outfile dist/${{ matrix.output }}
+          bun build --compile --define BUILD_VERSION="'$VERSION'" bin/postgres-server.js --outfile dist/${{ matrix.output }}
           ls -lh dist/
 
       - name: Upload artifact

package/Makefile

@@ -79,13 +79,13 @@ bench: ## Run benchmarks
 .PHONY: test-local
 test-local: ## Test server locally
 	@echo "$(CYAN)🧪 Testing server...$(RESET)"
-	@./bin/pglite-server.js start ./data/test-local --port 12050 --log info &
+	@./bin/postgres-server.js start ./data/test-local --port 12050 --log info &
 	@TESTPID=$$!; \
 	sleep 3; \
-	./bin/pglite-server.js list; \
-	./bin/pglite-server.js health --port 12050; \
+	./bin/postgres-server.js list; \
+	./bin/postgres-server.js health --port 12050; \
 	kill $$TESTPID 2>/dev/null || true; \
-	./bin/pglite-server.js cleanup
+	./bin/postgres-server.js cleanup
 	@echo "$(GREEN)✅ Server test passed!$(RESET)"
 
 # ==========================================
@@ -152,7 +152,7 @@ check-version: ## Check if version tag exists
 
 check-files: ## Check required files exist
 	@echo "$(CYAN)🔍 Checking required files...$(RESET)"
-	@for file in package.json README.md LICENSE src/index.js bin/pglite-server.js; do \
+	@for file in package.json README.md LICENSE src/index.js bin/postgres-server.js; do \
 		if [ ! -f "$$file" ]; then \
 			echo "$(RED)❌ Missing required file: $$file$(RESET)"; \
 			exit 1; \
@@ -172,26 +172,26 @@ $(DIST_DIR):
 
 build: $(DIST_DIR) ## Build standalone executable for current platform
 	@echo "$(CYAN)🔨 Building standalone executable...$(RESET)"
-	@bun build --compile bin/pglite-server.js --outfile $(DIST_DIR)/pgserve
+	@bun build --compile bin/postgres-server.js --outfile $(DIST_DIR)/pgserve
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve$(RESET)"
 
 build-linux: $(DIST_DIR) ## Build for Linux (x64 + arm64)
 	@echo "$(CYAN)🐧 Building for Linux...$(RESET)"
-	@bun build --compile --target=bun-linux-x64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-linux-x64
-	@bun build --compile --target=bun-linux-arm64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-linux-arm64
+	@bun build --compile --target=bun-linux-x64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-linux-x64
+	@bun build --compile --target=bun-linux-arm64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-linux-arm64
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-linux-x64$(RESET)"
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-linux-arm64$(RESET)"
 
 build-macos: $(DIST_DIR) ## Build for macOS (x64 + arm64)
 	@echo "$(CYAN)🍎 Building for macOS...$(RESET)"
-	@bun build --compile --target=bun-darwin-x64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-darwin-x64
-	@bun build --compile --target=bun-darwin-arm64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-darwin-arm64
+	@bun build --compile --target=bun-darwin-x64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-darwin-x64
+	@bun build --compile --target=bun-darwin-arm64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-darwin-arm64
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-darwin-x64$(RESET)"
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-darwin-arm64$(RESET)"
 
 build-windows: $(DIST_DIR) ## Build for Windows (x64)
 	@echo "$(CYAN)🪟 Building for Windows...$(RESET)"
-	@bun build --compile --target=bun-windows-x64 bin/pglite-server.js --outfile $(DIST_DIR)/pgserve-windows-x64.exe
+	@bun build --compile --target=bun-windows-x64 bin/postgres-server.js --outfile $(DIST_DIR)/pgserve-windows-x64.exe
 	@echo "$(GREEN)✅ Built: $(DIST_DIR)/pgserve-windows-x64.exe$(RESET)"
 
 build-all: build-linux build-macos build-windows ## Build for all platforms
@@ -254,7 +254,7 @@ publish: ## ⚠️ [DEPRECATED] Releases run from CI on push to main
 clean: ## Clean generated files
 	@echo "$(CYAN)🧹 Cleaning...$(RESET)"
 	@rm -rf data/test-* data/genieos-local
-	@./bin/pglite-server.js cleanup
+	@./bin/postgres-server.js cleanup
 	@echo "$(GREEN)✅ Cleaned!$(RESET)"
 
 clean-all: clean ## Deep clean (including node_modules)

package/README.md

@@ -355,6 +355,27 @@ ss -tlnp | grep pgserve   # no rows expected
 
 ## API
 
+Daemon-first apps can let the first caller install/start the singleton and
+then connect through the Unix socket. The daemon derives the app identity
+from kernel peer credentials and routes it to that app's signed fingerprint
+database.
+
+```javascript
+import { daemonClientOptions, ensureDaemon } from 'pgserve';
+import postgres from 'postgres';
+
+await ensureDaemon({
+  dataDir: `${process.env.HOME}/.pgserve/data`,
+  logLevel: 'warn',
+});
+
+const sql = postgres(daemonClientOptions());
+await sql`SELECT current_database()`;
+```
+
+The classic TCP router API remains available for explicit v1-compatible
+embedded servers:
+
 ```javascript
 import { startMultiTenantServer } from 'pgserve';
 
@@ -510,10 +531,10 @@ CREATE EXTENSION IF NOT EXISTS vector;
   <tr>
     <th>Scenario</th>
     <th>SQLite</th>
-    <th>PGlite</th>
     <th>PostgreSQL</th>
-    <th>pgserve</th>
-    <th>pgserve --ram</th>
+    <th>pgserve 1.2.0</th>
+    <th>pgserve v2</th>
+    <th>pgserve v2 --ram</th>
   </tr>
   <tr>
     <td><b>Concurrent Writes</b> (10 agents)</td>
@@ -546,10 +567,10 @@ CREATE EXTENSION IF NOT EXISTS vector;
 <table>
   <tr>
     <th>Metric</th>
-    <th>PGlite</th>
     <th>PostgreSQL</th>
-    <th>pgserve</th>
-    <th>pgserve --ram</th>
+    <th>pgserve 1.2.0</th>
+    <th>pgserve v2</th>
+    <th>pgserve v2 --ram</th>
   </tr>
   <tr>
     <td><b>Vector INSERT</b> (1000 × 1536-dim)</td>
@@ -598,7 +619,7 @@ CREATE EXTENSION IF NOT EXISTS vector;
     <td>117</td>
   </tr>
   <tr>
-    <td>PGlite</td>
+    <td>pgserve 1.2.0</td>
     <td>305</td>
     <td>65</td>
     <td>100%</td>
@@ -616,7 +637,7 @@ CREATE EXTENSION IF NOT EXISTS vector;
     <td>1,067</td>
   </tr>
   <tr>
-    <td>pgserve</td>
+    <td>pgserve v2</td>
     <td>2,145</td>
     <td>149</td>
     <td>100%</td>
@@ -625,7 +646,7 @@ CREATE EXTENSION IF NOT EXISTS vector;
     <td>1,347</td>
   </tr>
   <tr>
-    <td><b>pgserve --ram</b></td>
+    <td><b>pgserve v2 --ram</b></td>
     <td><b>3,541</b></td>
     <td><b>381</b></td>
     <td><b>100%</b></td>

package/bin/pgserve-wrapper.cjs

@@ -61,19 +61,19 @@ if (!bunPath) {
 // then exits instantly with:
 //   Error: Bun's postinstall script was not run.
 //
-// pglite-server.js's TCP readiness poll can't distinguish this from a slow
+// postgres-server.js's TCP readiness poll can't distinguish this from a slow
 // startup, so users see a confusing 30s timeout. Detect the specific error
 // here, attempt the documented self-heal once (`node install.js`), and retry.
 // If self-heal also fails, surface the real error instead of hanging later.
 ensureBunHealthy(bunPath);
 
-const scriptPath = path.join(__dirname, 'pglite-server.js');
+const scriptPath = path.join(__dirname, 'postgres-server.js');
 
 /**
  * Verify the selected bun binary can execute. If it fails with the known
  * "postinstall script was not run" signature, attempt a one-shot repair via
  * the bun npm package's install.js. Throws (with a useful message) rather
- * than letting pglite-server.js hang on the TCP readiness poll for 30s.
+ * than letting postgres-server.js hang on the TCP readiness poll for 30s.
  */
 function ensureBunHealthy(bunExe) {
   const probe = probeBun(bunExe);

package/bin/{pglite-server.js → postgres-server.js}

@@ -117,6 +117,7 @@ function parseDaemonArgs(daemonArgs) {
     logLevel: 'info',
     autoProvision: true,
     tcpListens: [],
+    enablePgvector: false,
   };
   for (let i = 0; i < daemonArgs.length; i++) {
     const arg = daemonArgs[i];
@@ -138,6 +139,9 @@ function parseDaemonArgs(daemonArgs) {
       case '--listen':
         opts.tcpListens.push(daemonArgs[++i]);
         break;
+      case '--pgvector':
+        opts.enablePgvector = true;
+        break;
       case '--help':
         console.log(`
 pgserve daemon — singleton control-socket mode
@@ -154,6 +158,7 @@ OPTIONS:
   --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
 
 The daemon binds $XDG_RUNTIME_DIR/pgserve/control.sock (fallback /tmp/pgserve/control.sock).

package/bun.lock

@@ -8,7 +8,6 @@
         "bun": "^1.3.4",
       },
       "devDependencies": {
-        "@electric-sql/pglite": "^0.2.17",
         "eslint": "^9.39.1",
         "eslint-plugin-unused-imports": "^4.3.0",
         "husky": "^9.1.7",
@@ -25,8 +24,6 @@
     },
   },
   "packages": {
-    "@electric-sql/pglite": ["@electric-sql/pglite@0.2.17", "", {}, "sha512-qEpKRT2oUaWDH6tjRxLHjdzMqRUGYDnGZlKrnL4dJ77JVMcP2Hpo3NYnOSPKdZdeec57B6QPprCUFg0picx5Pw=="],
-
     "@embedded-postgres/darwin-arm64": ["@embedded-postgres/darwin-arm64@18.2.0-beta.16", "", { "os": "darwin", "cpu": "arm64" }, "sha512-wnswaF+uDvGeitqajJ8v8xOG4ttFrzixElwKNe2MIxBXSLWPV3xhi6tBY0Sjw8Lmiu6UG9vNLFZSjHPrIeokBg=="],
 
     "@embedded-postgres/darwin-x64": ["@embedded-postgres/darwin-x64@18.2.0-beta.16", "", { "os": "darwin", "cpu": "x64" }, "sha512-u9WtTPxRuO0uOny5IniXHSDaLmtOujwzDoExIV/jFT0Fu8SzpX7wdoPbsSPBLgyQWdr/nPA77K9QI4r6P1/fKA=="],

package/ecosystem.config.cjs

@@ -2,7 +2,7 @@ module.exports = {
   apps: [
     {
       name: 'pgserve',
-      script: './bin/pglite-server.js',
+      script: './bin/postgres-server.js',
       args: 'router --port 8432',
       cwd: '/home/namastex/dev/pgserve',
       interpreter: 'node',
@@ -13,8 +13,8 @@ module.exports = {
       env: {
         NODE_ENV: 'production'
       },
-      error_file: '/home/namastex/logs/pglite-server-error.log',
-      out_file: '/home/namastex/logs/pglite-server-out.log',
+      error_file: '/home/namastex/logs/postgres-server-error.log',
+      out_file: '/home/namastex/logs/postgres-server-out.log',
       log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
       merge_logs: true,
       time: true

package/knip.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "entry": ["src/index.js", "bin/pglite-server.js", "bin/pgserve-wrapper.cjs"],
+  "entry": ["src/index.js", "bin/postgres-server.js", "bin/pgserve-wrapper.cjs"],
   "project": ["src/**/*.js", "bin/**/*.js", "bin/**/*.cjs"],
   "ignore": ["tests/**", "helpers/**", "scripts/**"],
   "ignoreBinaries": ["scripts/test-npx.sh", "scripts/test-bun-self-heal.sh", "make"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -11,9 +11,9 @@
     "bench": "bun tests/benchmarks/runner.js",
     "test": "bun test tests/**/*.test.js",
     "test:watch": "bun test --watch tests/**/*.test.js",
-    "dev": "bun --watch bin/pglite-server.js",
-    "start": "bun bin/pglite-server.js",
-    "build": "bun build --compile bin/pglite-server.js --outfile dist/pgserve",
+    "dev": "bun --watch bin/postgres-server.js",
+    "start": "bun bin/postgres-server.js",
+    "build": "bun build --compile bin/postgres-server.js --outfile dist/pgserve",
     "build:all": "make build-all",
     "lint": "eslint src/ bin/",
     "lint:fix": "eslint src/ bin/ --fix",
@@ -48,7 +48,6 @@
     "@embedded-postgres/windows-x64": "18.2.0-beta.16"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "^0.2.17",
     "eslint": "^9.39.1",
     "eslint-plugin-unused-imports": "^4.3.0",
     "husky": "^9.1.7",

package/scripts/test-bun-self-heal.sh

@@ -7,7 +7,7 @@
 # pgserve-wrapper.cjs must detect this and self-heal via `node install.js`.
 #
 # This test stages a synthetic broken install tree, runs the wrapper, and
-# asserts that it recovers and spawns pglite-server.
+# asserts that it recovers and spawns postgres-server.
 
 set -e
 
@@ -37,10 +37,10 @@ mkdir -p "$FIXTURE/node_modules/pgserve/bin"
 
 cp "$WRAPPER" "$FIXTURE/node_modules/pgserve/bin/pgserve-wrapper.cjs"
 
-# Stub pglite-server so we can detect a successful spawn without needing
+# Stub postgres-server so we can detect a successful spawn without needing
 # postgres binaries in the fixture.
-cat > "$FIXTURE/node_modules/pgserve/bin/pglite-server.js" <<'EOF'
-console.log("pglite-server-spawned");
+cat > "$FIXTURE/node_modules/pgserve/bin/postgres-server.js" <<'EOF'
+console.log("postgres-server-spawned");
 process.exit(0);
 EOF
 
@@ -97,13 +97,13 @@ if ! echo "$OUTPUT" | grep -q "bun runtime recovered"; then
   exit 1
 fi
 
-if ! echo "$OUTPUT" | grep -q "pglite-server-spawned"; then
-  echo "✗ pglite-server was not spawned after self-heal"
+if ! echo "$OUTPUT" | grep -q "postgres-server-spawned"; then
+  echo "✗ postgres-server was not spawned after self-heal"
   echo "$OUTPUT"
   exit 1
 fi
 
-echo "✓ self-heal path: wrapper detected, repaired, and spawned pglite-server"
+echo "✓ self-heal path: wrapper detected, repaired, and spawned postgres-server"
 
 echo ""
 echo "=== Testing healthy path is unaffected ==="
@@ -122,13 +122,13 @@ if echo "$OUTPUT" | grep -q "self-heal\|recovered"; then
   exit 1
 fi
 
-if ! echo "$OUTPUT" | grep -q "pglite-server-spawned"; then
-  echo "✗ pglite-server was not spawned on healthy path"
+if ! echo "$OUTPUT" | grep -q "postgres-server-spawned"; then
+  echo "✗ postgres-server was not spawned on healthy path"
   echo "$OUTPUT"
   exit 1
 fi
 
-echo "✓ healthy path: wrapper was silent and spawned pglite-server directly"
+echo "✓ healthy path: wrapper was silent and spawned postgres-server directly"
 
 echo ""
 echo "=== Testing non-postinstall errors surface raw ==="

package/src/daemon.js

@@ -251,7 +251,7 @@ export class PgserveDaemon extends EventEmitter {
 
     this.pgManager = options.pgManager || new PostgresManager({
       dataDir: this.baseDir,
-      port: options.pgPort || 5433,
+      port: options.pgPort ?? 0,
       logger: this.logger.child ? this.logger.child({ component: 'postgres' }) : this.logger,
       useRam: this.useRam,
       enablePgvector: options.enablePgvector || false,

package/src/fingerprint.js

@@ -6,7 +6,7 @@
  *
  *   1. SO_PEERCRED (Linux) / getpeereid + LOCAL_PEERPID (macOS)
  *      → kernel-attested {pid, uid, gid}
- *   2. /proc/$pid/cwd  → peer's current working directory (Linux only)
+ *   2. peer cwd lookup → /proc/$pid/cwd on Linux, lsof on macOS
  *   3. walk upward to the nearest package.json
  *   4. if found:  fingerprint = sha256(realpath \0 name \0 uid)[:12]   mode='package'
  *      else:      fingerprint = sha256(uid \0 cwd \0 cmdline[1])[:12]  mode='script'
@@ -29,6 +29,7 @@
  */
 
 import crypto from 'crypto';
+import { execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import { audit, AUDIT_EVENTS } from './audit.js';
@@ -175,17 +176,21 @@ function makeDarwinReader(symbols, ptr) {
 }
 
 // ---------------------------------------------------------------------------
-// /proc reads — Linux-only; macOS daemon support is best-effort
+// Peer process metadata reads
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the cwd of a peer process via /proc/$pid/cwd. Linux-only.
- * Returns null if the symlink cannot be read (process gone, EACCES, etc).
+ * Resolve the cwd of a peer process. Linux uses /proc/$pid/cwd; macOS has no
+ * /proc, so it shells out to the platform lsof binary and parses the cwd row.
+ * Returns null if the process disappeared, permissions deny the lookup, or the
+ * host does not expose a cwd for the peer.
  *
  * @param {number} pid
  * @returns {string | null}
  */
 export function readProcCwd(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  if (process.platform === 'darwin') return readDarwinCwd(pid);
   if (process.platform !== 'linux') return null;
   try {
     return fs.readlinkSync(`/proc/${pid}/cwd`);
@@ -194,6 +199,27 @@ export function readProcCwd(pid) {
   }
 }
 
+function readDarwinCwd(pid) {
+  const lsof = process.env.PGSERVE_LSOF_BIN || '/usr/sbin/lsof';
+  try {
+    const output = execFileSync(lsof, ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+      encoding: 'utf8',
+      timeout: 1000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return parseDarwinLsofCwd(output);
+  } catch {
+    return null;
+  }
+}
+
+export function parseDarwinLsofCwd(output) {
+  for (const line of String(output || '').split(/\r?\n/)) {
+    if (line.startsWith('n') && line.length > 1) return line.slice(1);
+  }
+  return null;
+}
+
 /**
  * Read the peer's argv via /proc/$pid/cmdline (NUL-separated).
  * argv[0] is the exe; argv[1] is typically the script.

package/src/index.js

@@ -24,6 +24,26 @@ export {
   acquirePidLock,
   isProcessAlive,
 } from './daemon.js';
+export {
+  buildDaemonArgs,
+  daemonClientOptions,
+  ensureDaemon,
+  probeDaemon,
+  resolveBundledCliBin,
+} from './sdk.js';
+export {
+  derivePackageFingerprint,
+  deriveScriptFingerprint,
+  fingerprintFromCred,
+  findNearestPackageJson,
+  readPackageName,
+  readPersistFlag,
+} from './fingerprint.js';
+export {
+  hashToken,
+  mintToken,
+  parseTcpAuth,
+} from './tokens.js';
 
 // Default export
 export { startMultiTenantServer as default } from './router.js';

package/src/postgres.js

@@ -406,10 +406,23 @@ export function pgvectorMetaMatches(meta, runtime) {
   return true;
 }
 
+function findAvailableTcpPort() {
+  const server = Bun.listen({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: {
+      data() {},
+    },
+  });
+  const port = server.port;
+  server.stop(true);
+  return port;
+}
+
 export class PostgresManager {
   constructor(options = {}) {
     this.dataDir = options.dataDir || null; // null = memory mode (temp dir)
-    this.port = options.port || 5433; // Internal PG port (router listens on different port)
+    this.port = options.port ?? 5433; // Internal PG port (router listens on different port)
     this.user = options.user || 'postgres';
     this.password = options.password || 'postgres';
     this.logger = options.logger;
@@ -465,6 +478,10 @@ export class PostgresManager {
     await fs.promises.chmod(this.binaries.initdb, '755');
     await fs.promises.chmod(this.binaries.postgres, '755');
 
+    if (this.port === 0) {
+      this.port = findAvailableTcpPort();
+    }
+
     // Determine data directory
     if (this.persistent) {
       this.databaseDir = this.dataDir;
@@ -568,7 +585,8 @@ export class PostgresManager {
       const initdbCmd = [
         this.binaries.initdb,
         `--pgdata=${this.databaseDir}`,
-        '--auth=password',
+        '--auth-local=trust',
+        '--auth-host=password',
         `--username=${this.user}`,
         `--pwfile=${passwordFile}`,
       ];
@@ -744,11 +762,13 @@ export class PostgresManager {
       // Whichever succeeds first wins
 
       const markReady = (method) => {
-        if (!started) {
-          started = true;
-          this.logger.info({ port: this.port, method }, 'PostgreSQL ready');
-          resolve();
-        }
+        if (started || processExited) return true;
+        const socketPath = this.getSocketPath();
+        if (socketPath && !fs.existsSync(socketPath)) return false;
+        started = true;
+        this.logger.info({ port: this.port, method }, 'PostgreSQL ready');
+        resolve();
+        return true;
       };
 
       // Read stderr - detect port binding in logs (locale-independent: just look for port number)
@@ -873,14 +893,19 @@ export class PostgresManager {
           if (processExited) return;
 
           try {
+            const socketPath = this.getSocketPath();
+            if (socketPath && fs.existsSync(socketPath)) {
+              markReady('unix-socket');
+              return;
+            }
             await tryConnect();
             // On Windows, TCP port opens before PostgreSQL is fully ready for protocol handshakes
             // Add delay to let PostgreSQL complete its startup sequence
             if (isWindows) {
               await Bun.sleep(2000); // 2 second delay for Windows
             }
-            markReady('tcp');
-            return;
+            if (processExited) return;
+            if (markReady('tcp')) return;
           } catch {
             await Bun.sleep(200);
           }