pgserve 1.1.3-rc.6 → 1.1.3

package/.claude/context/windows-debug.md

@@ -0,0 +1,119 @@
+# Windows Debug Context
+
+## RESOLVED (2025-12-12)
+
+The Windows router binding issue has been fixed. See "Solution Applied" below.
+
+---
+
+## Original Issue
+PostgreSQL starts successfully on port 9432, but the router/proxy on port 8432 was NOT listening.
+Clients could not connect because 8432 wasn't bound.
+
+## Root Causes Found
+
+### 1. `reusePort: true` - Linux-only feature (PRIMARY CAUSE)
+**Location:** `src/cluster.js:75`
+
+The cluster mode uses `Bun.listen({ reusePort: true })` which maps to `SO_REUSEPORT`.
+This socket option is Linux-only and **silently fails on Windows**.
+
+### 2. Auto-enabled cluster mode on multi-core Windows systems
+**Location:** `bin/pglite-server.js:106`
+
+Windows systems with multiple CPU cores automatically entered cluster mode,
+triggering the `reusePort` failure.
+
+### 3. TCP port opens before PostgreSQL ready for protocol handshakes
+**Location:** `src/postgres.js:803-821`
+
+PostgreSQL was marked "ready" when TCP port opened, but it wasn't actually
+ready for protocol-level handshakes. Admin pool connection timed out.
+
+---
+
+## Solution Applied
+
+### Fix 1: Disable cluster mode on Windows
+**File:** `bin/pglite-server.js:98-108`
+```javascript
+const isWindows = os.platform() === 'win32';
+cluster: cpuCount > 1 && !isWindows,
+```
+
+### Fix 2: Add platform check to reusePort
+**File:** `src/cluster.js:72-76`
+```javascript
+const isWindows = os.platform() === 'win32';
+this.server = Bun.listen({
+  reusePort: !isWindows,  // SO_REUSEPORT only works on Linux/macOS
+  ...
+});
+```
+
+### Fix 3: Add port binding verification
+**File:** `src/cluster.js:99-102`
+```javascript
+if (!this.server || !this.server.port) {
+  throw new Error(`Failed to bind to port ${this.port} - reusePort may not be supported`);
+}
+```
+
+### Fix 4: Add Windows readiness delay
+**File:** `src/postgres.js:813-817`
+```javascript
+if (isWindows) {
+  await Bun.sleep(2000); // 2 second delay for Windows
+}
+```
+
+### Fix 5: Increase admin pool retry for Windows
+**File:** `src/postgres.js:598-599`
+```javascript
+const maxRetries = isWindows ? 10 : 5;
+const baseDelay = isWindows ? 2000 : 1000;
+```
+
+---
+
+## Verification
+
+After applying fixes, server runs correctly on Windows:
+- Router: `127.0.0.1:7432` ✅
+- PostgreSQL: `127.0.0.1:8432` ✅
+- Database auto-provisioning: ✅
+- Query execution: ✅
+
+```
+Server started successfully!
+
+  Endpoint:    postgresql://127.0.0.1:7432/<database>
+  Mode:        In-memory (ephemeral)
+  PostgreSQL:  Port 8432 (internal)
+  Auto-create: Enabled
+```
+
+---
+
+## Test Commands (Run from Windows)
+```cmd
+# Build binary
+bun build --compile bin/pglite-server.js --outfile dist/pgserve-windows-x64.exe
+
+# Start server
+dist\pgserve-windows-x64.exe
+
+# Check ports are listening (should see BOTH)
+netstat -an | findstr "LISTEN" | findstr "8432 9432"
+
+# Test connection
+psql postgresql://localhost:8432/testdb
+```
+
+---
+
+## Related Files
+- `bin/pglite-server.js` - Entry point, cluster mode decision
+- `src/cluster.js` - Cluster mode with reusePort
+- `src/router.js` - Single-process mode (works on Windows)
+- `src/postgres.js` - PostgreSQL startup and admin pool

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

@@ -45,17 +45,14 @@ jobs:
         include:
           # Linux x64
           - platform: linux-x64
-            pg_pkg: linux-x64
             output: pgserve-linux-x64
             os: ubuntu-latest
