pgserve 1.1.2 → 1.1.3-rc.11

package/.github/workflows/build-all-platforms.yml

@@ -38,26 +38,23 @@ concurrency:
 jobs:
   build:
     name: Build ${{ matrix.platform }}
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         include:
-          - target: bun-linux-x64
-            platform: linux-x64
+          # Linux x64
+          - platform: linux-x64
             output: pgserve-linux-x64
-          - target: bun-linux-arm64
-            platform: linux-arm64
-            output: pgserve-linux-arm64
-          - target: bun-darwin-x64
-            platform: darwin-x64
-            output: pgserve-darwin-x64
-          - target: bun-darwin-arm64
-            platform: darwin-arm64
+            os: ubuntu-latest
+          # macOS ARM64 (Apple Silicon)
+          - platform: darwin-arm64
             output: pgserve-darwin-arm64
-          - target: bun-windows-x64
-            platform: windows-x64
+            os: macos-latest
+          # Windows x64 - must build on Windows for --windows-icon
+          - platform: windows-x64
             output: pgserve-windows-x64.exe
+            os: windows-latest
 
     steps:
       - name: Checkout
@@ -73,10 +70,32 @@ jobs:
       - name: Install dependencies
         run: bun install
 
+      # Windows: native build with icon and proper metadata
+      - name: Build for Windows (with branding)
+        if: matrix.platform == 'windows-x64'
+        run: |
+          New-Item -ItemType Directory -Force -Path dist | Out-Null
+          $RAW_VERSION = node -p "require('./package.json').version"
+          # Convert 1.1.3-rc.10 to 1.1.3.10 (Windows requires X.Y.Z.W format)
+          $WIN_VERSION = $RAW_VERSION -replace '-rc\.', '.'
+          Write-Host "Raw version: $RAW_VERSION -> Windows version: $WIN_VERSION"
+          bun build --compile `
+            --windows-icon=assets/icon.ico `
+            --windows-title="pgserve" `
+            --windows-publisher="Namastex Labs" `
+            --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 }}
+          Get-ChildItem dist/
+        shell: pwsh
+
+      # Linux/macOS: native build
       - name: Build for ${{ matrix.platform }}
+        if: matrix.platform != 'windows-x64'
         run: |
           mkdir -p dist
-          bun build --compile --target=${{ matrix.target }} bin/pglite-server.js --outfile dist/${{ matrix.output }}
+          bun build --compile bin/pglite-server.js --outfile dist/${{ matrix.output }}
           ls -lh dist/
 
       - name: Upload artifact
@@ -129,7 +148,8 @@ jobs:
           ls -la dist/
 
           MISSING=""
-          for platform in linux-x64 linux-arm64 darwin-x64 darwin-arm64; do
+          # Supported platforms: linux-x64, darwin-arm64, windows-x64
+          for platform in linux-x64 darwin-arm64; do
             if [ ! -f "dist/pgserve-$platform" ]; then
               MISSING="$MISSING pgserve-$platform"
             fi

package/README.md

@@ -99,6 +99,17 @@ npm install pgserve
 
 > PostgreSQL binaries are automatically downloaded on first run (~100MB).
 
