pgserve 0.1.4 → 1.0.1

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(kill:*)",
+      "Bash(pkill:*)",
+      "Bash(xargs:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/README.md

@@ -1,323 +1,348 @@
-# pgserve
+<div align="center">
+  <h1>pgserve</h1>
+  <p><strong>Embedded PostgreSQL Server with TRUE Concurrent Connections</strong></p>
 
-**Multi-tenant PostgreSQL router using PGlite** - Single port, auto-provisioning, zero config.
+  <p>
+    <a href="https://www.npmjs.com/package/pgserve"><img src="https://img.shields.io/npm/v/pgserve?style=flat-square&color=00D9FF" alt="npm version"></a>
+    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square" alt="Node.js">
+    <img src="https://img.shields.io/badge/PostgreSQL-17.7-blue?style=flat-square" alt="PostgreSQL">
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"></a>
+    <a href="https://discord.gg/xcW8c7fF3R"><img src="https://img.shields.io/discord/1095114867012292758?style=flat-square&color=00D9FF&label=discord" alt="Discord"></a>
+  </p>
 
-Perfect for multi-user apps, AI agents, and embedded databases.
+  <p><em>Zero config, auto-provision databases, unlimited concurrent connections. Just works.</em></p>
 
-## ✨ Features
+  <p>
+    <a href="#-quick-start">Quick Start</a> •
+    <a href="#-features">Features</a> •
+    <a href="#-cli-reference">CLI</a> •
+    <a href="#-api">API</a> •
+    <a href="#-performance">Performance</a>
+  </p>
+</div>
 
-- 🎯 **Multi-Tenant** - Single port, multiple isolated databases (one per user/app)
-- 🚀 **Auto-Provisioning** - Databases created on demand from connection string
-- 🔌 **Single Endpoint** - `postgresql://localhost:8432/dbname` routes to correct PGlite instance
-- ⚡ **High Performance** - MVCC, row-level locking, concurrent writes
-- 🎛️ **Zero Configuration** - Auto-tuned for your hardware (CPU, RAM)
-- 📦 **PostgreSQL Compatible** - Works with any PostgreSQL client (psql, Prisma, pg, etc.)
-- 🛡️ **Data Isolation** - Each database = separate PGlite instance
-- 💾 **Persistent** - Data survives restarts
+<br>
 
-## 🎯 Use Cases
-
-### Perfect For
-
-- 🤖 **AI Agents** - Each agent gets isolated database (sessions, memory, state)
-- 👥 **Multi-User Apps** - One database per user, single endpoint
-- 🏢 **SaaS Applications** - Tenant isolation without infrastructure complexity
-- 🧪 **Development** - Local PostgreSQL without Docker
-- 📱 **Desktop Apps** - Electron, Tauri with embedded multi-tenant DB
-
-### Real-World Examples
-
-- **AI Agent Swarms**: 100+ agents, each with isolated database
-- **Multi-Tenant SaaS**: Single endpoint, automatic tenant provisioning
-- **Desktop Apps**: Embedded PostgreSQL with multi-user support
-
-## 🚀 Quick Start
-
-### Installation
+## Quick Start
 
 ```bash
-npm install pgserve
-# or
-pnpm add pgserve
-```
-
-### Multi-Tenant Mode (Recommended)
-
-```javascript
-import { startMultiTenantServer } from 'pgserve';
-
-// Start multi-tenant router on single port
-const router = await startMultiTenantServer({
-  port: 8432,           // Single port for all databases
-  baseDir: './data',    // Base directory (creates ./data/dbname/ per DB)
-  autoProvision: true,  // Auto-create databases (default: true)
-  maxInstances: 100,    // Max concurrent databases
-  logLevel: 'info'
-});
-
-// Clients connect like normal PostgreSQL:
-// postgresql://localhost:8432/user123  → ./data/user123/
-// postgresql://localhost:8432/app456   → ./data/app456/
-```
-
-### Usage with PostgreSQL Clients
-
-```javascript
-import pg from 'pg';
-
-// Connect to database "user123" (auto-created)
-const client1 = new pg.Client({
-  connectionString: 'postgresql://localhost:8432/user123'
-});
-
-await client1.connect();
-await client1.query('CREATE TABLE users (id SERIAL, name TEXT)');
-await client1.query("INSERT INTO users (name) VALUES ('Alice')");
-
-// Connect to database "app456" (different isolated instance)
-const client2 = new pg.Client({
-  connectionString: 'postgresql://localhost:8432/app456'
-});
-
-await client2.connect();
-await client2.query('CREATE TABLE posts (id SERIAL, title TEXT)');
-
-// Each database is completely isolated!
+npx pgserve
 ```
 
