pgserve 1.1.3-rc.7 → 1.1.4

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

@@ -70,21 +70,34 @@ jobs:
       - name: Install dependencies
         run: bun install
 
-      # 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/README.md

@@ -260,46 +260,140 @@ pgserve --sync-to "postgresql://..." --sync-databases "myapp,tenant_*"
 
 ## Performance
 
-### Benchmark Results
+### CRUD Benchmarks
 
 <table>
   <tr>
     <th>Scenario</th>
     <th>SQLite</th>
     <th>PGlite</th>
-    <th>pgserve (Node)</th>
-    <th>pgserve (Bun)</th>
+    <th>PostgreSQL</th>
+    <th>pgserve</th>
     <th>pgserve --ram</th>
   </tr>
   <tr>
     <td><b>Concurrent Writes</b> (10 agents)</td>
-    <td>85 qps</td>
-    <td>211 qps</td>
-    <td>833 qps</td>
-    <td>1,754 qps</td>
-    <td><b>4,000 qps</b> 🏆</td>
+    <td>91 qps</td>
+    <td>204 qps</td>
+    <td>1,667 qps</td>
+    <td>2,273 qps</td>
+    <td><b>4,167 qps</b> 🏆</td>
   </tr>
   <tr>
     <td><b>Mixed Workload</b></td>
-    <td>339 qps</td>
-    <td>505 qps</td>
-    <td>1,017 qps</td>
-    <td>999 qps</td>
-    <td><b>1,986 qps</b> 🏆</td>
+    <td>383 qps</td>
+    <td>484 qps</td>
+    <td>507 qps</td>
+    <td>1,133 qps</td>
+    <td><b>2,109 qps</b> 🏆</td>
   </tr>
   <tr>
     <td><b>Write Lock</b> (50 writers)</td>
-    <td>86 qps</td>
-    <td>168 qps</td>
-    <td>488 qps</td>
-    <td>1,176 qps</td>
+    <td>111 qps</td>
+    <td>228 qps</td>
+    <td>2,857 qps</td>
+    <td>3,030 qps</td>
     <td><b>4,348 qps</b> 🏆</td>
   </tr>
 </table>
 
-> pgserve uses Bun runtime internally for 2x throughput. **RAM mode adds another 2-4x** on Linux.
+### Vector Benchmarks (pgvector)
+
+<table>
+  <tr>
+    <th>Metric</th>
+    <th>PGlite</th>
+    <th>PostgreSQL</th>
+    <th>pgserve</th>
+    <th>pgserve --ram</th>
+  </tr>
+  <tr>
+    <td><b>Vector INSERT</b> (1000 × 1536-dim)</td>
+    <td>152/sec</td>
+    <td>392/sec</td>
+    <td>387/sec</td>
+    <td><b>1,082/sec</b> 🏆</td>
+  </tr>
+  <tr>
+    <td><b>k-NN Search</b> (k=10, 10k corpus)</td>
+    <td>22 qps</td>
+    <td>33 qps</td>
+    <td>31 qps</td>
+    <td>30 qps</td>
+  </tr>
+  <tr>
+    <td><b>Recall@10</b></td>
+    <td>100%</td>
+    <td>100%</td>
+    <td>100%</td>
+    <td>100%</td>
+  </tr>
+</table>
+
+> <b>Why pgserve wins on writes:</b> RAM mode uses <code>/dev/shm</code> (tmpfs), eliminating fsync latency. Vector search is CPU-bound, so RAM mode shows minimal benefit there.
+
+### Final Score
+
+<table>
+  <tr>
+    <th>Engine</th>
+    <th>CRUD QPS</th>
+    <th>Vec QPS</th>
+    <th>Recall</th>
+    <th>P50</th>
+    <th>P99</th>
+    <th>Score</th>
+  </tr>
+  <tr>
+    <td>SQLite</td>
+    <td>195</td>
+    <td>N/A</td>
+    <td>N/A</td>
+    <td>6.3ms</td>
+    <td>17.3ms</td>
+    <td>117</td>
+  </tr>
+  <tr>
+    <td>PGlite</td>
+    <td>305</td>
+    <td>65</td>
+    <td>100%</td>
+    <td>3.3ms</td>
+    <td>7.0ms</td>
+    <td>209</td>
+  </tr>
+  <tr>
+    <td>PostgreSQL</td>
+    <td>1,677</td>
+    <td>152</td>
+    <td>100%</td>
+    <td>6.0ms</td>
+    <td>19.0ms</td>
+    <td>1,067</td>
+  </tr>
+  <tr>
+    <td>pgserve</td>
+    <td>2,145</td>
+    <td>149</td>
+    <td>100%</td>
+    <td>5.3ms</td>
+    <td>13.0ms</td>
+    <td>1,347</td>
+  </tr>
+  <tr>
+    <td><b>pgserve --ram</b></td>
+    <td><b>3,541</b></td>
+    <td><b>381</b></td>
+    <td><b>100%</b></td>
+    <td><b>3.3ms</b></td>
+    <td><b>10.7ms</b></td>
+    <td><b>2,277</b> 🏆</td>
+  </tr>
+</table>
+
+> <b>Methodology:</b> Recall@k measured against brute-force ground truth (industry standard). PostgreSQL baseline is Docker <code>pgvector/pgvector:pg17</code>. RAM mode available on Linux and WSL2.
 >
