pgserve 1.1.4 → 1.1.5

package/README.md

@@ -72,6 +72,10 @@ psql postgresql://localhost:8432/myapp
     <td><b>Async Replication</b></td>
     <td>Sync to real PostgreSQL with minimal overhead</td>
   </tr>
+  <tr>
+    <td><b>pgvector Built-in</b></td>
+    <td>Use <code>--pgvector</code> for auto-enabled vector similarity search</td>
+  </tr>
   <tr>
     <td><b>Cross-Platform</b></td>
     <td>Linux x64, macOS ARM64/x64, Windows x64</td>
@@ -129,6 +133,8 @@ Options:
   --no-provision        Disable auto-provisioning of databases
   --sync-to <url>       Sync to real PostgreSQL (async replication)
   --sync-databases <p>  Database patterns to sync (comma-separated)
+  --pgvector            Auto-enable pgvector extension on new databases
+  --max-connections <n> Max concurrent connections (default: 1000)
   --help                Show help message
 ```
 
@@ -148,6 +154,12 @@ pgserve --data /var/lib/pgserve
 # Custom port
 pgserve --port 5433
 
+# Enable pgvector for AI/RAG applications
+pgserve --pgvector
+
+# RAM mode + pgvector (fastest for AI workloads)
+pgserve --ram --pgvector
+
 # Sync to production PostgreSQL
 pgserve --sync-to "postgresql://user:pass@db.example.com:5432/prod"
 ```
@@ -167,6 +179,7 @@ const server = await startMultiTenantServer({
   baseDir: null,        // null = memory mode
   logLevel: 'info',
   autoProvision: true,
+  enablePgvector: true, // Auto-enable pgvector on new databases
   syncTo: null,         // Optional: PostgreSQL URL for replication
   syncDatabases: null   // Optional: patterns like "myapp,tenant_*"
 });
@@ -258,6 +271,52 @@ pgserve --sync-to "postgresql://..." --sync-databases "myapp,tenant_*"
 
 <br>
 
+## pgvector (Vector Search)
+
+pgvector is **built-in** — no separate installation required. Just enable it:
+
+```bash
+# Auto-enable pgvector on all new databases
+pgserve --pgvector
+
+# Combined with RAM mode for fastest vector operations
+pgserve --ram --pgvector
+```
+
+When `--pgvector` is enabled, every new database automatically has the vector extension installed. No SQL setup required.
+
+<details>
+<summary><b>Using pgvector</b></summary>
+
+```sql
+-- Create table with vector column (1536 = OpenAI embedding size)
+CREATE TABLE documents (id SERIAL, content TEXT, embedding vector(1536));
+
+-- Insert with embedding
+INSERT INTO documents (content, embedding) VALUES ('Hello', '[0.1, 0.2, ...]');
+
+-- k-NN similarity search (L2 distance)
+SELECT content FROM documents ORDER BY embedding <-> $1 LIMIT 10;
+```
+
+See [pgvector documentation](https://github.com/pgvector/pgvector) for full API reference.
+</details>
+
+<details>
+<summary><b>Without --pgvector flag</b></summary>
+
+If you don't use `--pgvector`, you can still enable pgvector manually per database:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+</details>
+
+> pgvector 0.8.1 is bundled with the PostgreSQL binaries. Supports L2 distance (`<->`), inner product (`<#>`), and cosine distance (`<=>`).
+
+<br>
+
 ## Performance
 
 ### CRUD Benchmarks

package/bin/pglite-server.js

@@ -55,6 +55,7 @@ OPTIONS:
   --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)
+  --pgvector         Auto-enable pgvector extension on new databases
   --help             Show this help message
 
 MODES:
@@ -112,7 +113,8 @@ function parseArgs() {
     syncTo: null,  // Sync target PostgreSQL URL
     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)
+    maxConnections: 1000, // Max concurrent connections (high default for multi-tenant)
+    enablePgvector: false // Auto-enable pgvector extension on new databases
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -179,6 +181,10 @@ function parseArgs() {
         options.maxConnections = parseInt(args[++i], 10);
         break;
 
+      case '--pgvector':
+        options.enablePgvector = true;
+        break;
+
       case '--help':
       case 'help':
         printHelp();
@@ -228,7 +234,8 @@ pgserve - Embedded PostgreSQL Server
         logLevel: options.logLevel,
         autoProvision: options.autoProvision,
         workers: options.workers,
-        maxConnections: options.maxConnections
+        maxConnections: options.maxConnections,
+        enablePgvector: options.enablePgvector
       });
 
       // Only primary process shows full startup message
