pgserve 0.1.4 → 1.0.1

package/tests/sync-perf-test.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Sync Performance Impact Test
+ *
+ * Verifies that enabling sync has ZERO impact on hot path performance.
+ * Runs identical workloads with and without sync, compares results.
+ */
+
+import { startMultiTenantServer } from '../src/index.js';
+import pg from 'pg';
+
+const ITERATIONS = 1000;
+const WARMUP = 100;
+
+async function runWorkload(port, label) {
+  const client = new pg.Client({
+    host: 'localhost',
+    port,
+    database: 'perftest',
+    user: 'postgres',
+    password: 'postgres'
+  });
+
+  await client.connect();
+
+  // Create table
+  await client.query('CREATE TABLE IF NOT EXISTS bench (id SERIAL PRIMARY KEY, data TEXT)');
+  await client.query('TRUNCATE bench');
+
+  // Warmup
+  for (let i = 0; i < WARMUP; i++) {
+    await client.query('INSERT INTO bench (data) VALUES ($1)', [`warmup-${i}`]);
+  }
+  await client.query('TRUNCATE bench');
+
+  // Benchmark
+  const start = process.hrtime.bigint();
+
+  for (let i = 0; i < ITERATIONS; i++) {
+    await client.query('INSERT INTO bench (data) VALUES ($1)', [`row-${i}`]);
+  }
+
+  const insertEnd = process.hrtime.bigint();
+  const insertMs = Number(insertEnd - start) / 1_000_000;
+
+  // Read benchmark
+  const readStart = process.hrtime.bigint();
+  for (let i = 0; i < ITERATIONS; i++) {
+    await client.query('SELECT * FROM bench WHERE id = $1', [i % ITERATIONS + 1]);
+  }
+  const readEnd = process.hrtime.bigint();
+  const readMs = Number(readEnd - readStart) / 1_000_000;
+
+  await client.end();
+
+  return {
+    label,
+    inserts: {
+      total: insertMs,
+      perOp: insertMs / ITERATIONS,
+      opsPerSec: Math.round(ITERATIONS / (insertMs / 1000))
+    },
+    reads: {
+      total: readMs,
+      perOp: readMs / ITERATIONS,
+      opsPerSec: Math.round(ITERATIONS / (readMs / 1000))
+    }
+  };
+}
+
+async function main() {
+  console.log('='.repeat(60));
+  console.log('SYNC PERFORMANCE IMPACT TEST');
+  console.log('='.repeat(60));
+  console.log(`Iterations: ${ITERATIONS} | Warmup: ${WARMUP}`);
+  console.log();
+
+  // Test 1: Without sync
+  console.log('[1/2] Starting pgserve WITHOUT sync...');
+  const serverNoSync = await startMultiTenantServer({
+    port: 18001,
+    logLevel: 'error'
+  });
+
+  await new Promise(r => setTimeout(r, 2000)); // Wait for server
+  const resultNoSync = await runWorkload(18001, 'NO SYNC');
+  await serverNoSync.stop();
+
+  console.log('      Done.');
+  console.log();
+
+  // Test 2: With sync enabled (failing target - simulates sync overhead)
+  console.log('[2/2] Starting pgserve WITH sync (failing target)...');
+  const serverWithSync = await startMultiTenantServer({
+    port: 18002,
+    logLevel: 'error',
+    syncTo: 'postgresql://dummy:dummy@localhost:59999/fake', // Intentionally failing
+    syncDatabases: 'perftest'
+  });
+
+  await new Promise(r => setTimeout(r, 2000)); // Wait for server
+  const resultWithSync = await runWorkload(18002, 'WITH SYNC');
+  await serverWithSync.stop();
+
+  console.log('      Done.');
+  console.log();
+
+  // Results
+  console.log('='.repeat(60));
+  console.log('RESULTS');
+  console.log('='.repeat(60));
+  console.log();
+
+  console.log('INSERT PERFORMANCE:');
+  console.log(`  Without Sync: ${resultNoSync.inserts.opsPerSec.toLocaleString()} ops/sec (${resultNoSync.inserts.perOp.toFixed(2)} ms/op)`);
+  console.log(`  With Sync:    ${resultWithSync.inserts.opsPerSec.toLocaleString()} ops/sec (${resultWithSync.inserts.perOp.toFixed(2)} ms/op)`);
+
+  const insertDiff = ((resultWithSync.inserts.opsPerSec - resultNoSync.inserts.opsPerSec) / resultNoSync.inserts.opsPerSec * 100).toFixed(2);
+  console.log(`  Difference:   ${insertDiff > 0 ? '+' : ''}${insertDiff}%`);
+  console.log();
+
+  console.log('READ PERFORMANCE:');
+  console.log(`  Without Sync: ${resultNoSync.reads.opsPerSec.toLocaleString()} ops/sec (${resultNoSync.reads.perOp.toFixed(2)} ms/op)`);
+  console.log(`  With Sync:    ${resultWithSync.reads.opsPerSec.toLocaleString()} ops/sec (${resultWithSync.reads.perOp.toFixed(2)} ms/op)`);
+
+  const readDiff = ((resultWithSync.reads.opsPerSec - resultNoSync.reads.opsPerSec) / resultNoSync.reads.opsPerSec * 100).toFixed(2);
+  console.log(`  Difference:   ${readDiff > 0 ? '+' : ''}${readDiff}%`);
+  console.log();
+
+  // Verdict
+  console.log('='.repeat(60));
+  const threshold = 5; // 5% tolerance
+  const insertPass = Math.abs(parseFloat(insertDiff)) < threshold;
+  const readPass = Math.abs(parseFloat(readDiff)) < threshold;
+
+  if (insertPass && readPass) {
+    console.log('VERDICT: ✅ PASS - ZERO PERFORMANCE IMPACT');
+    console.log(`         (within ${threshold}% tolerance)`);
+  } else {
+    console.log('VERDICT: ❌ FAIL - PERFORMANCE REGRESSION DETECTED');
+  }
+  console.log('='.repeat(60));
+
+  process.exit(insertPass && readPass ? 0 : 1);
+}
+
+main().catch(e => {
+  console.error('Test failed:', e);
+  process.exit(1);
+});