-          # macOS ARM64 (Apple Silicon) - must build on macOS for native binaries
+          # macOS ARM64 (Apple Silicon)
           - platform: darwin-arm64
-            pg_pkg: darwin-arm64
             output: pgserve-darwin-arm64
             os: macos-latest
           # Windows x64 - must build on Windows for --windows-icon
           - platform: windows-x64
-            pg_pkg: windows-x64
             output: pgserve-windows-x64.exe
             os: windows-latest
 
@@ -73,33 +70,34 @@ jobs:
       - name: Install dependencies
         run: bun install
 
-      # Bundle PostgreSQL binaries for standalone exe
-      - name: Bundle PostgreSQL binaries
-        run: |
-          echo "Installing @embedded-postgres/${{ matrix.pg_pkg }}..."
-          npm install @embedded-postgres/${{ matrix.pg_pkg }}
-          mkdir -p embedded-postgres
-          cp -r node_modules/@embedded-postgres/${{ matrix.pg_pkg }}/native/* embedded-postgres/
-          echo "Bundled PostgreSQL binaries:"
-          ls -la embedded-postgres/
-          ls -la embedded-postgres/bin/ || true
-        shell: bash
-
-      # Windows: native build with custom icon
-      - name: Build for Windows (with icon)
+      # Windows: native build with icon and proper metadata
+      - name: Build for Windows (with branding)
         if: matrix.platform == 'windows-x64'
         run: |
-          mkdir -p dist
-          bun build --compile --windows-icon=assets/icon.ico bin/pglite-server.js --outfile dist/${{ matrix.output }}
-          ls -lh dist/
-        shell: bash
+          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 `
+            --define BUILD_VERSION="'$RAW_VERSION'" `
+            --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 bin/pglite-server.js --outfile dist/${{ matrix.output }}
+          VERSION=$(node -p "require('./package.json').version")
+          bun build --compile --define BUILD_VERSION="'$VERSION'" bin/pglite-server.js --outfile dist/${{ matrix.output }}
           ls -lh dist/
 
       - name: Upload artifact

package/bin/pglite-server.js

@@ -94,7 +94,9 @@ FEATURES:
  */
 function parseArgs() {
   // Auto-enable cluster mode on multi-core systems for best performance
+  // Note: Cluster mode uses SO_REUSEPORT which is not supported on Windows
   const cpuCount = os.cpus().length;
+  const isWindows = os.platform() === 'win32';
 
   const options = {
     port: 8432,
@@ -103,7 +105,7 @@ function parseArgs() {
     useRam: false, // Use /dev/shm for true RAM storage (Linux only)
     logLevel: 'info',
     autoProvision: true,
-    cluster: cpuCount > 1,  // Auto-enable on multi-core (use --no-cluster to disable)
+    cluster: cpuCount > 1 && !isWindows,  // Auto-enable on multi-core (disabled on Windows - no SO_REUSEPORT)
     workers: null, // null = use CPU count
     syncTo: null,  // Sync target PostgreSQL URL
     syncDatabases: null // Database patterns to sync (comma-separated)

package/eslint.config.js

@@ -24,6 +24,8 @@ export default [
         TextDecoder: 'readonly',
         TextEncoder: 'readonly',
         Response: 'readonly',
+        // Build-time constants (injected via --define)
+        BUILD_VERSION: 'readonly',
       },
     },
     rules: {

package/package.json

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

package/src/cluster.js

@@ -69,10 +69,11 @@ class ClusterRouter extends EventEmitter {
 
     // Create TCP server using Bun.listen() for 2-3x throughput
     const router = this;
+    const isWindows = os.platform() === 'win32';
     this.server = Bun.listen({
       hostname: this.host,
       port: this.port,
-      reusePort: true,  // Enable SO_REUSEPORT for multi-worker port sharing (Linux)
+      reusePort: !isWindows,  // SO_REUSEPORT for multi-worker port sharing (Linux/macOS only)
       socket: {
         data(socket, data) {
           router.handleSocketData(socket, data);
@@ -95,6 +96,11 @@ class ClusterRouter extends EventEmitter {
       }
     });
 
+    // Verify port actually bound (detect silent failures on Windows)
+    if (!this.server || !this.server.port) {
+      throw new Error(`Failed to bind to port ${this.port} - reusePort may not be supported on this platform`);
+    }
+
     this.emit('listening');
   }
 

package/src/dashboard.js

@@ -13,12 +13,18 @@ import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
-// Get package version
+// Get package version - BUILD_VERSION is injected at compile time via --define
+// Falls back to reading package.json for development mode
 let version = '1.0.0';
 try {
-  const __dirname = dirname(fileURLToPath(import.meta.url));
-  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-  version = pkg.version;
+  // Check for build-time injected version first
+  if (typeof BUILD_VERSION !== 'undefined') {
+    version = BUILD_VERSION;
+  } else {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+    version = pkg.version;
+  }
 } catch {
   // Fallback version
 }

package/src/postgres.js

@@ -13,6 +13,7 @@
  * - No locale dependency (works on any system)
  */
 
+/* global fetch, Bun */
 import os from 'os';
 import path from 'path';
 import fs from 'fs';
@@ -45,71 +46,105 @@ function getBinaryCacheDir() {
 }
 
 /**
- * Check if bundled PostgreSQL binaries exist (standalone exe mode)
- * When compiled with `bun build --compile`, the embedded-postgres folder
- * should be bundled alongside the executable.
- * @returns {string|null} Path to bundled binaries or null if not found
- */
-function getBundledBinaryDir() {
-  // Check for embedded-postgres folder relative to the module
-  // This works when binaries are bundled during build
-  const bundledDir = path.join(import.meta.dirname, '..', 'embedded-postgres');
-  if (fs.existsSync(path.join(bundledDir, 'bin'))) {
-    return bundledDir;
-  }
-  return null;
-}
-
-/**
- * Extract bundled PostgreSQL binaries to cache directory.
- * Bun-compiled binaries can read embedded files but cannot execute them directly.
- * We extract to ~/.pgserve/bin/{platform}/ for execution.
+ * Download and extract PostgreSQL binaries on first run.
+ * Downloads from npm registry (@embedded-postgres packages).
  *
- * @returns {Promise<string>} Path to extracted bin directory
+ * @returns {Promise<string>} Path to extracted directory
  */
-async function extractBundledBinaries() {
+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 extracted
+  // Check if already downloaded
   if (fs.existsSync(path.join(cacheBinDir, initdbName)) &&
       fs.existsSync(path.join(cacheBinDir, postgresName))) {
     return cacheDir;
   }
 
-  // Get bundled directory
-  const bundledDir = getBundledBinaryDir();
-  if (!bundledDir) {
-    return null;
+  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}`);
   }
 
-  console.log('[pgserve] Extracting PostgreSQL binaries...');
+  // 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}`);
+  }
 
-  // Create cache directory
+  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 });
 
-  // Copy bundled binaries to cache
-  // Use recursive copy to get bin/, lib/, share/ directories
-  await copyRecursive(bundledDir, cacheDir);
+  // 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');
-    const files = fs.readdirSync(binDir);
-    for (const file of files) {
-      const filePath = path.join(binDir, file);
-      try {
-        fs.chmodSync(filePath, 0o755);
-      } catch {
-        // Ignore permission errors for non-executables
+    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
+        }
       }
     }
   }
 