-### With Prisma
-
-```javascript
-// prisma/schema.prisma
-datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
-
-// .env
-DATABASE_URL="postgresql://localhost:8432/myapp"
-```
+Connect from any PostgreSQL client — databases auto-create on first connection:
 
 ```bash
-# Auto-provisions "myapp" database
-npx prisma migrate dev
+psql postgresql://localhost:5432/myapp
 ```
 
-## 📖 API Reference
-
-### `startMultiTenantServer(options)`
+<br>
+
+## Features
+
+<table>
+  <tr>
+    <td><b>Unlimited Concurrency</b></td>
+    <td>Native PostgreSQL process forking — no connection locks</td>
+  </tr>
+  <tr>
+    <td><b>Zero Config</b></td>
+    <td>Just run <code>pgserve</code>, connect to any database name</td>
+  </tr>
+  <tr>
+    <td><b>Auto-Provision</b></td>
+    <td>Databases created automatically on first connection</td>
+  </tr>
+  <tr>
+    <td><b>Memory Mode</b></td>
+    <td>Fast and ephemeral for development (default)</td>
+  </tr>
+  <tr>
+    <td><b>Persistent Mode</b></td>
+    <td>Use <code>--data ./path</code> for durable storage</td>
+  </tr>
+  <tr>
+    <td><b>Async Replication</b></td>
+    <td>Sync to real PostgreSQL with zero performance impact</td>
+  </tr>
+  <tr>
+    <td><b>Cross-Platform</b></td>
+    <td>Linux x64, macOS ARM64/x64, Windows x64</td>
+  </tr>
+  <tr>
+    <td><b>Any Client Works</b></td>
+    <td>psql, node-postgres, Prisma, Drizzle, TypeORM</td>
+  </tr>
+</table>
+
+<br>
+
+## Installation
 
-Start multi-tenant router server.
+```bash
+# Zero install (recommended)
+npx pgserve
 
-```javascript
-const router = await startMultiTenantServer({
-  port: 8432,             // Port to listen on (default: 8432)
-  host: '127.0.0.1',      // Host to bind (default: 127.0.0.1)
-  baseDir: './data',      // Base data directory (default: './data')
-  autoProvision: true,    // Auto-create databases (default: true)
-  maxInstances: 100,      // Max concurrent databases (default: 100)
-  logLevel: 'info',       // Log level: error, warn, info, debug (default: 'info')
-  inspect: false          // Enable wire protocol debugging (default: false)
-});
+# Global install
+npm install -g pgserve
 
-// Returns MultiTenantRouter instance
+# Project dependency
+npm install pgserve
 ```
 
-### Router Methods
-
-```javascript
-// Get router stats
-const stats = router.getStats();
-// {
-//   port: 8432,
-//   activeConnections: 2,
-//   pool: {
-//     totalInstances: 3,
-//     maxInstances: 100,
-//     instances: [...]
-//   }
-// }
-
-// List all databases
-const databases = router.listDatabases();
-// [
-//   { dbName: 'user123', locked: false, queueLength: 0, ... },
-//   { dbName: 'app456', locked: true, queueLength: 1, ... }
-// ]
-
-// Stop router (closes all instances)
-await router.stop();
-```
+> PostgreSQL binaries are automatically downloaded on first run.
 
-## 🏗️ Architecture
+<br>
 
-### Single Port, Multi-Tenant Routing
+## CLI Reference
 
 ```