package/src/detector.js

@@ -1,105 +0,0 @@
-import net from 'net';
-
-/**
- * Check if PostgreSQL connection URL is valid and reachable
- */
-export async function canConnectToPostgres(connectionUrl, timeout = 5000) {
-  if (!connectionUrl || !connectionUrl.startsWith('postgresql://')) {
-    return false;
-  }
-
-  try {
-    // Parse URL to extract host and port
-    const url = new URL(connectionUrl);
-    const host = url.hostname;
-    const port = parseInt(url.port || '5432', 10);
-
-    return await checkTcpConnection(host, port, timeout);
-  } catch (error) {
-    console.warn('Invalid PostgreSQL URL:', error.message);
-    return false;
-  }
-}
-
-/**
- * Check if TCP connection can be established
- */
-function checkTcpConnection(host, port, timeout) {
-  return new Promise((resolve) => {
-    const socket = new net.Socket();
-
-    const cleanup = () => {
-      socket.destroy();
-    };
-
-    const timer = setTimeout(() => {
-      cleanup();
-      resolve(false);
-    }, timeout);
-
-    socket.once('connect', () => {
-      clearTimeout(timer);
-      cleanup();
-      resolve(true);
-    });
-
-    socket.once('error', () => {
-      clearTimeout(timer);
-      cleanup();
-      resolve(false);
-    });
-
-    socket.connect(port, host);
-  });
-}
-
-/**
- * Auto-detect database URL
- *
- * Priority:
- * 1. External PostgreSQL (if reachable)
- * 2. Embedded PGlite server (start if needed)
- */
-export async function autoDetect({
-  externalUrl,
-  embeddedDataDir,
-  embeddedPort = null,
-  timeout = 5000
-}) {
-  // Try external PostgreSQL first
-  if (externalUrl && externalUrl.startsWith('postgresql://')) {
-    console.log('🔍 Checking external PostgreSQL connection...');
-
-    if (await canConnectToPostgres(externalUrl, timeout)) {
-      console.log('✅ Using external PostgreSQL');
-      return {
-        type: 'external',
-        url: externalUrl,
-        embedded: false
-      };
-    }
-
-    console.warn('⚠️  External PostgreSQL unreachable, falling back to embedded');
-  }
-
-  // Start embedded server
-  console.log('🚀 Starting embedded PGlite server...');
-
-  const { getOrStart } = await import('./index.js');
-
-  const instance = await getOrStart({
-    dataDir: embeddedDataDir,
-    port: embeddedPort,
-    autoPort: true
-  });
-
-  console.log(`✅ Using embedded PGlite on port ${instance.port}`);
-
-  return {
-    type: 'embedded',
-    url: instance.connectionUrl,
-    embedded: true,
-    port: instance.port,
-    dataDir: instance.dataDir
-  };
-}