@@ -243,6 +250,7 @@ Cluster started successfully!
   Workers:     ${stats.workers} processes
   Data:        ${storageType}
   Auto-create: ${options.autoProvision ? 'Enabled' : 'Disabled'}
+  pgvector:    ${options.enablePgvector ? 'Enabled (auto-installed on new DBs)' : 'Disabled (use --pgvector to enable)'}
 
 Examples:
   postgresql://${options.host}:${options.port}/myapp
@@ -262,7 +270,8 @@ Press Ctrl+C to stop
         autoProvision: options.autoProvision,
         syncTo: options.syncTo,
         syncDatabases: options.syncDatabases,
-        maxConnections: options.maxConnections
+        maxConnections: options.maxConnections,
+        enablePgvector: options.enablePgvector
       });
 
       server = router;
@@ -280,6 +289,7 @@ Server started successfully!
   Data:        ${storageType}
   PostgreSQL:  Port ${router.pgPort} (internal)
   Auto-create: ${options.autoProvision ? 'Enabled' : 'Disabled'}
+  pgvector:    ${options.enablePgvector ? 'Enabled (auto-installed on new DBs)' : 'Disabled (use --pgvector to enable)'}
   Sync:        ${syncStatus}${options.syncDatabases ? ` (${options.syncDatabases})` : ''}
 
 Examples:

package/package.json

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

package/src/cluster.js

@@ -42,6 +42,7 @@ class ClusterRouter extends EventEmitter {
     this.pgPassword = options.pgPassword || 'postgres';
     this.autoProvision = options.autoProvision !== false;
     this.maxConnections = options.maxConnections || 1000;
+    this.enablePgvector = options.enablePgvector || false;
 
     this.logger = createLogger({ level: options.logLevel || 'info' });
     this.sql = null;  // Bun.sql for admin queries
@@ -124,6 +125,11 @@ class ClusterRouter extends EventEmitter {
       if (result.length === 0) {
         // Use sql() helper for safe identifier escaping (like CREATE DATABASE)
         await this.sql.unsafe(`CREATE DATABASE "${dbName.replace(/"/g, '""')}"`);
+
+        // Auto-enable pgvector extension if configured
+        if (this.enablePgvector) {
+          await this.enablePgvectorExtension(dbName);
+        }
       }
     } catch (error) {
       // Ignore "already exists" (race condition between workers)
@@ -133,6 +139,41 @@ class ClusterRouter extends EventEmitter {
     }
   }
 
+  /**
+   * Enable pgvector extension on a database
+   * Creates a temporary connection to the specific database to run CREATE EXTENSION
+   * @param {string} dbName - Database name to enable pgvector on
+   */
+  async enablePgvectorExtension(dbName) {
+    let dbPool = null;
+
+    try {
+      // Create temporary connection to the specific database
+      dbPool = new SQL({
+        hostname: '127.0.0.1',
+        port: this.pgPort,
+        database: dbName,
+        username: this.pgUser,
+        password: this.pgPassword,
+        max: 1,
+        idleTimeout: 5,
+        connectionTimeout: 5,
+      });
+
+      // Enable pgvector extension
+      await dbPool.unsafe('CREATE EXTENSION IF NOT EXISTS vector');
+      this.logger.info({ dbName }, 'pgvector extension enabled');
+    } catch (error) {
+      // Log but don't fail database creation - pgvector might not be available
+      this.logger.warn({ dbName, err: error.message }, 'Failed to enable pgvector extension (non-fatal)');
+    } finally {
+      // Always close the temporary connection
+      if (dbPool) {
+        await dbPool.close().catch(() => {});
+      }
+    }
+  }
+
   /**
    * Handle socket open (Bun TCP handler)
    */
@@ -342,7 +383,8 @@ export async function startClusterServer(options = {}) {
       dataDir: options.baseDir,
       port: pgPort,
       logger: logger.child({ component: 'postgres' }),
-      useRam: options.useRam  // Use /dev/shm for true RAM storage (Linux only)
+      useRam: options.useRam,  // Use /dev/shm for true RAM storage (Linux only)
+      enablePgvector: options.enablePgvector  // Auto-enable pgvector extension on new databases
     });
 
     await pgManager.start();
