pgserve

Embedded PostgreSQL Server with TRUE Concurrent Connections

Zero config, auto-provision databases, unlimited concurrent connections. Just works.

Quick Start • Features • CLI • API • Performance

Quick Start

npx pgserve

Connect from any PostgreSQL client — databases auto-create on first connection:

psql postgresql://localhost:5432/myapp

Features

Unlimited Concurrency	Native PostgreSQL process forking — no connection locks
Zero Config	Just run pgserve, connect to any database name
Auto-Provision	Databases created automatically on first connection
Memory Mode	Fast and ephemeral for development (default)
Persistent Mode	Use --data ./path for durable storage
Async Replication	Sync to real PostgreSQL with zero performance impact
Cross-Platform	Linux x64, macOS ARM64/x64, Windows x64
Any Client Works	psql, node-postgres, Prisma, Drizzle, TypeORM

Installation

# Zero install (recommended)
npx pgserve

# Global install
npm install -g pgserve

# Project dependency
npm install pgserve

PostgreSQL binaries are automatically downloaded on first run.

CLI Reference

pgserve [options]

Options:
  --port <number>       PostgreSQL port (default: 8432)
  --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

Examples

# Development (memory mode, auto-clusters on multi-core)
pgserve

# Persistent storage
pgserve --data /var/lib/pgserve

# Custom port
pgserve --port 5433

# Sync to production PostgreSQL
pgserve --sync-to "postgresql://user:pass@db.example.com:5432/prod"

API

import { startMultiTenantServer } from 'pgserve';

const server = await startMultiTenantServer({
  port: 8432,
  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_*"
});

// Get stats
console.log(server.getStats());

// Graceful shutdown
await server.stop();

Framework Integration

node-postgres

import pg from 'pg';

const client = new pg.Client({
  connectionString: 'postgresql://localhost:5432/myapp'
});

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();

Prisma

// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

# .env
DATABASE_URL="postgresql://localhost:5432/myapp"

# Run migrations
npx prisma migrate dev

Drizzle

import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: 'postgresql://localhost:5432/myapp'
});

const db = drizzle(pool);
const users = await db.select().from(usersTable);

Async Replication

Sync ephemeral pgserve data to a real PostgreSQL database. Uses native logical replication for zero performance impact on the hot path.

# Sync all databases
pgserve --sync-to "postgresql://user:pass@db.example.com:5432/mydb"

# Sync specific databases (supports wildcards)
pgserve --sync-to "postgresql://..." --sync-databases "myapp,tenant_*"

Replication is handled by PostgreSQL's WAL writer process, completely off the Node.js event loop. Sync failures don't affect main server operation.

Performance

Scenario	SQLite	PGlite	Docker PG	pgserve
Concurrent Writes (10 agents)	100 qps	219 qps	758 qps	855 qps 🏆
Mixed Workload (messages)	335 qps	506 qps	940 qps	1034 qps 🏆
Write Lock (50 writers)	98 qps	201 qps	478 qps 🏆	391 qps

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

Use Cases

Development & Testing Local Development — PostgreSQL without Docker Integration Testing — Real PostgreSQL, not mocks CI/CD Pipelines — Fresh databases per test run E2E Testing — Isolated database for Playwright/Cypress	AI & Agents AI Agent Memory — Isolated, concurrent-safe database LLM Tool Use — Give AI models a real PostgreSQL RAG Applications — Store embeddings with pgvector
Multi-Tenant & SaaS Tenant Isolation — Auto-provision per tenant Demo Environments — Instant sandboxed PostgreSQL Microservices Dev — Each service gets its own DB	Edge & Embedded IoT Devices — Full PostgreSQL on Raspberry Pi Desktop Apps — Electron with embedded PostgreSQL Offline-First — Local DB that syncs when online

Requirements

• Node.js >= 18.0.0
• Platform: Linux x64, macOS ARM64/x64, Windows x64

Contributing

Contributions welcome! Fork the repo, create a feature branch, add tests, and submit a PR.

---

MIT License — Copyright (c) 2025 Namastex Labs

GitHub • npm • Issues

Made with love by Namastex Labs