package/src/pool.js

@@ -1,320 +0,0 @@
-/**
- * PGlite Instance Pool (Performance Optimized)
- *
- * Manages multiple PGlite instances (one per database)
- * Handles lazy initialization, connection locking, and cleanup
- *
- * Performance Optimizations:
- * - Fast Map-based lookups (O(1) access)
- * - Minimal memory overhead per instance
- * - Pino structured logging
- * - Proper event listener cleanup
- */
-
-import { PGlite } from '@electric-sql/pglite';
-import path from 'path';
-import fs from 'fs';
-import { EventEmitter } from 'events';
-
-/**
- * Wrapper for PGlite instance with connection management
- */
-class ManagedInstance extends EventEmitter {
-  constructor(dbName, dataDir, logger, memoryMode = false) {
-    super();
-    this.dbName = dbName;
-    this.dataDir = dataDir;
-    this.memoryMode = memoryMode;
-    this.logger = logger; // Pino logger
-    this.db = null;
-    this.locked = false;
-    this.activeSocket = null;
-    this.lockTimer = null; // Safety timeout for locks
-    this.queue = [];
-    this.createdAt = Date.now();
-    this.lastAccess = Date.now();
-
-    // Performance: Limit max listeners
-    this.setMaxListeners(10);
-  }
-
-  /**
-   * Initialize PGlite instance (lazy)
-   */
-  async initialize() {
-    if (this.db) {
-      return this.db;
-    }
-
-    const initStart = Date.now();
-
-    if (this.memoryMode) {
-      // Use in-memory database (unique per instance)
-      this.logger.debug({ dbName: this.dbName, mode: 'memory' }, 'Initializing in-memory PGlite instance');
-      this.db = new PGlite();
-    } else {
-      // Ensure directory exists for file-based storage
-      if (!fs.existsSync(this.dataDir)) {
-        fs.mkdirSync(this.dataDir, { recursive: true });
-      }
-
-      this.logger.debug({ dbName: this.dbName, dataDir: this.dataDir }, 'Initializing PGlite instance');
-      this.db = new PGlite(this.dataDir);
-    }
-
-    await this.db.waitReady;
-
-    const initTime = Date.now() - initStart;
-    this.logger.info({
-      dbName: this.dbName,
-      dataDir: this.memoryMode ? '(in-memory)' : this.dataDir,
-      memoryMode: this.memoryMode,
-      initTimeMs: initTime
-    }, 'PGlite instance initialized');
-
-    this.emit('initialized', this.dbName);
-    return this.db;
-  }
-
-  /**
-   * Lock instance to a socket
-   * @param {net.Socket} socket - TCP socket to lock to
-   * @param {number} timeout - Safety timeout in ms (default 5 minutes)
-   */
-  lock(socket, timeout = 300000) {
-    if (this.locked) {
-      throw new Error(`Instance ${this.dbName} is already locked`);
-    }
-
-    this.locked = true;
-    this.activeSocket = socket;
-    this.lastAccess = Date.now();
-
-    // Safety net: auto-unlock after timeout (prevents permanent locks)
-    this.lockTimer = setTimeout(() => {
-      this.logger.warn({ dbName: this.dbName }, 'Lock timeout - forcing unlock');
-      this.unlock();
-    }, timeout);
-
-    // Only attach event listeners if socket is provided
-    if (socket) {
-      socket.on('close', () => this.unlock());
-      socket.on('error', () => this.unlock());
-    }
-
-    this.emit('locked', this.dbName, socket);
-  }
-
-  /**
-   * Unlock instance (connection closed)
-   */
-  unlock() {
-    // Clear safety timeout if it exists
-    if (this.lockTimer) {
-      clearTimeout(this.lockTimer);
-      this.lockTimer = null;
-    }
-
-    this.locked = false;
-    this.activeSocket = null;
-    this.lastAccess = Date.now();
-
-    this.emit('unlocked', this.dbName);
-
-    // Resolve one waiting promise (it will lock, then when it unlocks, the next will be resolved)
-    if (this.queue.length > 0) {
-      const { resolve } = this.queue.shift();
-      // Don't lock here - let the acquire() caller handle locking with their socket
-      resolve(this);
-    }
-  }
-
-  /**
-   * Wait for instance to be free
-   */
-  async waitForFree(timeout = 30000) {
-    if (!this.locked) {
-      return this;
-    }
-
-    return new Promise((resolve, reject) => {
-      this.queue.push({ socket: null, resolve, reject });
-
-      const timer = setTimeout(() => {
-        const index = this.queue.findIndex((item) => item.resolve === resolve);
-        if (index !== -1) {
-          this.queue.splice(index, 1);
-        }
-        reject(new Error(`Timeout waiting for database ${this.dbName}`));
-      }, timeout);
-
-      // Clear timeout on resolve
-      this.once('unlocked', () => clearTimeout(timer));
-    });
-  }
-
-  /**
-   * Close PGlite instance
-   */
-  async close() {
-    if (this.db) {
-      try {
-        await this.db.close();
-      } catch (error) {
-        // Ignore ExitStatus errors (normal WASM cleanup)
-        if (error.name !== 'ExitStatus') {
-          console.error(`Error closing instance ${this.dbName}:`, error.message);
-        }
-      }
-    }
-
-    this.db = null;
-    this.emit('closed', this.dbName);
-  }
-
-  /**
-   * Get instance stats
-   */
-  getStats() {
-    return {
-      dbName: this.dbName,
-      locked: this.locked,
-      queueLength: this.queue.length,
-      uptime: Date.now() - this.createdAt,
-      lastAccess: Date.now() - this.lastAccess
-    };
-  }
-}
-
-/**
- * PGlite Instance Pool
- */
-export class InstancePool extends EventEmitter {
-  constructor(options = {}) {
-    super();
-    this.baseDir = options.baseDir || './data';
-    this.memoryMode = options.memoryMode || false;
-    this.maxInstances = options.maxInstances || 100;
-    this.autoProvision = options.autoProvision !== false; // Default true
-    this.instances = new Map(); // dbName -> ManagedInstance (O(1) lookups)
-    this.logger = options.logger; // Pino logger
-
-    // Performance: Set max listeners based on max instances
-    this.setMaxListeners(this.maxInstances + 10);
-  }
-
-  /**
-   * Get or create PGlite instance for database (Performance Optimized)
-   */
-  async getOrCreate(dbName) {
-    // Fast path: Check cache first (O(1) lookup)
-    let instance = this.instances.get(dbName);
-
-    if (!instance) {
-      // Check max instances limit
-      if (this.instances.size >= this.maxInstances) {
-        this.logger.error({
-          dbName,
-          currentInstances: this.instances.size,
-          maxInstances: this.maxInstances
-        }, 'Maximum instances limit reached');
-
-        throw new Error(
-          `Maximum instances limit reached (${this.maxInstances}). ` +
-            `Cannot create database: ${dbName}`
-        );
-      }
-
-      if (!this.autoProvision) {
-        this.logger.warn({ dbName }, 'Database does not exist (auto-provision disabled)');
-        throw new Error(`Database ${dbName} does not exist (auto-provision disabled)`);
-      }
-
-      // Create new instance
-      const dataDir = this.memoryMode ? null : path.join(this.baseDir, dbName);
-      instance = new ManagedInstance(
-        dbName,
-        dataDir,
-        this.logger.child({ dbName }), // Child logger with context
-        this.memoryMode
-      );
-
-      // Forward events (use once() where appropriate for performance)
-      instance.on('initialized', (name) => this.emit('instance-created', name));
-      instance.on('locked', (name) => this.emit('instance-locked', name));
-      instance.on('unlocked', (name) => this.emit('instance-unlocked', name));
-      instance.on('closed', (name) => this.emit('instance-closed', name));
-
-      // Add to cache BEFORE initialization (prevents race conditions)
-      this.instances.set(dbName, instance);
-    }
-
-    // Lazy initialize (async, may already be initialized)
-    await instance.initialize();
-
-    return instance;
-  }
-
-  /**
-   * Acquire instance (lock to socket)
-   */
-  async acquire(dbName, socket, timeout = 30000) {
-    const instance = await this.getOrCreate(dbName);
-
-    // If locked, wait for it to be free
-    if (instance.locked) {
-      console.log(`⏳ Database ${dbName} is busy, queuing connection...`);
-      await instance.waitForFree(timeout);
-    }
-
-    // Lock to this socket
-    instance.lock(socket);
-
-    return instance;
-  }
-
-  /**
-   * Get instance (without locking)
-   */
-  get(dbName) {
-    return this.instances.get(dbName);
-  }
-
-  /**
-   * List all instances
-   */
-  list() {
-    return Array.from(this.instances.values()).map((instance) => instance.getStats());
-  }
-
-  /**
-   * Close specific instance
-   */
-  async closeInstance(dbName) {
-    const instance = this.instances.get(dbName);
-    if (instance) {
-      await instance.close();
-      this.instances.delete(dbName);
-    }
-  }
-
-  /**
-   * Close all instances
-   */
-  async closeAll() {
-    const promises = Array.from(this.instances.values()).map((instance) => instance.close());
-    await Promise.all(promises);
-    this.instances.clear();
-  }
-
-  /**
-   * Get pool stats
-   */
-  getStats() {
-    return {
-      totalInstances: this.instances.size,
-      maxInstances: this.maxInstances,
-      instances: this.list()
-    };
-  }
-}

