pgserve 1.0.1 → 1.0.4

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+pnpm exec lint-staged
+pnpm deadcode

package/bin/pglite-server.js

@@ -16,7 +16,7 @@ import { startClusterServer } from '../src/cluster.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 // Global error handlers
-process.on('unhandledRejection', (reason, promise) => {
+process.on('unhandledRejection', (reason, _promise) => {
   console.error('Unhandled Promise Rejection:', reason);
 });
 
@@ -158,6 +158,7 @@ function parseArgs() {
       case 'help':
         printHelp();
         process.exit(0);
+        // falls through (unreachable - exit above)
 
       default:
         if (arg.startsWith('-')) {

package/eslint.config.js

@@ -0,0 +1,54 @@
+import unusedImports from 'eslint-plugin-unused-imports';
+
+export default [
+  {
+    files: ['src/**/*.js', 'bin/**/*.js', 'tests/**/*.js'],
+    plugins: {
+      'unused-imports': unusedImports,
+    },
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        URL: 'readonly',
+        __dirname: 'readonly',
+      },
+    },
+    rules: {
+      // Dead imports - ERROR
+      'unused-imports/no-unused-imports': 'error',
+      'unused-imports/no-unused-vars': [
+        'error',
+        {
+          vars: 'all',
+          varsIgnorePattern: '^_',
+          args: 'after-used',
+          argsIgnorePattern: '^_',
+        },
+      ],
+
+      // Code quality
+      'no-unused-vars': 'off', // Handled by unused-imports
+      'no-console': 'off', // We use console in CLI
+      'no-undef': 'error',
+      'no-unreachable': 'error',
+      'no-constant-condition': 'warn',
+      'no-empty': 'warn',
+      'no-duplicate-case': 'error',
+      'no-fallthrough': 'warn',
+      'eqeqeq': ['warn', 'always', { null: 'ignore' }],
+      'no-var': 'error',
+      'prefer-const': 'warn',
+    },
+  },
+  {
+    ignores: ['node_modules/', 'data/', 'test-data-*/', '.genie/'],
+  },
+];

package/knip.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": ["src/index.js", "bin/pglite-server.js"],
+  "project": ["src/**/*.js", "bin/**/*.js"],
+  "ignore": ["tests/**", "helpers/**", "scripts/**"],
+  "ignoreDependencies": ["pino-pretty"],
+  "ignoreBinaries": ["scripts/test-npx.sh"],
+  "ignoreExportsUsedInFile": true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgserve",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Embedded PostgreSQL server with true concurrent connections - zero config, auto-provision databases",
   "main": "src/index.js",
   "type": "module",
@@ -9,7 +9,13 @@
   },
   "scripts": {
     "bench": "node tests/benchmarks/runner.js",
-    "test": "node --test tests/**/*.test.js"
+    "test": "node --test tests/**/*.test.js",
+    "lint": "eslint src/ bin/",
+    "lint:fix": "eslint src/ bin/ --fix",
+    "deadcode": "knip",
+    "test:npx": "scripts/test-npx.sh",
+    "prepublishOnly": "npm run lint && npm run deadcode && npm run test:npx",
+    "prepare": "husky"
   },
   "keywords": [
     "postgresql",
@@ -31,20 +37,34 @@
   "homepage": "https://github.com/namastexlabs/pgserve#readme",
   "dependencies": {
     "pg": "^8.16.3",
+    "pg-copy-streams": "^7.0.0",
     "pino": "^10.1.0",
     "pino-pretty": "^13.1.2"
   },
   "optionalDependencies": {
-    "@embedded-postgres/linux-x64": "17.7.0-beta.15",
     "@embedded-postgres/darwin-arm64": "17.7.0-beta.15",
     "@embedded-postgres/darwin-x64": "17.7.0-beta.15",
+    "@embedded-postgres/linux-x64": "17.7.0-beta.15",
     "@embedded-postgres/win32-x64": "17.7.0-beta.15"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.2.17",
     "better-sqlite3": "^11.7.0",
-    "@electric-sql/pglite": "^0.2.17"
+    "eslint": "^9.39.1",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "husky": "^9.1.7",
+    "knip": "^5.71.0",
+    "lint-staged": "^16.2.7"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "lint-staged": {
+    "src/**/*.js": [
+      "eslint --fix"
+    ],
+    "bin/**/*.js": [
+      "eslint --fix"
+    ]
   }
 }

package/scripts/test-npx.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Test that the package works with npx (simulates fresh install)
+# This catches path resolution issues that static analysis can't detect
+
+set -e
+
+echo "=== Testing npx compatibility ==="
+
+# Create temp directory
+TEST_DIR=$(mktemp -d)
+trap "rm -rf $TEST_DIR" EXIT
+
+# Pack the current package
+echo "Packing package..."
+PACK_FILE=$(npm pack --pack-destination "$TEST_DIR" 2>/dev/null | tail -1)
+
+# Extract and install in isolated environment
+echo "Installing in isolated environment..."
+cd "$TEST_DIR"
+npm init -y > /dev/null 2>&1
+npm install "$PACK_FILE" > /dev/null 2>&1
+
+# Test that it starts (with timeout)
+echo "Testing server startup..."
+timeout 8 npx pgserve --no-cluster --port 15432 > output.log 2>&1 &
+PID=$!
+
+# Wait for ready signal
+for i in {1..20}; do
+  if grep -q "READY" output.log 2>/dev/null; then
+    echo "✓ Server started successfully"
+    kill $PID 2>/dev/null || true
+    wait $PID 2>/dev/null || true
+    echo "=== npx test PASSED ==="
+    exit 0
+  fi
+  if ! kill -0 $PID 2>/dev/null; then
+    echo "✗ Server exited unexpectedly"
+    cat output.log
+    echo "=== npx test FAILED ==="
+    exit 1
+  fi
+  sleep 0.5
+done
+
+# Timeout
+kill $PID 2>/dev/null || true
+echo "✗ Server did not start within timeout"
+cat output.log
+echo "=== npx test FAILED ==="
+exit 1

package/src/cluster.js

@@ -77,7 +77,7 @@ class ClusterRouter extends EventEmitter {
       await this.adminClient.connect();
     }
 
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve, _reject) => {
       this.server = net.createServer({
         allowHalfOpen: false,
         pauseOnConnect: true
@@ -318,5 +318,3 @@ export async function startClusterServer(options = {}) {
     return router;
   }
 }
-
-export default startClusterServer;

package/src/dashboard.js

@@ -0,0 +1,211 @@
+/**
+ * Dashboard - Informative CLI startup display
+ *
+ * Hybrid approach:
+ * - Scrolling stages (preserved history)
+ * - In-place progress updates (only during restore)
+ * - Non-TTY fallback (works in pipes/CI)
+ *
+ * Zero external dependencies - pure Node.js ANSI codes
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// Get package version
+let version = '1.0.0';
+try {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  version = pkg.version;
+} catch {
+  // Fallback version
+}
+
+// ANSI escape codes
+const ANSI = {
+  CLEAR_LINE: '\x1B[2K',
+  MOVE_UP: (n) => `\x1B[${n}A`,
+  MOVE_DOWN: (n) => `\x1B[${n}B`,
+  HIDE_CURSOR: '\x1B[?25l',
+  SHOW_CURSOR: '\x1B[?25h',
+  GREEN: '\x1B[32m',
+  YELLOW: '\x1B[33m',
+  CYAN: '\x1B[36m',
+  DIM: '\x1B[2m',
+  RESET: '\x1B[0m',
+  BOLD: '\x1B[1m'
+};
+
+/**
+ * Dashboard class for CLI output
+ */
+export class Dashboard {
+  constructor(options = {}) {
+    this.enabled = process.stdout.isTTY && !process.env.NO_COLOR;
+    this.updateInterval = options.updateInterval || 200; // Throttle updates
+    this.lastUpdate = 0;
+    this.progressLines = 0; // Track lines to overwrite
+    this.restoreStartTime = 0;
+    this.config = options.config || {};
+  }
+
+  /**
+   * Show the startup header
+   */
+  showHeader(config = {}) {
+    const mode = config.memoryMode ? 'In-memory' : 'Persistent';
+    const port = config.port || 5432;
+    const host = config.host || '127.0.0.1';
+    const syncTo = config.syncTo ? ` → ${this._maskUrl(config.syncTo)}` : '';
+
+    console.log('');
+    console.log(`${ANSI.BOLD}pgserve v${version}${ANSI.RESET} - Embedded PostgreSQL Server`);
+    console.log(`${ANSI.DIM}MODE: ${mode}  |  PORT: ${port}  |  HOST: ${host}${syncTo}${ANSI.RESET}`);
+    console.log('');
+  }
+
+  /**
+   * Log a stage completion
+   */
+  stage(name, status = 'done') {
+    const icon = status === 'done' ? `${ANSI.GREEN}[✓]${ANSI.RESET}` :
+                 status === 'error' ? `${ANSI.YELLOW}[✗]${ANSI.RESET}` :
+                 `${ANSI.DIM}[○]${ANSI.RESET}`;
+    console.log(`${icon} ${name}`);
+  }
+
+  /**
+   * Start restore progress section
+   */
+  startRestore(totalDatabases, totalTables = 0, totalBytes = 0) {
+    this.restoreStartTime = Date.now();
+    this.totalDatabases = totalDatabases;
+    this.totalTables = totalTables || totalDatabases * 10; // Estimate
+    this.totalBytes = totalBytes;
+
+    console.log('');
+    console.log(`${ANSI.CYAN}Restoring from external PostgreSQL...${ANSI.RESET}`);
+
+    if (this.enabled) {
+      // Reserve lines for progress
+      console.log('  Databases:  0/0   [░░░░░░░░░░░░░░░░]   0%');
+      console.log('  Tables:     0/0   [░░░░░░░░░░░░░░░░]   0%');
+      console.log('  Speed:      0.0 MB/s  |  ETA: calculating...');
+      this.progressLines = 3;
+      process.stdout.write(ANSI.HIDE_CURSOR);
+    }
+  }
+
+  /**
+   * Update restore progress (in-place)
+   */
+  updateRestore(metrics) {
+    if (!this.enabled) return;
+
+    // Throttle updates
+    const now = Date.now();
+    if (now - this.lastUpdate < this.updateInterval) return;
+    this.lastUpdate = now;
+
+    const {
+      databasesRestored = 0,
+      totalDatabases = this.totalDatabases || 1,
+      tablesRestored = 0,
+      totalTables = this.totalTables || 1,
+      bytesTransferred = 0
+    } = metrics;
+
+    // Calculate throughput and ETA
+    const elapsed = (now - this.restoreStartTime) / 1000;
+    const throughputMBps = elapsed > 0 ? (bytesTransferred / 1024 / 1024) / elapsed : 0;
+    const bytesRemaining = this.totalBytes - bytesTransferred;
+    const eta = throughputMBps > 0 ? Math.ceil(bytesRemaining / (throughputMBps * 1024 * 1024)) : 0;
+
+    // Format progress
+    const dbPct = Math.round((databasesRestored / totalDatabases) * 100);
+    const tablePct = Math.round((tablesRestored / totalTables) * 100);
+    const dbBar = this._progressBar(databasesRestored, totalDatabases);
+    const tableBar = this._progressBar(tablesRestored, totalTables);
+    const etaStr = eta > 0 ? `~${eta}s` : 'finishing...';
+
+    // Move up and overwrite
+    process.stdout.write(ANSI.MOVE_UP(this.progressLines));
+
+    process.stdout.write(ANSI.CLEAR_LINE);
+    console.log(`  Databases:  ${String(databasesRestored).padStart(2)}/${totalDatabases}   ${dbBar}  ${String(dbPct).padStart(3)}%`);
+
+    process.stdout.write(ANSI.CLEAR_LINE);
+    console.log(`  Tables:     ${String(tablesRestored).padStart(3)}/${totalTables}  ${tableBar}  ${String(tablePct).padStart(3)}%`);
+
+    process.stdout.write(ANSI.CLEAR_LINE);
+    console.log(`  Speed:      ${throughputMBps.toFixed(1)} MB/s  |  ETA: ${etaStr}`);
+  }
+
+  /**
+   * Complete restore progress (replace with summary)
+   */
+  completeRestore(metrics) {
+    if (this.enabled && this.progressLines > 0) {
+      // Move up and clear progress lines
+      process.stdout.write(ANSI.MOVE_UP(this.progressLines));
+      for (let i = 0; i < this.progressLines; i++) {
+        process.stdout.write(ANSI.CLEAR_LINE + '\n');
+      }
+      process.stdout.write(ANSI.MOVE_UP(this.progressLines));
+      process.stdout.write(ANSI.SHOW_CURSOR);
+      this.progressLines = 0;
+    }
+
+    const duration = ((metrics.endTime || Date.now()) - this.restoreStartTime) / 1000;
+    const mb = (metrics.bytesTransferred / 1024 / 1024).toFixed(1);
+
+    console.log(`${ANSI.GREEN}[✓]${ANSI.RESET} Restored ${metrics.databasesRestored} database${metrics.databasesRestored !== 1 ? 's' : ''} (${mb} MB in ${duration.toFixed(1)}s)`);
+    console.log('');
+  }
+
+  /**
+   * Show final ready message
+   */
+  showReady(config = {}) {
+    const port = config.port || 5432;
+    const host = config.host || '127.0.0.1';
+
+    console.log('');
+    console.log(`${ANSI.GREEN}${ANSI.BOLD}✨ READY${ANSI.RESET}: postgresql://${host}:${port}/<database>`);
+    console.log(`${ANSI.DIM}Press Ctrl+C to stop${ANSI.RESET}`);
+    console.log('');
+  }
+
+  /**
+   * Generate progress bar
+   */
+  _progressBar(current, total, width = 16) {
+    const pct = total > 0 ? current / total : 0;
+    const filled = Math.round(pct * width);
+    const empty = width - filled;
+    return '[' + '█'.repeat(filled) + '░'.repeat(empty) + ']';
+  }
+
+  /**
+   * Mask sensitive URL parts
+   */
+  _maskUrl(url) {
+    try {
+      const u = new URL(url);
+      return `${u.protocol}//${u.host}/${u.pathname.split('/')[1] || ''}`;
+    } catch {
+      return url.replace(/:[^:@]+@/, ':***@');
+    }
+  }
+
+  /**
+   * Cleanup (show cursor if hidden)
+   */
+  cleanup() {
+    if (this.enabled) {
+      process.stdout.write(ANSI.SHOW_CURSOR);
+    }
+  }
+}

package/src/index.js

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

package/src/postgres.js

@@ -18,7 +18,6 @@ import os from 'os';
 import path from 'path';
 import fs from 'fs';
 import crypto from 'crypto';
-import net from 'net';
 
 // Resolve binary paths from embedded-postgres platform packages
 function getBinaryPaths() {
@@ -38,10 +37,12 @@ function getBinaryPaths() {
     throw new Error(`Unsupported platform: ${platform}-${arch}`);
   }
 
-  // Find the package in node_modules
+  // Find the package in node_modules (check multiple locations for npx/pnpm/npm compatibility)
   const possiblePaths = [
     path.join(process.cwd(), 'node_modules', pkgName, 'native', 'bin'),
     path.join(import.meta.dirname, '..', 'node_modules', pkgName, 'native', 'bin'),
+    path.join(import.meta.dirname, '..', '..', pkgName, 'native', 'bin'), // Hoisted (npx flat structure)
+    path.join(import.meta.dirname, '..', '..', '..', pkgName, 'native', 'bin'), // Extra level for some package managers
   ];
 
   for (const binDir of possiblePaths) {
@@ -187,8 +188,8 @@ export class PostgresManager {
         // Clean up password file
         try {
           await fs.promises.unlink(passwordFile);
-        } catch (e) {
-          // Ignore
+        } catch {
+          // Ignore cleanup errors
         }
 
         if (code === 0) {

package/src/protocol.js

@@ -14,7 +14,6 @@ const PROTOCOL_VERSION_3 = 196608;
 const SSL_REQUEST_CODE = 80877103;    // PostgreSQL SSL negotiation request
 const GSSAPI_REQUEST_CODE = 80877104; // PostgreSQL GSSAPI encryption request
 const CANCEL_REQUEST_CODE = 80877102; // PostgreSQL cancel request
-const DATABASE_KEY = Buffer.from('database\0');
 
 /**
  * Parse PostgreSQL startup message to extract connection parameters

package/src/restore.js

@@ -0,0 +1,587 @@
+/**
+ * RestoreManager - Automatic restore from external PostgreSQL on startup
+ *
+ * High-performance restore using:
+ * - Parallel database restore (Promise.all)
+ * - COPY protocol for bulk data transfer (pg-copy-streams)
+ * - Unix sockets for local connections (~30% faster)
+ * - Binary format COPY (~2x faster than text)
+ *
+ * Tech Council Design Principles:
+ * - nayr: Question assumptions, root cause focus
+ * - oettam: Benchmark-driven, measure p99 latency
+ * - jt: Ship simple, delete complexity
+ */
+
+import pg from 'pg';
+import { from as copyFrom, to as copyTo } from 'pg-copy-streams';
+import pino from 'pino';
+
+/**
+ * Match database name against patterns (supports wildcards)
+ * Reused from sync.js for consistency
+ * @param {string} dbName - Database name to check
+ * @param {string[]} patterns - Array of patterns (supports * wildcard)
+ * @returns {boolean}
+ */
+function matchesPattern(dbName, patterns) {
+  if (!patterns || patterns.length === 0) return true; // No filter = restore all
+
+  return patterns.some(pattern => {
+    if (pattern.includes('*')) {
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      return regex.test(dbName);
+    }
+    return dbName === pattern;
+  });
+}
+
+/**
+ * RestoreManager - Handles automatic restore from external PostgreSQL
+ */
+export class RestoreManager {
+  constructor(options = {}) {
+    this.sourceUrl = options.sourceUrl;              // External PostgreSQL URL
+    this.patterns = options.patterns || [];          // Database patterns ["myapp", "tenant_*"]
+    this.targetPort = options.targetPort;            // Local embedded PostgreSQL port
+    this.targetSocketPath = options.targetSocketPath; // Unix socket path (optional)
+
+    this.logger = options.logger || pino({ level: options.logLevel || 'info' }).child({ component: 'restore' });
+
+    // Connection pools (lazy initialized)
+    this.sourcePool = null;
+
+    // Performance tuning - parallel restore limits
+    this.maxParallelDatabases = options.maxParallelDatabases || 4;
+    this.maxParallelTables = options.maxParallelTables || 8;
+
+    // Timeout handling
+    this.restoreTimeout = options.restoreTimeout || 60000; // 60s default
+
+    // Progress callback for dashboard
+    this.onProgress = options.onProgress || (() => {});
+
+    // Totals for progress tracking
+    this.totalDatabases = 0;
+    this.totalTables = 0;
+    this.totalBytes = 0;
+
+    // Metrics collection
+    this.metrics = {
+      startTime: 0,
+      endTime: 0,
+      databasesRestored: 0,
+      tablesRestored: 0,
+      rowsRestored: 0,
+      bytesTransferred: 0,
+      errors: []
+    };
+  }
+
+  /**
+   * Main entry point - restore databases from external PostgreSQL
+   * Called from router.js after pgManager.start(), before SyncManager
+   *
+   * @param {PostgresManager} pgManager - Local PostgreSQL manager
+   * @returns {Promise<Object>} Restore result with metrics
+   */
+  async restore(pgManager) {
+    if (!this.sourceUrl) {
+      return { skipped: true, reason: 'no sourceUrl configured' };
+    }
+
+    this.metrics.startTime = Date.now();
+    this.logger.info({ source: this.sourceUrl.replace(/:[^:@]+@/, ':***@') }, 'Starting automatic restore from external PostgreSQL');
+
+    try {
+      // Initialize connection to external PostgreSQL
+      const connected = await this._initSourcePool();
+      if (!connected) {
+        return { skipped: true, reason: 'external PostgreSQL unreachable' };
+      }
+
+      // Discover databases matching patterns
+      const databases = await this._discoverDatabases();
+
+      if (databases.length === 0) {
+        this.logger.info('No databases found matching sync patterns on external PostgreSQL');
+        return { skipped: true, reason: 'no matching databases found' };
+      }
+
+      this.logger.info({ count: databases.length, databases }, 'Found databases to restore');
+
+      // Set totals for progress tracking
+      this.totalDatabases = databases.length;
+
+      // Restore databases in parallel (with controlled concurrency)
+      await this._restoreDatabasesParallel(databases, pgManager);
+
+      this.metrics.endTime = Date.now();
+      const duration = this.metrics.endTime - this.metrics.startTime;
+
+      this.logger.info({
+        databasesRestored: this.metrics.databasesRestored,
+        tablesRestored: this.metrics.tablesRestored,
+        rowsRestored: this.metrics.rowsRestored,
+        bytesTransferred: this.metrics.bytesTransferred,
+        throughputMBps: ((this.metrics.bytesTransferred / 1024 / 1024) / (duration / 1000)).toFixed(2),
+        durationMs: duration,
+        errors: this.metrics.errors.length
+      }, 'Restore completed');
+
+      return {
+        success: true,
+        metrics: { ...this.metrics }
+      };
+
+    } catch (error) {
+      this.logger.error({ err: error }, 'Restore failed');
+      return { success: false, error: error.message };
+    } finally {
+      await this._closeSourcePool();
+    }
+  }
+
+  /**
+   * Initialize connection pool to external PostgreSQL
+   * @returns {Promise<boolean>} true if connected successfully
+   */
+  async _initSourcePool() {
+    try {
+      this.sourcePool = new pg.Pool({
+        connectionString: this.sourceUrl,
+        max: 3, // Small pool - just for discovery
+        connectionTimeoutMillis: 5000,
+        idleTimeoutMillis: 10000
+      });
+
+      // Test connection
+      await this.sourcePool.query('SELECT 1');
+      this.logger.debug('Connected to external PostgreSQL');
+      return true;
+
+    } catch (error) {
+      if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT' || error.code === 'ENOTFOUND') {
+        this.logger.warn({ err: error.message }, 'External PostgreSQL unreachable, skipping restore');
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Close source connection pool
+   */
+  async _closeSourcePool() {
+    if (this.sourcePool) {
+      await this.sourcePool.end();
+      this.sourcePool = null;
+    }
+  }
+
+  /**
+   * Discover databases on external PostgreSQL matching patterns
+   * @returns {Promise<string[]>} List of database names
+   */
+  async _discoverDatabases() {
+    const result = await this.sourcePool.query(`
+      SELECT datname FROM pg_database
+      WHERE datistemplate = false
+      AND datname NOT IN ('postgres', 'template0', 'template1')
+      ORDER BY datname
+    `);
+
+    // Filter by patterns
+    return result.rows
+      .map(r => r.datname)
+      .filter(name => matchesPattern(name, this.patterns));
+  }
+
+  /**
+   * Restore databases in parallel with controlled concurrency
+   * @param {string[]} databases - Database names to restore
+   * @param {PostgresManager} pgManager - Local PostgreSQL manager
+   */
+  async _restoreDatabasesParallel(databases, pgManager) {
+    // Batch databases to limit concurrency
+    const batches = [];
+    for (let i = 0; i < databases.length; i += this.maxParallelDatabases) {
+      batches.push(databases.slice(i, i + this.maxParallelDatabases));
+    }
+
+    for (const batch of batches) {
+      const results = await Promise.allSettled(
+        batch.map(dbName => this._restoreDatabase(dbName, pgManager))
+      );
+
+      // Track failures but continue
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === 'rejected') {
+          this.metrics.errors.push({
+            database: batch[i],
+            error: results[i].reason.message
+          });
+        }
+      }
+    }
+
+    if (this.metrics.errors.length > 0) {
+      this.logger.warn({
+        failedCount: this.metrics.errors.length,
+        totalCount: databases.length
+      }, 'Some databases failed to restore');
+    }
+  }
+
+  /**
+   * Restore a single database: create DB, schema, data
+   * @param {string} dbName - Database name
+   * @param {PostgresManager} pgManager - Local PostgreSQL manager
+   */
+  async _restoreDatabase(dbName, pgManager) {
+    this.logger.info({ dbName }, 'Restoring database');
+    const startTime = Date.now();
+
+    // Step 1: Create database locally
+    await pgManager.createDatabase(dbName);
+
+    // Step 2: Create connection pools for this specific database
+    const sourceDbPool = await this._createSourceDbPool(dbName);
+    const targetDbPool = await this._createTargetDbPool(dbName);
+
+    try {
+      // Step 3: Restore schema (types, tables, indexes, FKs)
+      await this._restoreSchema(sourceDbPool, targetDbPool, dbName);
+
+      // Step 4: Discover tables and copy data in parallel
+      const tables = await this._discoverTables(sourceDbPool);
+      this.totalTables += tables.length; // Track total for progress
+      if (tables.length > 0) {
+        await this._restoreTablesParallel(sourceDbPool, targetDbPool, tables);
+      }
+
+      // Step 5: Restore sequences (after data for correct values)
+      await this._restoreSequences(sourceDbPool, targetDbPool);
+
+      this.metrics.databasesRestored++;
+      const duration = Date.now() - startTime;
+      this.logger.info({ dbName, durationMs: duration }, 'Database restored successfully');
+
+    } finally {
+      await sourceDbPool.end();
+      await targetDbPool.end();
+    }
+  }
+
+  /**
+   * Create connection pool to specific database on external PostgreSQL
+   * @param {string} dbName - Database name
+   * @returns {Promise<pg.Pool>}
+   */
+  async _createSourceDbPool(dbName) {
+    const url = new URL(this.sourceUrl);
+    url.pathname = `/${dbName}`;
+
+    const pool = new pg.Pool({
+      connectionString: url.toString(),
+      max: this.maxParallelTables,
+      connectionTimeoutMillis: 5000,
+      idleTimeoutMillis: 10000
+    });
+
+    return pool;
+  }
+
+  /**
+   * Create connection pool to specific database on local embedded PostgreSQL
+   * Uses Unix socket when available for ~30% faster connections
+   * @param {string} dbName - Database name
+   * @returns {Promise<pg.Pool>}
+   */
+  async _createTargetDbPool(dbName) {
+    const config = {
+      database: dbName,
+      user: 'postgres',
+      password: 'postgres',
+      max: this.maxParallelTables,
+      connectionTimeoutMillis: 5000,
+      idleTimeoutMillis: 10000
+    };
+
+    // Prefer Unix socket for faster local connections
+    if (this.targetSocketPath) {
+      config.host = this.targetSocketPath.replace(/\/\.s\.PGSQL\.\d+$/, '');
+      config.port = this.targetPort;
+    } else {
+      config.host = '127.0.0.1';
+      config.port = this.targetPort;
+    }
+
+    return new pg.Pool(config);
+  }
+
+  /**
+   * Restore schema: ENUMs, tables, indexes, foreign keys
+   * Order matters: types → tables → indexes → FKs
+   * @param {pg.Pool} sourcePool - External database pool
+   * @param {pg.Pool} targetPool - Local database pool
+   * @param {string} dbName - Database name (for logging)
+   */
+  async _restoreSchema(sourcePool, targetPool, dbName) {
+    // 1. Restore ENUM types
+    await this._restoreEnums(sourcePool, targetPool);
+
+    // 2. Restore tables (structure only, no data yet)
+    await this._restoreTables(sourcePool, targetPool);
+
+    this.logger.debug({ dbName }, 'Schema restored');
+  }
+
+  /**
+   * Restore ENUM types from external database
+   */
+  async _restoreEnums(sourcePool, targetPool) {
+    const result = await sourcePool.query(`
+      SELECT n.nspname as schema, t.typname as name,
+             array_agg(e.enumlabel ORDER BY e.enumsortorder) as values
+      FROM pg_type t
+      JOIN pg_enum e ON t.oid = e.enumtypid
+      JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+      WHERE n.nspname = 'public'
+      GROUP BY n.nspname, t.typname
+    `);
+
+    for (const enumType of result.rows) {
+      const values = enumType.values.map(v => `'${v.replace(/'/g, "''")}'`).join(', ');
+      const createSql = `CREATE TYPE "${enumType.name}" AS ENUM (${values})`;
+
+      try {
+        await targetPool.query(createSql);
+      } catch (err) {
+        if (err.code !== '42710') throw err; // 42710 = type already exists
+      }
+    }
+  }
+
+  /**
+   * Restore table structures from external database
+   */
+  async _restoreTables(sourcePool, targetPool) {
+    // Get table list
+    const tablesResult = await sourcePool.query(`
+      SELECT table_name FROM information_schema.tables
+      WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+      ORDER BY table_name
+    `);
+
+    for (const row of tablesResult.rows) {
+      const tableName = row.table_name;
+      const createSql = await this._getTableCreateStatement(sourcePool, tableName);
+
+      try {
+        await targetPool.query(createSql);
+      } catch (err) {
+        if (err.code !== '42P07') throw err; // 42P07 = table already exists
+      }
+    }
+  }
+
+  /**
+   * Generate CREATE TABLE statement from information_schema
+   * @param {pg.Pool} sourcePool - Source database pool
+   * @param {string} tableName - Table name
+   * @returns {Promise<string>} CREATE TABLE SQL
+   */
+  async _getTableCreateStatement(sourcePool, tableName) {
+    // Get columns
+    const columnsResult = await sourcePool.query(`
+      SELECT column_name, data_type, udt_name, character_maximum_length,
+             column_default, is_nullable, numeric_precision, numeric_scale
+      FROM information_schema.columns
+      WHERE table_schema = 'public' AND table_name = $1
+      ORDER BY ordinal_position
+    `, [tableName]);
+
+    const columns = columnsResult.rows.map(col => {
+      let type = col.data_type;
+
+      // Handle special types
+      if (type === 'USER-DEFINED') {
+        type = `"${col.udt_name}"`; // ENUM or custom type
+      } else if (type === 'character varying' && col.character_maximum_length) {
+        type = `varchar(${col.character_maximum_length})`;
+      } else if (type === 'character' && col.character_maximum_length) {
+        type = `char(${col.character_maximum_length})`;
+      } else if (type === 'numeric' && col.numeric_precision) {
+        type = col.numeric_scale
+          ? `numeric(${col.numeric_precision},${col.numeric_scale})`
+          : `numeric(${col.numeric_precision})`;
+      } else if (type === 'ARRAY') {
+        type = `${col.udt_name.replace(/^_/, '')}[]`;
+      }
+
+      let colDef = `"${col.column_name}" ${type}`;
+
+      if (col.column_default) {
+        colDef += ` DEFAULT ${col.column_default}`;
+      }
+
+      if (col.is_nullable === 'NO') {
+        colDef += ' NOT NULL';
+      }
+
+      return colDef;
+    });
+
+    // Get primary key
+    const pkResult = await sourcePool.query(`
+      SELECT a.attname
+      FROM pg_index i
+      JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = ANY(i.indkey)
+      WHERE i.indrelid = $1::regclass AND i.indisprimary
+      ORDER BY array_position(i.indkey, a.attnum)
+    `, [tableName]);
+
+    if (pkResult.rows.length > 0) {
+      const pkCols = pkResult.rows.map(r => `"${r.attname}"`).join(', ');
+      columns.push(`PRIMARY KEY (${pkCols})`);
+    }
+
+    return `CREATE TABLE "${tableName}" (\n  ${columns.join(',\n  ')}\n)`;
+  }
+
+  /**
+   * Discover tables in the database
+   * @param {pg.Pool} sourcePool - Source database pool
+   * @returns {Promise<string[]>} Table names
+   */
+  async _discoverTables(sourcePool) {
+    const result = await sourcePool.query(`
+      SELECT table_name FROM information_schema.tables
+      WHERE table_schema = 'public' AND table_type = 'BASE TABLE'
+      ORDER BY table_name
+    `);
+
+    return result.rows.map(r => r.table_name);
+  }
+
+  /**
+   * Restore table data in parallel using COPY protocol
+   * @param {pg.Pool} sourcePool - Source database pool
+   * @param {pg.Pool} targetPool - Target database pool
+   * @param {string[]} tables - Table names
+   */
+  async _restoreTablesParallel(sourcePool, targetPool, tables) {
+    // Batch tables to limit concurrency
+    const batches = [];
+    for (let i = 0; i < tables.length; i += this.maxParallelTables) {
+      batches.push(tables.slice(i, i + this.maxParallelTables));
+    }
+
+    for (const batch of batches) {
+      await Promise.all(
+        batch.map(table => this._copyTableData(sourcePool, targetPool, table))
+      );
+    }
+  }
+
+  /**
+   * Copy table data using binary COPY protocol (high performance)
+   * @param {pg.Pool} sourcePool - Source database pool
+   * @param {pg.Pool} targetPool - Target database pool
+   * @param {string} tableName - Table name
+   */
+  async _copyTableData(sourcePool, targetPool, tableName) {
+    // Get row count first (for metrics)
+    const countResult = await sourcePool.query(
+      `SELECT COUNT(*)::int as count FROM "${tableName}"`
+    );
+    const rowCount = countResult.rows[0].count;
+
+    if (rowCount === 0) {
+      this.logger.debug({ tableName, rows: 0 }, 'Skipping empty table');
+      return;
+    }
+
+    // Stream COPY: source → target
+    const sourceClient = await sourcePool.connect();
+    const targetClient = await targetPool.connect();
+
+    try {
+      const copyToStream = sourceClient.query(
+        copyTo(`COPY "${tableName}" TO STDOUT WITH (FORMAT binary)`)
+      );
+      const copyFromStream = targetClient.query(
+        copyFrom(`COPY "${tableName}" FROM STDIN WITH (FORMAT binary)`)
+      );
+
+      // Track bytes transferred
+      let bytesTransferred = 0;
+
+      await new Promise((resolve, reject) => {
+        copyToStream.on('error', reject);
+        copyFromStream.on('error', reject);
+
+        copyToStream.on('data', chunk => {
+          bytesTransferred += chunk.length;
+          copyFromStream.write(chunk);
+        });
+
+        copyToStream.on('end', () => {
+          copyFromStream.end();
+        });
+
+        copyFromStream.on('finish', () => {
+          this.metrics.bytesTransferred += bytesTransferred;
+          this.metrics.rowsRestored += rowCount;
+          this.metrics.tablesRestored++;
+          resolve();
+        });
+      });
+
+      this.logger.debug({ tableName, rows: rowCount, bytes: bytesTransferred }, 'Table data copied');
+
+      // Emit progress for dashboard
+      this.onProgress({
+        databasesRestored: this.metrics.databasesRestored,
+        totalDatabases: this.totalDatabases,
+        tablesRestored: this.metrics.tablesRestored,
+        totalTables: this.totalTables,
+        bytesTransferred: this.metrics.bytesTransferred,
+        totalBytes: this.totalBytes
+      });
+
+    } finally {
+      sourceClient.release();
+      targetClient.release();
+    }
+  }
+
+  /**
+   * Restore sequences to correct values (after data restore)
+   * @param {pg.Pool} sourcePool - Source database pool
+   * @param {pg.Pool} targetPool - Target database pool
+   */
+  async _restoreSequences(sourcePool, targetPool) {
+    // Get all sequences
+    const seqResult = await sourcePool.query(`
+      SELECT sequence_name FROM information_schema.sequences
+      WHERE sequence_schema = 'public'
+    `);
+
+    for (const seq of seqResult.rows) {
+      const seqName = seq.sequence_name;
+
+      // Get current value from source
+      const valueResult = await sourcePool.query(`SELECT last_value FROM "${seqName}"`);
+      const lastValue = valueResult.rows[0].last_value;
+
+      // Set on target
+      try {
+        await targetPool.query(`SELECT setval($1, $2, true)`, [seqName, lastValue]);
+      } catch (err) {
+        this.logger.warn({ sequence: seqName, err: err.message }, 'Failed to restore sequence');
+      }
+    }
+  }
+}

package/src/router.js

@@ -15,6 +15,8 @@
 import net from 'net';
 import { PostgresManager } from './postgres.js';
 import { SyncManager } from './sync.js';
+import { RestoreManager } from './restore.js';
+import { Dashboard } from './dashboard.js';
 import { extractDatabaseNameFromSocket } from './protocol.js';
 import { EventEmitter } from 'events';
 import pino from 'pino';
@@ -87,8 +89,53 @@ export class MultiTenantRouter extends EventEmitter {
    * Start multi-tenant router
    */
   async start() {
+    // Initialize dashboard for informative CLI output
+    const dashboard = new Dashboard();
+    dashboard.showHeader({
+      port: this.port,
+      host: this.host,
+      memoryMode: this.memoryMode,
+      syncTo: this.syncTo
+    });
+
     // Start PostgreSQL first
+    dashboard.stage('PostgreSQL binaries resolved');
     await this.pgManager.start();
+    dashboard.stage('PostgreSQL started');
+
+    // Automatic restore from external PostgreSQL (if sync configured)
+    // This runs BEFORE SyncManager to restore data before enabling outbound sync
+    if (this.syncTo) {
+      const restoreManager = new RestoreManager({
+        sourceUrl: this.syncTo,
+        patterns: this.syncDatabases,
+        targetPort: this.pgPort,
+        targetSocketPath: this.pgManager.getSocketPath(),
+        logger: this.logger.child({ component: 'restore' }),
+        onProgress: (metrics) => dashboard.updateRestore(metrics)
+      });
+
+      // Start restore progress display
+      dashboard.startRestore(restoreManager.totalDatabases || 1);
+
+      const restoreResult = await restoreManager.restore(this.pgManager);
+
+      if (restoreResult.success) {
+        dashboard.completeRestore(restoreResult.metrics);
+        this.logger.info({
+          databases: restoreResult.metrics.databasesRestored,
+          tables: restoreResult.metrics.tablesRestored,
+          rows: restoreResult.metrics.rowsRestored,
+          bytes: restoreResult.metrics.bytesTransferred,
+          durationMs: restoreResult.metrics.endTime - restoreResult.metrics.startTime
+        }, 'Restored from external PostgreSQL');
+      } else if (restoreResult.skipped) {
+        // No progress to complete - was skipped
+      } else {
+        dashboard.cleanup();
+        this.logger.warn({ error: restoreResult.error }, 'Restore failed (continuing without restored data)');
+      }
+    }
 
     // Initialize SyncManager if configured (async replication)
     if (this.syncTo) {
@@ -105,11 +152,14 @@ export class MultiTenantRouter extends EventEmitter {
 
       // Initialize sync connections (non-blocking, runs in background)
       this.syncManager.initialize(this.pgManager)
-        .then(() => this.logger.info('Sync manager initialized'))
+        .then(() => {
+          dashboard.stage('Sync manager initialized');
+          this.logger.info('Sync manager initialized');
+        })
         .catch(err => this.logger.warn({ err: err.message }, 'Sync manager initialization failed (non-fatal)'));
     }
 
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve, _reject) => {
       // Create TCP server
       this.server = net.createServer({
         allowHalfOpen: false,
@@ -130,6 +180,10 @@ export class MultiTenantRouter extends EventEmitter {
       // Start listening
       this.server.listen(this.port, this.host, () => {
         const socketPath = this.pgManager.getSocketPath();
+
+        dashboard.stage('TCP server listening');
+        dashboard.showReady({ port: this.port, host: this.host });
+
         this.logger.info({
           host: this.host,
           port: this.port,

package/src/sync.js

@@ -46,9 +46,9 @@ export class SyncManager {
 
   /**
    * Initialize the SyncManager after PostgreSQL is ready
-   * @param {Object} pgManager - PostgresManager instance
+   * @param {Object} _pgManager - PostgresManager instance (unused, reserved for future)
    */
-  async initialize(pgManager) {
+  async initialize(_pgManager) {
     if (!this.targetUrl) {
       throw new Error('SyncManager requires targetUrl');
     }
@@ -340,5 +340,3 @@ export class SyncManager {
     this.logger.info('Sync manager stopped');
   }
 }
-
-export default SyncManager;