@@ -366,7 +408,8 @@ export async function startClusterServer(options = {}) {
         PGSERVE_PG_PASSWORD: 'postgres',
         PGSERVE_LOG_LEVEL: options.logLevel || 'info',
         PGSERVE_AUTO_PROVISION: options.autoProvision !== false ? 'true' : 'false',
-        PGSERVE_MAX_CONNECTIONS: String(options.maxConnections || 1000)
+        PGSERVE_MAX_CONNECTIONS: String(options.maxConnections || 1000),
+        PGSERVE_ENABLE_PGVECTOR: options.enablePgvector ? 'true' : 'false'
       });
       workers.set(worker.id, worker);
     }
@@ -393,7 +436,8 @@ export async function startClusterServer(options = {}) {
         PGSERVE_PG_PASSWORD: 'postgres',
         PGSERVE_LOG_LEVEL: options.logLevel || 'info',
         PGSERVE_AUTO_PROVISION: options.autoProvision !== false ? 'true' : 'false',
-        PGSERVE_MAX_CONNECTIONS: String(options.maxConnections || 1000)
+        PGSERVE_MAX_CONNECTIONS: String(options.maxConnections || 1000),
+        PGSERVE_ENABLE_PGVECTOR: options.enablePgvector ? 'true' : 'false'
       });
       workers.set(newWorker.id, newWorker);
     });
@@ -480,7 +524,8 @@ export async function startClusterServer(options = {}) {
       pgPassword: process.env.PGSERVE_PG_PASSWORD || 'postgres',
       logLevel: process.env.PGSERVE_LOG_LEVEL || 'info',
       autoProvision: process.env.PGSERVE_AUTO_PROVISION === 'true',
-      maxConnections: parseInt(process.env.PGSERVE_MAX_CONNECTIONS) || 1000
+      maxConnections: parseInt(process.env.PGSERVE_MAX_CONNECTIONS) || 1000,
+      enablePgvector: process.env.PGSERVE_ENABLE_PGVECTOR === 'true'
     });
 
     await router.start();

package/src/postgres.js