package/src/ports.js

@@ -1,114 +0,0 @@
-import net from 'net';
-import { loadRegistry } from './registry.js';
-
-const PORT_RANGE_START = 12000;
-const PORT_RANGE_END = 12999;
-
-/**
- * Check if a port is available
- */
-export function isPortFree(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-
-    server.once('error', (err) => {
-      if (err.code === 'EADDRINUSE') {
-        resolve(false);
-      } else {
-        resolve(false);
-      }
-    });
-
-    server.once('listening', () => {
-      server.close();
-      resolve(true);
-    });
-
-    server.listen(port, '127.0.0.1');
-  });
-}
-
-/**
- * Check if port is in registry (even if process is dead)
- */
-function isPortInRegistry(port) {
-  const registry = loadRegistry();
-
-  for (const instance of Object.values(registry.instances)) {
-    if (instance.port === port) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Allocate a port for a data directory
- *
- * Priority:
- * 1. If instance already running, return its port
- * 2. Try preferred port (if provided)
- * 3. Find next available port in range
- */
-export async function allocatePort(dataDir, preferredPort = null) {
-  const registry = loadRegistry();
-
-  // Check if instance already exists for this dataDir
-  const existing = registry.instances[dataDir];
-  if (existing) {
-    // Verify process is still running
-    try {
-      process.kill(existing.pid, 0);
-      console.log(`Instance already running for ${dataDir} on port ${existing.port}`);
-      return existing.port;
-    } catch {
-      // Process dead, continue allocation
-      console.log(`Stale instance found for ${dataDir}, reallocating port`);
-    }
-  }
-
-  // Try preferred port first
-  if (preferredPort !== null) {
-    if (preferredPort < PORT_RANGE_START || preferredPort > PORT_RANGE_END) {
-      throw new Error(
-        `Preferred port ${preferredPort} outside allowed range ${PORT_RANGE_START}-${PORT_RANGE_END}`
-      );
-    }
-
-    if (await isPortFree(preferredPort) && !isPortInRegistry(preferredPort)) {
-      return preferredPort;
-    }
-
-    console.warn(`Preferred port ${preferredPort} unavailable, auto-allocating...`);
-  }
-
-  // Find next available port
-  for (let port = PORT_RANGE_START; port <= PORT_RANGE_END; port++) {
-    if ((await isPortFree(port)) && !isPortInRegistry(port)) {
-      return port;
-    }
-  }
-
-  throw new Error(
-    `No available ports in range ${PORT_RANGE_START}-${PORT_RANGE_END}. ` +
-    `Stop unused instances with 'pglite-server stop --all'`
-  );
-}
-
-/**
- * Get port range info
- */
-export function getPortRangeInfo() {
-  const registry = loadRegistry();
-  const usedPorts = Object.values(registry.instances).map((i) => i.port);
-
-  return {
-    start: PORT_RANGE_START,
-    end: PORT_RANGE_END,
-    total: PORT_RANGE_END - PORT_RANGE_START + 1,
-    used: usedPorts.length,
-    available: PORT_RANGE_END - PORT_RANGE_START + 1 - usedPorts.length,
-    usedPorts
-  };
-}