+### Windows
+
+Download `pgserve-windows-x64.exe` from [GitHub Releases](https://github.com/namastexlabs/pgserve/releases).
+
+Double-click to run, or use CLI:
+
+```cmd
+pgserve-windows-x64.exe --port 5432
+pgserve-windows-x64.exe --data C:\pgserve-data
+```
+
 <br>
 
 ## CLI Reference

package/bin/pgserve-wrapper.cjs

@@ -5,9 +5,12 @@
  * This wrapper enables `npx pgserve` to work without requiring
  * users to install bun globally. The bun runtime is bundled as
  * an npm dependency and this wrapper finds and invokes it.
+ *
+ * Windows EBUSY fix: Uses synchronous waiting and taskkill for
+ * reliable process termination and file handle cleanup.
  */
 
-const { spawn } = require('child_process');
+const { spawn, execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
@@ -52,30 +55,120 @@ if (!bunPath) {
 
 const scriptPath = path.join(__dirname, 'pglite-server.js');
 
-// Spawn bun with the actual script, inherit all stdio
-const child = spawn(bunPath, [scriptPath, ...process.argv.slice(2)], {
-  stdio: 'inherit',
-  windowsHide: true
-});
+// Platform-specific spawning strategy:
+// - Windows: Use pipes for explicit handle control (prevents EBUSY errors)
+// - Unix: Use inherit for simplicity (works fine)
 
-child.on('error', (err) => {
-  console.error('Failed to start pgserve:', err.message);
-  process.exit(1);
-});
+if (isWindows) {
+  // WINDOWS PATH: Explicit pipe control to prevent EBUSY errors
+  // Using stdio: 'inherit' causes file handle inheritance that we cannot release,
+  // leading to npm cleanup failures. With pipes, we control when handles are destroyed.
+
+  const child = spawn(bunPath, [scriptPath, ...process.argv.slice(2)], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true
+  });
+
+  // Manually pipe stdio - we now control the handles
+  // Handle stdin errors gracefully (may not be connected in some environments)
+  process.stdin.on('error', () => {});
+  child.stdin.on('error', () => {});
 
-child.on('exit', (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-  } else {
-    process.exit(code ?? 0);
+  // Only pipe stdin if it's readable
+  if (process.stdin.readable) {
+    process.stdin.pipe(child.stdin);
   }
-});
+  child.stdout.pipe(process.stdout);
+  child.stderr.pipe(process.stderr);
+
+  child.on('error', (err) => {
+    console.error('Failed to start pgserve:', err.message);
+    process.exit(1);
+  });
+
+  child.on('close', (code, signal) => {
+    // CRITICAL: Explicitly destroy ALL streams to release file handles
+    // This must happen BEFORE process.exit() to prevent EBUSY
+    try {
+      if (process.stdin.readable) {
+        process.stdin.unpipe(child.stdin);
+      }
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+    } catch {
+      // Ignore stream destruction errors
+    }
+
+    // Remove all listeners to prevent memory leaks
+    child.removeAllListeners();
+
+    // Use setImmediate to ensure stream destruction completes before exit
+    // This gives the event loop one tick to process pending I/O cleanup
+    setImmediate(() => {
+      process.exit(signal ? 1 : (code ?? 0));
+    });
+  });
 
-// Forward signals to child process
-['SIGINT', 'SIGTERM', 'SIGHUP'].forEach(signal => {
-  process.on(signal, () => {
+  // Windows: use taskkill for reliable process termination
+  // process.kill(pid, 'SIGINT') does NOT work properly on Windows
+  process.on('SIGINT', () => {
     if (child.pid) {
-      process.kill(child.pid, signal);
+      try {
+        // /T = terminate child processes (tree), /F = force
+        execSync(`taskkill /PID ${child.pid} /T /F`, {
+          stdio: 'ignore',
+          windowsHide: true
+        });
+      } catch {
+        // Process may have already exited, ignore errors
+      }
     }
   });
-});
+
+  // Handle Ctrl+C via readline for Windows terminal compatibility
+  // Some Windows terminals don't emit SIGINT properly
+  const readline = require('readline');
+  if (process.stdin.isTTY) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+    rl.on('SIGINT', () => {
+      process.emit('SIGINT');
+    });
+    // Clean up readline on close
+    child.on('close', () => {
+      rl.close();
+    });
+  }
+
+} else {
+  // UNIX PATH: Simple stdio inheritance (works fine, no EBUSY issues)
+  const child = spawn(bunPath, [scriptPath, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    windowsHide: true
+  });
+
+  child.on('error', (err) => {
+    console.error('Failed to start pgserve:', err.message);
+    process.exit(1);
+  });
+
+  child.on('close', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+
+  // Unix: forward signals to child process normally
+  ['SIGINT', 'SIGTERM', 'SIGHUP'].forEach(sig => {
+    process.on(sig, () => {
+      if (child.pid) {
+        process.kill(child.pid, sig);
+      }
+    });
+  });
+}

package/bun.lock

@@ -20,7 +20,7 @@
         "@embedded-postgres/darwin-arm64": "17.7.0-beta.15",
         "@embedded-postgres/darwin-x64": "17.7.0-beta.15",
         "@embedded-postgres/linux-x64": "17.7.0-beta.15",
-        "@embedded-postgres/win32-x64": "17.7.0-beta.15",
+        "@embedded-postgres/windows-x64": "17.7.0-beta.15",
       },
     },
   },
@@ -33,6 +33,8 @@
 
     "@embedded-postgres/linux-x64": ["@embedded-postgres/linux-x64@17.7.0-beta.15", "", { "os": "linux", "cpu": "x64" }, "sha512-HeaxSHsw6ccVh8l5iC4OgXqvaaCGWnnZR9CpgNgrAfnKPPGiEhUPBmO2XhEsFQIhc+ad/+36h0NTvKo4bdi40w=="],
 
+    "@embedded-postgres/windows-x64": ["@embedded-postgres/windows-x64@17.7.0-beta.15", "", { "os": "win32", "cpu": "x64" }, "sha512-Oq11yyKxISjefuYdKljcp3Q+uxx237zn9YpP9hO43+6Feorq7USuMIDqk5ofLSQ30FAnVyTqaIQK8ZIjW+tQXQ=="],
+
     "@emnapi/core": ["@emnapi/core@1.7.1", "", { "dependencies": { "@emnapi/wasi-threads": "1.1.0", "tslib": "^2.4.0" } }, "sha512-o1uhUASyo921r2XtHYOHy7gdkGLge8ghBEQHMWmyJFoXlpU58kIrhhN3w26lpQb6dspetweapMn2CSNwQ8I4wg=="],
 
     "@emnapi/runtime": ["@emnapi/runtime@1.7.1", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-PVtJr5CmLwYAU9PZDMITZoR5iAOShYREoR45EyyLrbntV50mdePTgUn4AmOw90Ifcj+x2kRjdzr1HP3RrNiHGA=="],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "1.1.2",
+  "version": "1.1.3-rc.11",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -44,7 +44,7 @@
     "@embedded-postgres/darwin-arm64": "17.7.0-beta.15",
     "@embedded-postgres/darwin-x64": "17.7.0-beta.15",
     "@embedded-postgres/linux-x64": "17.7.0-beta.15",
-    "@embedded-postgres/win32-x64": "17.7.0-beta.15"
+    "@embedded-postgres/windows-x64": "17.7.0-beta.15"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.2.17",

package/src/postgres.js

@@ -13,11 +13,162 @@
  * - No locale dependency (works on any system)
  */
 
+/* global fetch, Bun */
 import os from 'os';
 import path from 'path';
 import fs from 'fs';
 import crypto from 'crypto';
 
+/**
+ * Get platform key for binary lookup (e.g., 'windows-x64', 'linux-x64', 'darwin-arm64')
+ * @returns {string} Platform key
+ */
+function getPlatformKey() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  if (platform === 'win32') return 'windows-x64';
+  if (platform === 'linux' && arch === 'x64') return 'linux-x64';
+  if (platform === 'darwin' && arch === 'arm64') return 'darwin-arm64';
+  if (platform === 'darwin' && arch === 'x64') return 'darwin-x64';
+  if (platform === 'linux' && arch === 'arm64') return 'linux-arm64';
+
+  throw new Error(`Unsupported platform: ${platform}-${arch}`);
+}
+
+/**
+ * Get the directory where extracted binaries are cached
+ * @returns {string} Cache directory path
+ */
+function getBinaryCacheDir() {
+  const platformKey = getPlatformKey();
+  return path.join(os.homedir(), '.pgserve', 'bin', platformKey);
+}
+
+/**
+ * Download and extract PostgreSQL binaries on first run.
+ * Downloads from npm registry (@embedded-postgres packages).
+ *
+ * @returns {Promise<string>} Path to extracted directory
+ */
+async function downloadPostgresBinaries() {
+  const platform = os.platform();
+  const cacheDir = getBinaryCacheDir();
+  const cacheBinDir = path.join(cacheDir, 'bin');
+  const initdbName = platform === 'win32' ? 'initdb.exe' : 'initdb';
+  const postgresName = platform === 'win32' ? 'postgres.exe' : 'postgres';
+
+  // Check if already downloaded
+  if (fs.existsSync(path.join(cacheBinDir, initdbName)) &&
+      fs.existsSync(path.join(cacheBinDir, postgresName))) {
+    return cacheDir;
+  }
+
+  const platformKey = getPlatformKey();
+  const pkgName = `@embedded-postgres/${platformKey}`;
+  const pkgVersion = '17.7.0-beta.15';
+
+  console.log(`[pgserve] PostgreSQL binaries not found.`);
+  console.log(`[pgserve] Downloading ${pkgName}@${pkgVersion}...`);
+
+  // Get tarball URL from npm registry
+  const registryUrl = `https://registry.npmjs.org/${pkgName}`;
+  const registryRes = await fetch(registryUrl);
+  if (!registryRes.ok) {
+    throw new Error(`Failed to fetch package info: ${registryRes.status}`);
+  }
+  const pkgInfo = await registryRes.json();
+  const tarballUrl = pkgInfo.versions[pkgVersion]?.dist?.tarball;
+
+  if (!tarballUrl) {
+    throw new Error(`Version ${pkgVersion} not found for ${pkgName}`);
+  }
+
+  // Download tarball
+  console.log(`[pgserve] Downloading from npm registry...`);
+  const tarballRes = await fetch(tarballUrl);
+  if (!tarballRes.ok) {
+    throw new Error(`Failed to download tarball: ${tarballRes.status}`);
+  }
+
+  const tarballBuffer = await tarballRes.arrayBuffer();
+  const tarballSize = (tarballBuffer.byteLength / 1024 / 1024).toFixed(1);
+  console.log(`[pgserve] Downloaded ${tarballSize} MB`);
+
+  // Create temp file for tarball
+  const tempDir = path.join(os.tmpdir(), `pgserve-download-${Date.now()}`);
+  fs.mkdirSync(tempDir, { recursive: true });
+  const tarballPath = path.join(tempDir, 'package.tgz');
+  fs.writeFileSync(tarballPath, Buffer.from(tarballBuffer));
+
+  // Extract tarball using tar (available on all platforms via bun/node)
+  console.log(`[pgserve] Extracting binaries...`);
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  // Use Bun.spawn for extraction
+  const extractProc = Bun.spawn(['tar', '-xzf', tarballPath, '-C', tempDir], {
+    stdout: 'pipe',
+    stderr: 'pipe'
+  });
+  await extractProc.exited;
+
+  // Copy native/* to cache dir
+  const nativeDir = path.join(tempDir, 'package', 'native');
+  if (!fs.existsSync(nativeDir)) {
+    throw new Error('Extracted package does not contain native/ directory');
+  }
+
+  // Copy files recursively
+  await copyDirRecursive(nativeDir, cacheDir);
+
+  // Make executables executable (Unix only)
+  if (platform !== 'win32') {
+    const binDir = path.join(cacheDir, 'bin');
+    if (fs.existsSync(binDir)) {
+      const files = fs.readdirSync(binDir);
+      for (const file of files) {
+        const filePath = path.join(binDir, file);
+        try {
+          fs.chmodSync(filePath, 0o755);
+        } catch {
+          // Ignore
+        }
+      }
+    }
+  }
+
+  // Cleanup temp
+  try {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  console.log(`[pgserve] PostgreSQL binaries installed to ${cacheDir}`);
+  return cacheDir;
+}
+
+/**
+ * Recursively copy a directory
+ * @param {string} src - Source directory
+ * @param {string} dest - Destination directory
+ */
+async function copyDirRecursive(src, dest) {
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      await copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
 /**
  * Ensure library symlinks exist in the lib directory.
  * The @embedded-postgres package ships versioned libraries but binaries look for soname versions.
@@ -94,10 +245,45 @@ function ensureLibrarySymlinks(libDir, platform) {
 }
 
 // Resolve binary paths from embedded-postgres platform packages
-function getBinaryPaths() {
+// Now async to support bundled binary extraction
+async function getBinaryPaths() {
   const platform = os.platform();
   const arch = os.arch();
+  const exeSuffix = platform === 'win32' ? '.exe' : '';
+
+  // Priority 1: Check extracted cache directory (standalone exe mode)
+  // This is where bundled binaries are extracted on first run
+  const cacheDir = getBinaryCacheDir();
+  const cacheBinDir = path.join(cacheDir, 'bin');
+  const cachedInitdb = path.join(cacheBinDir, 'initdb' + exeSuffix);
+  const cachedPostgres = path.join(cacheBinDir, 'postgres' + exeSuffix);
+
+  if (fs.existsSync(cachedInitdb) && fs.existsSync(cachedPostgres)) {
+    const libDir = path.join(cacheDir, 'lib');
+    if ((platform === 'linux' || platform === 'darwin') && fs.existsSync(libDir)) {
+      ensureLibrarySymlinks(libDir, platform);
+    }
+    return { initdb: cachedInitdb, postgres: cachedPostgres, binDir: cacheBinDir, libDir };
+  }
+
+  // Priority 2: Download binaries if not found (standalone exe mode)
+  // This downloads from npm registry on first run
+  const downloadedDir = await downloadPostgresBinaries();
+  if (downloadedDir) {
+    const downloadedBinDir = path.join(downloadedDir, 'bin');
+    const downloadedInitdb = path.join(downloadedBinDir, 'initdb' + exeSuffix);
+    const downloadedPostgres = path.join(downloadedBinDir, 'postgres' + exeSuffix);
 
+    if (fs.existsSync(downloadedInitdb) && fs.existsSync(downloadedPostgres)) {
+      const libDir = path.join(downloadedDir, 'lib');
+      if ((platform === 'linux' || platform === 'darwin') && fs.existsSync(libDir)) {
+        ensureLibrarySymlinks(libDir, platform);
+      }
+      return { initdb: downloadedInitdb, postgres: downloadedPostgres, binDir: downloadedBinDir, libDir };
+    }
+  }
+
+  // Priority 3: Find the package in node_modules (npm install case)
   let pkgName;
   if (platform === 'linux' && arch === 'x64') {
     pkgName = '@embedded-postgres/linux-x64';
@@ -106,12 +292,11 @@ function getBinaryPaths() {
   } else if (platform === 'darwin' && arch === 'x64') {
     pkgName = '@embedded-postgres/darwin-x64';
   } else if (platform === 'win32' && arch === 'x64') {
-    pkgName = '@embedded-postgres/win32-x64';
+    pkgName = '@embedded-postgres/windows-x64';
   } else {
     throw new Error(`Unsupported platform: ${platform}-${arch}`);
   }
 
-  // Find the package in node_modules (check multiple locations for npx/pnpm/npm compatibility)
   const possiblePaths = [
     path.join(process.cwd(), 'node_modules', pkgName, 'native', 'bin'),
     path.join(import.meta.dirname, '..', 'node_modules', pkgName, 'native', 'bin'),
@@ -120,8 +305,8 @@ function getBinaryPaths() {
   ];
 
   for (const binDir of possiblePaths) {
-    const initdb = path.join(binDir, platform === 'win32' ? 'initdb.exe' : 'initdb');
-    const postgres = path.join(binDir, platform === 'win32' ? 'postgres.exe' : 'postgres');
+    const initdb = path.join(binDir, 'initdb' + exeSuffix);
+    const postgres = path.join(binDir, 'postgres' + exeSuffix);
     if (fs.existsSync(initdb) && fs.existsSync(postgres)) {
       // Resolve the actual binary paths (handles symlinks from package managers)
       const realInitdb = fs.realpathSync(initdb);
@@ -237,8 +422,8 @@ export class PostgresManager {
    * Start the embedded PostgreSQL instance
    */
   async start() {
-    // Get binary paths
-    this.binaries = getBinaryPaths();
+    // Get binary paths (may extract bundled binaries on first run)
+    this.binaries = await getBinaryPaths();
 
     // Make binaries executable
     await fs.promises.chmod(this.binaries.initdb, '755');
@@ -308,6 +493,12 @@ export class PostgresManager {
     // Initialize admin connection pool (for database creation operations)
     await this._initAdminPool();
 
+    // For persistent mode, load existing databases into createdDatabases
+    // This prevents "database already exists" errors when reusing data directories
+    if (this.persistent) {
+      await this._loadExistingDatabases();
+    }
+
     this.logger.info({
       databaseDir: this.databaseDir,
       port: this.port,
@@ -407,6 +598,33 @@ export class PostgresManager {
     }, 'Admin connection pool initialized (Bun.sql)');
   }
 
+  /**
+   * Load existing databases into createdDatabases Set (for persistent mode)
+   * This allows pgserve to reuse existing data directories without
+   * attempting to CREATE DATABASE for databases that already exist.
+   */
+  async _loadExistingDatabases() {
+    try {
+      const result = await this.adminPool`
+        SELECT datname FROM pg_database
+        WHERE datistemplate = false
+        AND datname NOT IN ('postgres', 'template0', 'template1')
+      `;
+
+      for (const row of result) {
+        this.createdDatabases.add(row.datname);
+      }
+
+      this.logger.info({
+        databases: Array.from(this.createdDatabases),
+        count: this.createdDatabases.size
+      }, 'Loaded existing databases from persistent storage');
+    } catch (error) {
+      // Non-fatal - if we can't load existing DBs, createDatabase will handle it
+      this.logger.warn({ error: error.message }, 'Failed to load existing databases');
+    }
+  }
+
   /**
    * Start the PostgreSQL server process
    * Uses Bun.spawn() for ~40% faster process startup
@@ -449,8 +667,24 @@ export class PostgresManager {
 
       let started = false;
       let startupOutput = '';
+      let processExited = false;
+      let portBindingSeen = false;
+      const portStr = this.port.toString();
+
+      // Hybrid startup detection:
+      // 1. TCP connection polling (works on Linux/macOS)
+      // 2. Log-based detection (fallback for Windows where Bun.connect may fail)
+      // Whichever succeeds first wins
+
+      const markReady = (method) => {
+        if (!started) {
+          started = true;
+          this.logger.info({ port: this.port, method }, 'PostgreSQL ready');
+          resolve();
+        }
+      };
 
-      // Read stderr in streaming fashion to detect startup
+      // Read stderr - detect port binding in logs (locale-independent: just look for port number)
       const readStream = async (stream) => {
         const reader = stream.getReader();
         const decoder = new TextDecoder();
@@ -462,11 +696,16 @@ export class PostgresManager {
             startupOutput += message;
             this.logger.debug({ pgOutput: message.trim() }, 'PostgreSQL output');
 
-            // Check for ready message
-            if (!started && (message.includes('database system is ready to accept connections') ||
-                message.includes('ready to accept connections'))) {
-              started = true;
-              resolve();
+            // Detect port binding - look for our port number in log output
+            // This is locale-independent (numbers are universal)
+            if (!portBindingSeen && message.includes(portStr)) {
+              portBindingSeen = true;
+              // Give PostgreSQL 500ms after port binding to finish startup
+              setTimeout(() => {
+                if (!started && !processExited) {
+                  markReady('log-port-binding');
+                }
+              }, 500);
             }
           }
         } catch {
@@ -480,16 +719,91 @@ export class PostgresManager {
 
       // Handle process exit
       this.process.exited.then((code) => {
+        processExited = true;
         if (!started) {
           reject(new Error(`PostgreSQL exited with code ${code} before starting: ${startupOutput}`));
         }
         this.process = null;
       });
 
-      // Timeout after 30 seconds
+      // Method 1: TCP connection polling (preferred, works on Linux/macOS)
+      const tryConnect = () => {
+        return new Promise((resolveConn, rejectConn) => {
+          let resolved = false;
+          const timeout = setTimeout(() => {
+            if (!resolved) {
+              resolved = true;
+              rejectConn(new Error('Connection timeout'));
+            }
+          }, 500);
+
+          Bun.connect({
+            hostname: '127.0.0.1',
+            port: this.port,
+            socket: {
+              open(socket) {
+                if (!resolved) {
+                  resolved = true;
+                  clearTimeout(timeout);
+                  socket.end();
+                  resolveConn(true);
+                }
+              },
+              connectError(_socket, error) {
+                if (!resolved) {
+                  resolved = true;
+                  clearTimeout(timeout);
+                  rejectConn(error);
+                }
+              },
+              error(_socket, error) {
+                if (!resolved) {
+                  resolved = true;
+                  clearTimeout(timeout);
+                  rejectConn(error);
+                }
+              },
+              data() {},
+              close() {},
+            },
+          }).catch((err) => {
+            if (!resolved) {
+              resolved = true;
+              clearTimeout(timeout);
+              rejectConn(err);
+            }
+          });
+        });
+      };
+
+      const pollConnection = async () => {
+        const startTime = Date.now();
+        const timeoutMs = 30000;
+
+        while (Date.now() - startTime < timeoutMs && !started) {
+          if (processExited) return;
+
+          try {
+            await tryConnect();
+            markReady('tcp');
+            return;
+          } catch {
+            await Bun.sleep(200);
+          }
+        }
+      };
+
+      // Start TCP polling (log detection is handled inline above via setTimeout)
+      pollConnection();
+
+      // Overall timeout with helpful error for Windows firewall
       setTimeout(() => {
-        if (!started) {
-          reject(new Error(`PostgreSQL startup timed out after 30s. Output: ${startupOutput}`));
+        if (!started && !processExited) {
+          const isWindows = process.platform === 'win32';
+          const hint = isWindows
+            ? '\n\nOn Windows, this may be caused by Windows Firewall blocking localhost connections.\nTry: netsh advfirewall firewall add rule name="pgserve" dir=in action=allow protocol=TCP localport=' + this.port
+            : '';
+          reject(new Error(`PostgreSQL startup timed out after 30s.${hint}\n\nOutput: ${startupOutput}`));
         }
       }, 30000);
     });
@@ -543,7 +857,11 @@ export class PostgresManager {
     } catch (error) {
       // Database might already exist (from previous persistent session or race condition)
       // 42P04 = duplicate_database, 23505 = unique_violation
-      if (error.code === '42P04' || error.code === '23505') {
+      // Also check error.message for Bun.sql compatibility (may not expose SQLSTATE codes)
+      const isAlreadyExists = error.code === '42P04' ||
+                              error.code === '23505' ||
+                              error.message?.includes('already exists');
+      if (isAlreadyExists) {
         this.createdDatabases.add(dbName);
         this.logger.debug({ dbName }, 'Database already exists');
       } else {