@@ -406,6 +406,9 @@ export class PostgresManager {
     // Sync/Replication options (for async sync to real PostgreSQL)
     this.syncEnabled = options.syncEnabled || false;
     this.syncManager = null; // Will be set via setSyncManager()
+
+    // pgvector extension auto-enable
+    this.enablePgvector = options.enablePgvector || false;
   }
 
   /**
@@ -880,6 +883,11 @@ export class PostgresManager {
       this.createdDatabases.add(dbName);
       this.logger.info({ dbName }, 'Database created');
 
+      // Auto-enable pgvector extension if configured
+      if (this.enablePgvector) {
+        await this.enablePgvectorExtension(dbName);
+      }
+
       // Trigger async sync setup (non-blocking, doesn't affect hot path)
       if (this.syncManager) {
         this.syncManager.setupDatabaseSync(dbName)
@@ -909,6 +917,42 @@ export class PostgresManager {
     }
   }
 
+  /**
+   * Enable pgvector extension on a database
+   * Creates a temporary connection to the specific database to run CREATE EXTENSION
+   * @param {string} dbName - Database name to enable pgvector on
+   */
+  async enablePgvectorExtension(dbName) {
+    const { SQL } = await import('bun');
+    let dbPool = null;
+
+    try {
+      // Create temporary connection to the specific database
+      dbPool = new SQL({
+        hostname: '127.0.0.1',
+        port: this.port,
+        database: dbName,
+        username: this.user,
+        password: this.password,
+        max: 1,
+        idleTimeout: 5,
+        connectionTimeout: 5,
+      });
+
+      // Enable pgvector extension
+      await dbPool.unsafe('CREATE EXTENSION IF NOT EXISTS vector');
+      this.logger.info({ dbName }, 'pgvector extension enabled');
+    } catch (error) {
+      // Log but don't fail database creation - pgvector might not be available
+      this.logger.warn({ dbName, err: error.message }, 'Failed to enable pgvector extension (non-fatal)');
+    } finally {
+      // Always close the temporary connection
+      if (dbPool) {
+        await dbPool.close().catch(() => {});
+      }
+    }
+  }
+
   /**
    * Check if a database exists
    * @param {string} dbName - Database name to check

package/src/router.js

@@ -61,7 +61,8 @@ export class MultiTenantRouter extends EventEmitter {
       port: this.pgPort,
       logger: this.logger.child({ component: 'postgres' }),
       syncEnabled: !!this.syncTo,  // Enable logical replication if sync is configured
-      useRam: options.useRam  // Use /dev/shm for true RAM storage (Linux only)
+      useRam: options.useRam,  // Use /dev/shm for true RAM storage (Linux only)
+      enablePgvector: options.enablePgvector  // Auto-enable pgvector extension on new databases
     });
 
     // TCP server

package/src/stats-collector.js

@@ -38,6 +38,15 @@ export class StatsCollector {
     // Disk I/O tracking (Linux)
     this.lastDiskStats = null;
     this.lastDiskTime = 0;
+
+    // pgvector stats cache (longer TTL since it requires cross-DB queries)
+    this.pgvectorCache = null;
+    this.pgvectorCacheTime = 0;
+    this.pgvectorCacheTTL = 5000; // 5s cache for pgvector stats
+
+    // Connection pool reuse for pgvector stats (avoids TCP handshake overhead per collection)
+    this.pgvectorDbPools = new Map(); // dbName -> SQL pool
+    this.pgvectorExtCache = new Map(); // dbName -> boolean (vector extension exists)
   }
 
   /**
@@ -97,6 +106,9 @@ export class StatsCollector {
       // PostgreSQL internals (pg_stat_*)
       internals: await this.collectPgStats(),
 
+      // pgvector stats (if enabled)
+      pgvector: await this.collectPgvectorStats(),
+
       // Process stats
       process: {
         pid: process.pid,
@@ -264,4 +276,178 @@ export class StatsCollector {
       return null;
     }
   }
+
+  /**
+   * Collect pgvector statistics across all databases
+   * Uses separate cache with longer TTL due to cross-DB query overhead
+   */
+  async collectPgvectorStats() {
+    // Return cached if recent
+    if (this.pgvectorCache && Date.now() - this.pgvectorCacheTime < this.pgvectorCacheTTL) {
+      return this.pgvectorCache;
+    }
+
+    const adminPool = this.pgManager?.adminPool;
+    if (!adminPool) return null;
+
+    // Query PostgreSQL directly for databases (pgManager.getStats().databases may be empty in cluster mode)
+    let databases = [];
+    try {
+      const dbResult = await adminPool`
+        SELECT datname FROM pg_database
+        WHERE datname NOT IN ('template0', 'template1', 'postgres')
+      `;
+      databases = dbResult.map(row => row.datname);
+    } catch (err) {
+      this.logger?.debug?.({ err: err.message }, 'Failed to query databases for pgvector stats');
+      return null;
+    }
+
+    if (databases.length === 0) return null;
+
+    try {
+      let totalTables = 0;
+      let totalRows = 0;
+      const dimensions = new Set();
+      let dbsWithVectors = 0;
+
+      // Query each database for vector columns (parallel for performance)
+      const allDbStats = await Promise.all(
+        databases.map(dbName => this.queryDatabaseVectorStats(dbName))
+      );
+
+      for (const dbStats of allDbStats) {
+        if (dbStats && dbStats.tableCount > 0) {
+          dbsWithVectors++;
+          totalTables += dbStats.tableCount;
+          totalRows += dbStats.rowCount;
+          dbStats.dimensions.forEach(d => dimensions.add(d));
+        }
+      }
+
+      // Only return stats if vectors exist
+      if (totalTables === 0) {
+        this.pgvectorCache = null;
+        this.pgvectorCacheTime = Date.now();
+        return null;
+      }
+
+      const stats = {
+        enabled: true,
+        databases: dbsWithVectors,
+        tableCount: totalTables,
+        totalRows: totalRows,
+        dimensions: [...dimensions].sort((a, b) => b - a).join(', ') || null
+      };
+
+      this.pgvectorCache = stats;
+      this.pgvectorCacheTime = Date.now();
+      return stats;
+    } catch (err) {
+      this.logger?.debug?.({ err: err.message }, 'Failed to collect pgvector stats');
+      return null;
+    }
+  }
+
+  /**
+   * Query vector column stats for a specific database
+   * @param {string} dbName - Database name to query
+   * @returns {Promise<{tableCount: number, rowCount: number, dimensions: number[]}>}
+   */
+  async queryDatabaseVectorStats(dbName) {
+    try {
+      // Reuse connection pool (avoids TCP handshake + auth overhead per collection)
+      let dbPool = this.pgvectorDbPools.get(dbName);
+      if (!dbPool) {
+        const { SQL } = await import('bun');
+        dbPool = new SQL({
+          hostname: '127.0.0.1',
+          port: this.pgManager?.port || 5433,
+          database: dbName,
+          username: 'postgres',
+          password: 'postgres',
+          max: 2, // Allow some concurrency
+          idleTimeout: 30, // Keep alive longer for reuse
+          connectionTimeout: 3,
+        });
+        this.pgvectorDbPools.set(dbName, dbPool);
+      }
+
+      // Check cached extension status (only query once per DB)
+      if (!this.pgvectorExtCache.has(dbName)) {
+        const extCheck = await dbPool`
+          SELECT 1 FROM pg_extension WHERE extname = 'vector'
+        `;
+        this.pgvectorExtCache.set(dbName, extCheck.length > 0);
+      }
+
+      if (!this.pgvectorExtCache.get(dbName)) {
+        return { tableCount: 0, rowCount: 0, dimensions: [] };
+      }
+
+      // Single query: get tables, dimensions, and row counts via pg_class.reltuples
+      // Note: reltuples is an estimate (updated by ANALYZE/VACUUM), not exact COUNT(*)
+      // This is acceptable for dashboard stats with 5s cache - avoids expensive full table scans
+      // Trade-off: ~50-100x faster, but counts may be stale after bulk INSERT/DELETE until ANALYZE
+      const vectorInfo = await dbPool`
+        SELECT
+          c.relname as table_name,
+          a.atttypmod as dimensions,
+          GREATEST(c.reltuples, 0)::bigint AS row_count
+        FROM pg_attribute a
+        JOIN pg_class c ON a.attrelid = c.oid
+        JOIN pg_type t ON a.atttypid = t.oid
+        WHERE t.typname = 'vector'
+          AND c.relkind = 'r'
+          AND a.attnum > 0
+          AND NOT a.attisdropped
+      `;
+
+      if (vectorInfo.length === 0) {
+        return { tableCount: 0, rowCount: 0, dimensions: [] };
+      }
+
+      // Aggregate results from single query
+      const tableRows = new Map();
+      const dims = [];
+
+      for (const row of vectorInfo) {
+        if (!tableRows.has(row.table_name)) {
+          tableRows.set(row.table_name, Number(row.row_count || 0));
+        }
+        if (row.dimensions > 0) {
+          dims.push(row.dimensions);
+        }
+      }
+
+      const totalRows = Array.from(tableRows.values()).reduce((sum, count) => sum + count, 0);
+
+      return {
+        tableCount: tableRows.size,
+        rowCount: totalRows,
+        dimensions: dims
+      };
+    } catch (err) {
+      this.logger?.debug?.({ dbName, err: err.message }, 'Failed to query database vector stats');
+      // Invalidate caches on error (DB might have been dropped)
+      this.pgvectorExtCache.delete(dbName);
+      const pool = this.pgvectorDbPools.get(dbName);
+      if (pool) {
+        this.pgvectorDbPools.delete(dbName);
+        await pool.close().catch(() => {});
+      }
+      return { tableCount: 0, rowCount: 0, dimensions: [] };
+    }
+  }
+
+  /**
+   * Close all pgvector database pools (called on shutdown)
+   */
+  async closePgvectorPools() {
+    for (const [_dbName, pool] of this.pgvectorDbPools) {
+      await pool.close().catch(() => {});
+    }
+    this.pgvectorDbPools.clear();
+    this.pgvectorExtCache.clear();
+  }
 }

package/src/stats-dashboard.js

@@ -261,6 +261,25 @@ export class StatsDashboard {
       }
     }
 
+    // pgvector section (only if vector data exists)
+    if (stats.pgvector?.enabled && stats.pgvector.tableCount > 0) {
+      const vecLines = [
+        `${ANSI.DIM}Databases:${ANSI.RESET}   ${stats.pgvector.databases} with vectors`,
+        `${ANSI.DIM}Tables:${ANSI.RESET}      ${stats.pgvector.tableCount} total`
+      ];
+
+      if (stats.pgvector.totalRows > 0) {
+        vecLines.push(`${ANSI.DIM}Vectors:${ANSI.RESET}     ${this.formatNumber(stats.pgvector.totalRows)} rows`);
+      }
+
+      if (stats.pgvector.dimensions) {
+        vecLines.push(`${ANSI.DIM}Dimensions:${ANSI.RESET}  ${stats.pgvector.dimensions}`);
+      }
+
+      lines.push(this.section('PGVECTOR', vecLines));
+      lines.push('');
+    }
+
     // System resources section
     const resourceLines = [];