-Client 1: postgresql://localhost:8432/user123
-Client 2: postgresql://localhost:8432/app456
-Client 3: postgresql://localhost:8432/tenant789
-         ↓
-┌────────────────────────────────────────┐
-│  Multi-Tenant Router (port 8432)       │
-│  - Parses connection database name     │
-│  - Routes to correct PGlite instance   │
-│  - Auto-provisions new databases       │
-└────────────────────────────────────────┘
-         ↓
-┌────────────────────────────────────────┐
-│  Instance Pool                         │
-│  ├─ user123   → PGlite('./data/user123')   │
-│  ├─ app456    → PGlite('./data/app456')    │
-│  └─ tenant789 → PGlite('./data/tenant789') │
-└────────────────────────────────────────┘
+pgserve [options]
+
+Options:
+  --port <number>       PostgreSQL port (default: 5432)
+  --data <path>         Data directory for persistence (default: in-memory)
+  --host <host>         Host to bind to (default: 127.0.0.1)
+  --log <level>         Log level: error, warn, info, debug (default: info)
+  --cluster             Force cluster mode (auto-enabled on multi-core)
+  --no-cluster          Force single-process mode
+  --workers <n>         Number of worker processes (default: CPU cores)
+  --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)
+  --help                Show help message
 ```
 
-### How It Works
+<details>
+<summary><b>Examples</b></summary>
 
-1. **Client connects**: `postgresql://localhost:8432/myapp`
-2. **Router parses** PostgreSQL startup message → extracts database name: `myapp`
-3. **Pool checks** for existing PGlite instance for `myapp`
-4. **Auto-provision** creates `./data/myapp/` if doesn't exist
-5. **Route connection** to PGlite instance
-6. **Client communicates** with isolated database
+```bash
+# Development (memory mode, auto-clusters on multi-core)
+pgserve
 
-### Connection Lifecycle
+# Persistent storage
+pgserve --data /var/lib/pgserve
 
-- **First connection to DB**: PGlite instance created, database initialized
-- **Subsequent connections**: Reuses existing PGlite instance
-- **Concurrent connections**: Queued (PGlite is single-connection per instance)
-- **Connection closes**: Instance unlocked, ready for next connection
+# Custom port
+pgserve --port 5433
 
-## 📊 Performance
+# Sync to production PostgreSQL
+pgserve --sync-to "postgresql://user:pass@db.example.com:5432/prod"
+```
 
-### vs Multiple Port Approach
+</details>
 
-| Approach | Ports Used | Management | Scalability |
-|----------|-----------|------------|-------------|
-| **Multi-tenant** | 1 | Auto | ✅ Excellent (100+ DBs) |
-| Multi-port | 1 per DB | Manual | ⚠️ Limited (port exhaustion) |
+<br>
 
-### Benchmarks
+## API
 
-- **DB creation**: ~50ms per database (lazy initialization)
-- **Connection routing**: < 1ms overhead
-- **Concurrent databases**: Tested with 100+ isolated instances
-- **Memory**: ~10-30MB per PGlite instance (depends on data)
+```javascript
+import { startMultiTenantServer } from 'pgserve';
 
-## 🔧 CLI Usage
+const server = await startMultiTenantServer({
+  port: 5432,
+  host: '127.0.0.1',
+  baseDir: null,        // null = memory mode
+  logLevel: 'info',
+  autoProvision: true,
+  syncTo: null,         // Optional: PostgreSQL URL for replication
+  syncDatabases: null   // Optional: patterns like "myapp,tenant_*"
+});
 
-### Install Globally
+// Get stats
+console.log(server.getStats());
 
-```bash
-npm install -g pgserve
+// Graceful shutdown
+await server.stop();
 ```
 
-### Commands
-
-```bash
-# Start multi-tenant router
-pgserve start --port 8432 --dir ./data
-
-# Check router status
-pgserve router-stats
-
-# List all databases
-pgserve list-databases
+<br>
 
