pgserve 1.1.3 → 1.1.4

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:
@@ -108,7 +110,9 @@ function parseArgs() {
     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++) {
@@ -163,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();
@@ -211,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
@@ -222,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'}
@@ -244,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;
@@ -258,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'}
@@ -272,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/package.json

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

package/src/cluster.js

@@ -23,6 +23,10 @@ const SSL_REQUEST_CODE = 80877103;
 const GSSAPI_REQUEST_CODE = 80877104;
 const CANCEL_REQUEST_CODE = 80877102;
 
+// Stats collection constants
+const WORKER_STATS_TIMEOUT_MS = 10000; // Worker stats older than this are considered stale
+const WORKER_STATS_REPORT_INTERVAL_MS = 4000; // How often workers report stats to primary
+
 /**
  * ClusterRouter - Lightweight TCP router for worker processes
  * Does NOT start PostgreSQL - connects to PRIMARY's PostgreSQL via Unix socket
@@ -44,6 +48,12 @@ class ClusterRouter extends EventEmitter {
     this.server = null;
     this.connections = new Set();
     this.setMaxListeners(this.maxConnections + 10);
+
+    // Connection stats tracking for IPC reporting
+    this.connectionStats = {
+      totalConnected: 0,
+      totalDisconnected: 0
+    };
   }
 
   /**
@@ -134,6 +144,7 @@ class ClusterRouter extends EventEmitter {
       handshakeComplete: false
     });
     this.connections.add(socket);
+    this.connectionStats.totalConnected++;
   }
 
   /**
@@ -259,6 +270,19 @@ class ClusterRouter extends EventEmitter {
     }
     this.connections.delete(socket);
     this.socketState.delete(socket);
+    this.connectionStats.totalDisconnected++;
+  }
+
+  /**
+   * Get router stats for IPC reporting
+   */
+  getStats() {
+    return {
+      connections: this.connections.size,
+      totalConnected: this.connectionStats.totalConnected,
+      totalDisconnected: this.connectionStats.totalDisconnected,
+      pid: process.pid
+    };
   }
 
   /**
@@ -286,7 +310,7 @@ class ClusterRouter extends EventEmitter {
       try {
         await this.sql.close();
       } catch {
-        // Ignore - connection may already be terminated
+        // Expected: connection may already be terminated during cleanup
       }
     }
 
@@ -297,6 +321,7 @@ class ClusterRouter extends EventEmitter {
   }
 }
 
+
 /**
  * Start pgserve in cluster mode
  */
@@ -307,6 +332,8 @@ export async function startClusterServer(options = {}) {
   const pgPort = options.pgPort || (port + 1000);
 
   if (cluster.isPrimary) {
+    // Port binding happens in workers via Bun.listen with reusePort
+    // If port is in use, first worker will fail with EADDRINUSE
     console.log(`[pgserve] Cluster mode: ${numWorkers} workers`);
 
     // PRIMARY: Start our embedded PostgreSQL (single instance)
@@ -325,6 +352,7 @@ export async function startClusterServer(options = {}) {
     console.log(`[pgserve] Socket: ${pgSocketPath || `TCP port ${pgPort}`}`);
 
     const workers = new Map();
+    const workerStats = new Map(); // Track stats from each worker
 
     // Fork workers with PostgreSQL connection info
     for (let i = 0; i < numWorkers; i++) {
@@ -337,7 +365,8 @@ export async function startClusterServer(options = {}) {
         PGSERVE_PG_USER: 'postgres',
         PGSERVE_PG_PASSWORD: 'postgres',
         PGSERVE_LOG_LEVEL: options.logLevel || 'info',
-        PGSERVE_AUTO_PROVISION: options.autoProvision !== false ? 'true' : 'false'
+        PGSERVE_AUTO_PROVISION: options.autoProvision !== false ? 'true' : 'false',
+        PGSERVE_MAX_CONNECTIONS: String(options.maxConnections || 1000)
       });
       workers.set(worker.id, worker);
     }
@@ -363,18 +392,25 @@ export async function startClusterServer(options = {}) {
         PGSERVE_PG_USER: 'postgres',
         PGSERVE_PG_PASSWORD: 'postgres',
         PGSERVE_LOG_LEVEL: options.logLevel || 'info',
-        PGSERVE_AUTO_PROVISION: options.autoProvision !== false ? 'true' : 'false'
+        PGSERVE_AUTO_PROVISION: options.autoProvision !== false ? 'true' : 'false',
+        PGSERVE_MAX_CONNECTIONS: String(options.maxConnections || 1000)
       });
       workers.set(newWorker.id, newWorker);
     });
 