-> Run benchmarks: `bun run bench` (contributors only)
+> Run benchmarks yourself: <code>bun tests/benchmarks/runner.js --include-vector</code>
 
 <br>
 

package/bin/pglite-server.js

@@ -53,6 +53,8 @@ OPTIONS:
   --no-provision     Disable auto-provisioning of databases
   --sync-to <url>    Sync to real PostgreSQL (async replication)
   --sync-databases   Database patterns to sync (comma-separated, e.g. "myapp,tenant_*")
+  --no-stats         Disable real-time stats dashboard (enabled by default)
+  --max-connections  Max concurrent connections (default: 1000)
   --help             Show this help message
 
 MODES:
@@ -94,7 +96,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,10 +107,12 @@ 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)
+    syncDatabases: null, // Database patterns to sync (comma-separated)
+    showStats: true, // Show real-time stats dashboard (default: enabled)
+    maxConnections: 1000 // Max concurrent connections (high default for multi-tenant)
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -161,6 +167,18 @@ function parseArgs() {
         options.syncDatabases = args[++i];
         break;
 
+      case '--stats':
+        options.showStats = true;
+        break;
+
+      case '--no-stats':
+        options.showStats = false;
+        break;
+
+      case '--max-connections':
+        options.maxConnections = parseInt(args[++i], 10);
+        break;
+
       case '--help':
       case 'help':
         printHelp();
@@ -209,7 +227,8 @@ pgserve - Embedded PostgreSQL Server
         useRam: options.useRam,
         logLevel: options.logLevel,
         autoProvision: options.autoProvision,
-        workers: options.workers
+        workers: options.workers,
+        maxConnections: options.maxConnections
       });
 
       // Only primary process shows full startup message
@@ -220,7 +239,7 @@ pgserve - Embedded PostgreSQL Server
 Cluster started successfully!
 
   Endpoint:    postgresql://${options.host}:${options.port}/<database>
-  Mode:        ${memoryMode ? 'In-memory (ephemeral)' : 'Persistent'} (Cluster)
+  Mode:        ${memoryMode ? (options.useRam ? 'RAM (/dev/shm)' : 'Ephemeral (temp)') : 'Persistent'} (Cluster)
   Workers:     ${stats.workers} processes
   Data:        ${storageType}
   Auto-create: ${options.autoProvision ? 'Enabled' : 'Disabled'}
@@ -242,7 +261,8 @@ Press Ctrl+C to stop
         logLevel: options.logLevel,
         autoProvision: options.autoProvision,
         syncTo: options.syncTo,
-        syncDatabases: options.syncDatabases
+        syncDatabases: options.syncDatabases,
+        maxConnections: options.maxConnections
       });
 
       server = router;
@@ -256,7 +276,7 @@ Press Ctrl+C to stop
 Server started successfully!
 
   Endpoint:    postgresql://${options.host}:${options.port}/<database>
-  Mode:        ${memoryMode ? 'In-memory (ephemeral)' : 'Persistent'}
+  Mode:        ${memoryMode ? (options.useRam ? 'RAM (/dev/shm)' : 'Ephemeral (temp)') : 'Persistent'}
   Data:        ${storageType}
   PostgreSQL:  Port ${router.pgPort} (internal)
   Auto-create: ${options.autoProvision ? 'Enabled' : 'Disabled'}
@@ -270,12 +290,45 @@ Press Ctrl+C to stop
 `);
     }
 
+    // Start stats dashboard if requested (only for primary/single-process)
+    let dashboard = null;
+    if (options.showStats && !process.env.PGSERVE_WORKER) {
+      const { StatsDashboard } = await import('../src/stats-dashboard.js');
+      const { StatsCollector } = await import('../src/stats-collector.js');
+
+      // Create stats collector with appropriate sources
+      const collector = new StatsCollector({
+        router: options.cluster ? null : server,
+        pgManager: server.pgManager,
+        clusterStats: options.cluster ? () => server.getStats() : null,
+        logger: server.logger,
+        port: options.port,
+        host: options.host
+      });
+
+      dashboard = new StatsDashboard({
+        refreshInterval: 2000, // 2 second refresh for real-time feel
+        statsProvider: () => collector.collect()
+      });
+
+      dashboard.start();
+    }
+
     // Graceful shutdown (only for primary/single-process, workers handle via IPC)
     if (!process.env.PGSERVE_WORKER) {
       const shutdown = async () => {
+        // Stop dashboard first to restore cursor
+        if (dashboard) {
+          dashboard.stop();
+        }
         console.log('\nShutting down...');
-        await server.stop();
-        console.log('Server stopped.');
+        try {
+          await server.stop();
+          console.log('Server stopped.');
+        } catch (err) {
+          console.error('Error during shutdown:', err.message);
+          // Still exit - best effort cleanup
+        }
         process.exit(0);
       };
 

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