-# Stop router
-pgserve stop-router
-```
+## Framework Integration
 
-## 🛠️ Advanced Usage
-
-### Custom Instance Pool
+<details>
+<summary><b>node-postgres</b></summary>
 
 ```javascript
-import { InstancePool } from 'pgserve';
+import pg from 'pg';
 
-const pool = new InstancePool({
-  baseDir: './databases',
-  maxInstances: 50,
-  autoProvision: true
+const client = new pg.Client({
+  connectionString: 'postgresql://localhost:5432/myapp'
 });
 
-// Get or create instance
-const instance = await pool.getOrCreate('mydb');
-
-// Access PGlite directly
-const result = await instance.db.query('SELECT version()');
+await client.connect();
+await client.query('CREATE TABLE users (id SERIAL, name TEXT)');
+await client.query("INSERT INTO users (name) VALUES ('Alice')");
+const result = await client.query('SELECT * FROM users');
+console.log(result.rows);
+await client.end();
 ```
 
-### Connection Queueing
-
-PGlite is **single-connection** per instance. When multiple clients connect to the same database:
-
-```javascript
-// Client 1 connects to "mydb" → locks instance
-const client1 = new pg.Client({ database: 'mydb', ... });
-await client1.connect(); // ✅ Connected
-
-// Client 2 tries to connect to "mydb" → queued
-const client2 = new pg.Client({ database: 'mydb', ... });
-await client2.connect(); // ⏳ Waits for client1 to disconnect
+</details>
 
-// Client 1 disconnects
-await client1.end();
+<details>
+<summary><b>Prisma</b></summary>
 
-// Client 2 auto-connects
-// ✅ Connected
+```prisma
+// prisma/schema.prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
 ```
 
-Default timeout: **30 seconds**. Customize in `pool.acquire()`:
+```bash
+# .env
+DATABASE_URL="postgresql://localhost:5432/myapp"
 
-```javascript
-await pool.acquire('mydb', socket, timeout = 60000); // 60s timeout
+# Run migrations
+npx prisma migrate dev
 ```
 
-## 🔐 Security Notes
+</details>
 
-- **No authentication**: PGlite doesn't support auth (embedded use case)
-- **Bind to localhost**: Default `127.0.0.1` (local only)
-- **Production**: Use proper PostgreSQL for external access
+<details>
+<summary><b>Drizzle</b></summary>
 
-## 📁 File Structure
-
-```
-./data/
-  ├─ user123/        (PGlite data for "user123" database)
-  │  ├─ base/
-  │  ├─ pg_wal/
-  │  └─ PG_VERSION
-  ├─ app456/         (PGlite data for "app456" database)
-  └─ tenant789/      (PGlite data for "tenant789" database)
-```
+```typescript
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
 
-## 🤝 Contributing
+const pool = new Pool({
+  connectionString: 'postgresql://localhost:5432/myapp'
+});
 
-Contributions welcome! Please:
+const db = drizzle(pool);
+const users = await db.select().from(usersTable);
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new features
-4. Submit a pull request
+</details>
 
-## 📄 License
+<br>
 
-MIT License - Copyright (c) 2025 Namastex Labs
+## Async Replication
 
-## 🙏 Credits
+Sync ephemeral pgserve data to a real PostgreSQL database. Uses native logical replication for **zero performance impact** on the hot path.
 
-Built on top of:
-- [@electric-sql/pglite](https://pglite.dev) - PostgreSQL WASM
-- [@electric-sql/pglite-socket](https://www.npmjs.com/package/@electric-sql/pglite-socket) - Wire protocol server
+```bash
+# Sync all databases
+pgserve --sync-to "postgresql://user:pass@db.example.com:5432/mydb"
 
-## 📧 Support
+# Sync specific databases (supports wildcards)
+pgserve --sync-to "postgresql://..." --sync-databases "myapp,tenant_*"
+```
 
-- **Issues**: [GitHub Issues](https://github.com/namastexlabs/pgserve/issues)
-- **Email**: labs@namastex.com
-- **Website**: [namastex.com](https://namastex.com)
+> Replication is handled by PostgreSQL's WAL writer process, completely off the Node.js event loop. Sync failures don't affect main server operation.
+
+<br>
+
+## Performance
+
+<table>
+  <tr>
+    <th>Scenario</th>
+    <th>SQLite</th>
+    <th>PGlite</th>
+    <th>Docker PG</th>
+    <th>pgserve</th>
+  </tr>
+  <tr>
+    <td><b>Concurrent Writes</b> (10 agents)</td>
+    <td>100 qps</td>
+    <td>219 qps</td>
+    <td>758 qps</td>
+    <td><b>855 qps 🏆</b></td>
+  </tr>
+  <tr>
+    <td><b>Mixed Workload</b> (messages)</td>
+    <td>335 qps</td>
+    <td>506 qps</td>
+    <td>940 qps</td>
+    <td><b>1034 qps 🏆</b></td>
+  </tr>
+  <tr>
+    <td><b>Write Lock</b> (50 writers)</td>
+    <td>98 qps</td>
+    <td>201 qps</td>
+    <td><b>478 qps 🏆</b></td>
+    <td>391 qps</td>
+  </tr>
+</table>
+
+> pgserve beats Docker PostgreSQL in 2/3 scenarios. For development, CI/CD, and ephemeral deployments — better-than-Docker performance without Docker.
+>
+> Run benchmarks: `npm run bench`
+
+<br>
+
+## Use Cases
+
+<table>
+  <tr>
+    <td width="50%">
+      <h4>Development & Testing</h4>
+      <ul>
+        <li><b>Local Development</b> — PostgreSQL without Docker</li>
+        <li><b>Integration Testing</b> — Real PostgreSQL, not mocks</li>
+        <li><b>CI/CD Pipelines</b> — Fresh databases per test run</li>
+        <li><b>E2E Testing</b> — Isolated database for Playwright/Cypress</li>
+      </ul>
+    </td>
+    <td width="50%">
+      <h4>AI & Agents</h4>
+      <ul>
+        <li><b>AI Agent Memory</b> — Isolated, concurrent-safe database</li>
+        <li><b>LLM Tool Use</b> — Give AI models a real PostgreSQL</li>
+        <li><b>RAG Applications</b> — Store embeddings with pgvector</li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%">
+      <h4>Multi-Tenant & SaaS</h4>
+      <ul>
+        <li><b>Tenant Isolation</b> — Auto-provision per tenant</li>
+        <li><b>Demo Environments</b> — Instant sandboxed PostgreSQL</li>
+        <li><b>Microservices Dev</b> — Each service gets its own DB</li>
+      </ul>
+    </td>
+    <td width="50%">
+      <h4>Edge & Embedded</h4>
+      <ul>
+        <li><b>IoT Devices</b> — Full PostgreSQL on Raspberry Pi</li>
+        <li><b>Desktop Apps</b> — Electron with embedded PostgreSQL</li>
+        <li><b>Offline-First</b> — Local DB that syncs when online</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+<br>
+
+## Requirements
+
+- **Node.js** >= 18.0.0
+- **Platform**: Linux x64, macOS ARM64/x64, Windows x64
+
+<br>
+
+## Contributing
+
+Contributions welcome! Fork the repo, create a feature branch, add tests, and submit a PR.
+
+<br>
 
 ---
 
-**Made with ❤️ by [Namastex Labs](https://namastex.com)**
+<div align="center">
+  <p>
+    <b>MIT License</b> — Copyright (c) 2025 Namastex Labs
+  </p>
+  <p>
+    <a href="https://github.com/namastexlabs/pgserve">GitHub</a> •
+    <a href="https://www.npmjs.com/package/pgserve">npm</a> •
+    <a href="https://github.com/namastexlabs/pgserve/issues">Issues</a>
+  </p>
+  <p>
+    Made with love by <a href="https://namastex.ai">Namastex Labs</a>
+  </p>
+</div>