-    // Wait for workers to be ready
+    // Wait for workers to be ready and handle IPC messages
     let readyCount = 0;
     await new Promise((resolve) => {
       cluster.on('message', (worker, message) => {
         if (message.type === 'ready') {
           readyCount++;
           if (readyCount === numWorkers) resolve();
+        } else if (message.type === 'stats') {
+          // Update worker stats from IPC
+          workerStats.set(worker.id, {
+            ...message.data,
+            lastUpdate: Date.now()
+          });
         }
       });
     });
@@ -403,10 +439,35 @@ export async function startClusterServer(options = {}) {
         await pgManager.stop();
         console.log('[pgserve] Cluster stopped');
       },
-      getStats: () => ({
-        workers: workers.size,
-        pids: Array.from(workers.values()).map(w => w.process.pid)
-      })
+      getStats: () => {
+        // Aggregate stats from all workers
+        let totalConnections = 0;
+        let totalConnected = 0;
+        let totalDisconnected = 0;
+        const activeWorkerStats = {};
+
+        for (const [id, stats] of workerStats) {
+          // Only include recent stats (within timeout window)
+          if (Date.now() - stats.lastUpdate < WORKER_STATS_TIMEOUT_MS) {
+            totalConnections += stats.connections || 0;
+            totalConnected += stats.totalConnected || 0;
+            totalDisconnected += stats.totalDisconnected || 0;
+            activeWorkerStats[id] = stats;
+          }
+        }
+
+        return {
+          workers: workers.size,
+          pids: Array.from(workers.values()).map(w => w.process.pid),
+          connections: {
+            active: totalConnections,
+            totalConnected,
+            totalDisconnected
+          },
+          workerStats: activeWorkerStats
+        };
+      },
+      pgManager
     };
   } else {
     // WORKER: Only run TCP routing, connect to PRIMARY's PostgreSQL
@@ -418,7 +479,8 @@ export async function startClusterServer(options = {}) {
       pgUser: process.env.PGSERVE_PG_USER || 'postgres',
       pgPassword: process.env.PGSERVE_PG_PASSWORD || 'postgres',
       logLevel: process.env.PGSERVE_LOG_LEVEL || 'info',
-      autoProvision: process.env.PGSERVE_AUTO_PROVISION === 'true'
+      autoProvision: process.env.PGSERVE_AUTO_PROVISION === 'true',
+      maxConnections: parseInt(process.env.PGSERVE_MAX_CONNECTIONS) || 1000
     });
 
     await router.start();
@@ -426,9 +488,19 @@ export async function startClusterServer(options = {}) {
     // Tell PRIMARY we're ready
     process.send({ type: 'ready' });
 
+    // Periodically send stats to PRIMARY
+    const statsInterval = setInterval(() => {
+      try {
+        process.send({ type: 'stats', data: router.getStats() });
+      } catch {
+        // Expected: IPC channel may be closed during shutdown
+      }
+    }, WORKER_STATS_REPORT_INTERVAL_MS);
+
     // Handle shutdown
     process.on('message', async (message) => {
       if (message.type === 'shutdown') {
+        clearInterval(statsInterval);
         await router.stop();
         process.exit(0);
       }

package/src/index.js

@@ -11,6 +11,8 @@ export { PostgresManager } from './postgres.js';
 export { SyncManager } from './sync.js';
 export { RestoreManager } from './restore.js';
 export { Dashboard } from './dashboard.js';
+export { StatsCollector } from './stats-collector.js';
+export { StatsDashboard } from './stats-dashboard.js';
 
 // Default export
 export { startMultiTenantServer as default } from './router.js';

package/src/postgres.js

@@ -660,6 +660,7 @@ export class PostgresManager {
         this.binaries.postgres,
         '-D', this.databaseDir,
         '-p', this.port.toString(),
+        '-c', 'max_connections=1000',  // Support high connection counts for stress testing
       ];
 
       // Enable Unix socket for faster local connections (Linux/macOS)