-  console.log(`[pgserve] Binaries extracted to ${cacheDir}`);
+  // Cleanup temp
+  try {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  console.log(`[pgserve] PostgreSQL binaries installed to ${cacheDir}`);
   return cacheDir;
 }
 
@@ -118,7 +153,7 @@ async function extractBundledBinaries() {
  * @param {string} src - Source directory
  * @param {string} dest - Destination directory
  */
-async function copyRecursive(src, dest) {
+async function copyDirRecursive(src, dest) {
   const entries = fs.readdirSync(src, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -127,11 +162,9 @@ async function copyRecursive(src, dest) {
 
     if (entry.isDirectory()) {
       fs.mkdirSync(destPath, { recursive: true });
-      await copyRecursive(srcPath, destPath);
+      await copyDirRecursive(srcPath, destPath);
     } else {
-      // Read and write file (works with Bun's virtual filesystem)
-      const content = fs.readFileSync(srcPath);
-      fs.writeFileSync(destPath, content);
+      fs.copyFileSync(srcPath, destPath);
     }
   }
 }
@@ -233,22 +266,20 @@ async function getBinaryPaths() {
     return { initdb: cachedInitdb, postgres: cachedPostgres, binDir: cacheBinDir, libDir };
   }
 
-  // Priority 2: Check for bundled binaries and extract if found (standalone exe mode)
-  const bundledDir = getBundledBinaryDir();
-  if (bundledDir) {
-    const extractedDir = await extractBundledBinaries();
-    if (extractedDir) {
-      const extractedBinDir = path.join(extractedDir, 'bin');
-      const extractedInitdb = path.join(extractedBinDir, 'initdb' + exeSuffix);
-      const extractedPostgres = path.join(extractedBinDir, 'postgres' + exeSuffix);
-
-      if (fs.existsSync(extractedInitdb) && fs.existsSync(extractedPostgres)) {
-        const libDir = path.join(extractedDir, 'lib');
-        if ((platform === 'linux' || platform === 'darwin') && fs.existsSync(libDir)) {
-          ensureLibrarySymlinks(libDir, platform);
-        }
-        return { initdb: extractedInitdb, postgres: extractedPostgres, binDir: extractedBinDir, 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 };
     }
   }
 
@@ -544,9 +575,11 @@ export class PostgresManager {
    */
   async _initAdminPool() {
     const { SQL } = await import('bun');
+    const isWindows = process.platform === 'win32';
 
     // Bun.sql config - uses TCP connections (Unix sockets not directly supported)
     // This is fine for admin queries (low volume, local connection)
+    // Windows needs longer timeout due to higher network stack latency
     this.adminPool = new SQL({
       hostname: '127.0.0.1',
       port: this.port,
@@ -555,16 +588,38 @@ export class PostgresManager {
       password: this.password,
       max: 5, // Small pool - only for CREATE DATABASE operations
       idleTimeout: 30,
-      connectionTimeout: 5,
+      connectionTimeout: isWindows ? 15 : 5,
     });
 
-    // Verify connection is working with a simple query
-    await this.adminPool`SELECT 1`;
+    // Verify connection with retry logic
+    // TCP port being open doesn't mean PostgreSQL protocol is ready
+    // This handles the race condition on Windows where the port binds
+    // before the server is fully ready to accept protocol handshakes
+    const maxRetries = isWindows ? 10 : 5;  // More retries on Windows
+    const baseDelay = isWindows ? 2000 : 1000; // Longer delay on Windows
 
-    this.logger.debug({
-      host: '127.0.0.1',
-      maxConnections: 5
-    }, 'Admin connection pool initialized (Bun.sql)');
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        await this.adminPool`SELECT 1`;
+        this.logger.debug({
+          host: '127.0.0.1',
+          maxConnections: 5,
+          attempt
+        }, 'Admin connection pool initialized (Bun.sql)');
+        return; // Success
+      } catch (err) {
+        if (attempt === maxRetries) {
+          throw new Error(`Failed to initialize admin pool after ${maxRetries} attempts: ${err.message}`);
+        }
+        this.logger.debug({
+          attempt,
+          maxRetries,
+          error: err.message
+        }, 'Admin pool connection failed, retrying...');
+        // Exponential backoff: 1s, 2s, 3s, 4s
+        await new Promise(resolve => setTimeout(resolve, baseDelay * attempt));
+      }
+    }
   }
 
   /**
@@ -636,8 +691,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
 
-      // Read stderr in streaming fashion to detect startup
+      const markReady = (method) => {
+        if (!started) {
+          started = true;
+          this.logger.info({ port: this.port, method }, 'PostgreSQL ready');
+          resolve();
+        }
+      };
+
+      // 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();
@@ -649,11 +720,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 {
@@ -667,16 +743,97 @@ 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;
+        const isWindows = process.platform === 'win32';
+
+        while (Date.now() - startTime < timeoutMs && !started) {
+          if (processExited) return;
+
+          try {
+            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;
+          } 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);
     });