Installation

LocalDB Simulator requires Node.js 18+ and pnpm / npm / yarn. No other system dependencies needed.

# Install globally (recommended)
$ npm install -g localdb-simulator

# Verify installation
$ lds --version
0.1.0

$ lds --help

Two binary names are registered: lds (shorthand) and localdb-simulator (full name). Both point to the same entry point.

Quick Start

1. Create a config file

Run lds init in your project directory to generate a localdb-simulator.yaml:

$ cd my-project
$ lds init
✔ Created localdb-simulator.yaml

2. Start services

$ lds start
✔ redis     running  127.0.0.1:6379
✔ postgres  running  127.0.0.1:5432
◆ Dashboard http://127.0.0.1:8080

3. Copy connection strings

Click the Copy .env button in the dashboard, or use the connection strings below in your application:

# .env
REDIS_URL=redis://127.0.0.1:6379
DATABASE_URL=postgresql://postgres@127.0.0.1:5432/myapp_dev
MONGODB_URI=mongodb://127.0.0.1:27017/myapp_dev

4. Stop when done

$ lds stop
✔ redis stopped
✔ postgres stopped
✔ mongodb stopped

Configuration

LocalDB Simulator is configured via a localdb-simulator.yaml file in your project root. All changes require a service restart to take effect.

Full config reference

version: "1"

services:

  # ── Redis ────────────────────────────────────────
  redis:
    enabled: true          # enable/disable this service
    port: 6379            # TCP port to bind (127.0.0.1 only)
    persistence: false   # true → snapshot to disk every 5s
    data_dir: ./.localdb/redis  # required when persistence: true
    password: ""          # empty = no auth (NOAUTH)
    max_memory_mb: 0     # 0 = unlimited; >0 → OOM guard

  # ── PostgreSQL ───────────────────────────────────
  postgres:
    enabled: true
    port: 5432
    persistence: true
    data_dir: ./.localdb/postgres
    databases:           # list of database names to create
      - myapp_dev
      - myapp_test
    user: postgres       # superuser name
    password: ""         # empty = trust mode (no password)

dashboard:
  port: 8080            # web dashboard port
  open_on_start: true  # auto-open browser

Config options reference

CLI Reference

All commands are available as both lds <command> and localdb-simulator <command>.

If the server is not running when you run any command, the CLI starts it automatically in the background.

# Start all services defined in localdb-simulator.yaml
$ lds start

# Start only Redis
$ lds start redis

# Start only PostgreSQL
$ lds start postgres

$ lds stop          # stop everything + server
$ lds stop redis    # stop only Redis, keep server running

$ lds status
  NAME      STATUS   PORT   UPTIME   MEMORY
  redis     running  6379   2m 14s   4.2 MB
  postgres  running  5432   2m 14s   38.1 MB

$ lds logs redis
$ lds logs postgres
$ lds logs redis --tail 200   # show last 200 lines, then stream

$ lds restart
$ lds restart redis

$ lds init
✔ Created localdb-simulator.yaml

Exit codes

Redis Emulator Ready

The Redis emulator implements the full RESP (REdis Serialization Protocol) over TCP. It is wire-compatible with ioredis, redis (node-redis), and any other RESP client.

Connection

// ioredis
import Redis from 'ioredis';
const redis = new Redis('redis://127.0.0.1:6379');

// With password
const redis = new Redis('redis://:mypassword@127.0.0.1:6379');

// node-redis
import { createClient } from 'redis';
const client = createClient({ url: 'redis://127.0.0.1:6379' });
await client.connect();

Supported commands

Persistence

Enable persistence in config to snapshot data to LevelDB every 5 seconds:

redis:
  persistence: true
  data_dir: ./.localdb/redis

PostgreSQL Emulator Ready

Powered by pglite — a WebAssembly build of real PostgreSQL 16 embedded in Node.js. Clients connect via the standard PostgreSQL wire protocol; no special drivers needed.

Connection

// node-postgres (pg)
import { Pool } from 'pg';
const pool = new Pool({
  host: '127.0.0.1',
  port: 5432,
  database: 'myapp_dev',
  user: 'postgres',
});

// With connection string
const pool = new Pool({
  connectionString: 'postgresql://postgres@127.0.0.1:5432/myapp_dev'
});

// Prisma — datasource in schema.prisma
// datasource db {
//   provider = "postgresql"
//   url      = env("DATABASE_URL")
// }
// DATABASE_URL=postgresql://postgres@127.0.0.1:5432/myapp_dev

Multi-database support

Define multiple databases in config. Each database is a separate pglite instance:

postgres:
  enabled: true
  databases:
    - myapp_dev
    - myapp_test    # isolated DB for tests
    - analytics

Authentication

Supported features

• ✓ DDL: CREATE/DROP TABLE, INDEX, SCHEMA, SEQUENCE
• ✓ DML: SELECT, INSERT, UPDATE, DELETE with WHERE, JOIN, GROUP BY, ORDER BY
• ✓ Transactions: BEGIN / COMMIT / ROLLBACK
• ✓ Extended query protocol (prepared statements, parameterised queries)
• ✓ Data types: JSONB, BOOLEAN, TIMESTAMPTZ, UUID, ARRAY, NUMERIC
• ✓ Functions, aggregates, CTEs, window functions

SQLite Emulator Coming in Phase 3

SQLite is an embedded database — it has no client-server wire protocol. The SQLite emulator manages .db files and exposes data through the dashboard's data browser. Clients access the file directly using better-sqlite3.

Planned config

sqlite:
  enabled: true
  data_dir: ./.localdb/sqlite
  databases:
    - myapp_dev

MongoDB Emulator Ready

Powered by mongodb-memory-server, which downloads the official mongod binary for your platform on first run (~77 MB, cached in ~/.cache/mongodb-binaries). 100% wire-compatible — use the standard mongodb driver without modification.

Connecting

// Official mongodb driver (Node.js)
import { MongoClient } from 'mongodb';

const client = new MongoClient('mongodb://127.0.0.1:27017');
await client.connect();
const db = client.db('myapp_dev');

// Mongoose
await mongoose.connect('mongodb://127.0.0.1:27017/myapp_dev');

# .env
MONGODB_URI=mongodb://127.0.0.1:27017/myapp_dev

Configuration

mongodb:
  enabled: true
  port: 27017
  persistence: false        # true → WiredTiger engine, data survives restart
  data_dir: ./.localdb/mongodb  # required when persistence: true
  databases:
    - myapp_dev
    - myapp_test

Supported features

• ✓ Full CRUD: insertOne/Many, findOne/find, updateOne/Many, deleteOne/Many, replaceOne
• ✓ Aggregation pipeline ($match, $group, $sort, $project, $lookup, …)
• ✓ Indexes: createIndex, unique indexes, compound indexes
• ✓ Multi-database — data is fully isolated between databases
• ✓ Persistence — WiredTiger storage engine, data survives restarts
• ✓ Mongoose, Prisma, and any driver that targets the MongoDB wire protocol

Web Dashboard

The dashboard is available at http://127.0.0.1:8080 as soon as lds start runs. It provides real-time visibility into your local services.

Service cards

Each service has a card showing:

• • Status badge (running / stopped / error) + connection string
• • Live metrics: commands/sec, memory usage, active keys / databases
• • Animated area chart — 60-point rolling window (2 s interval)
• • Persistence badge (💾 persistent / ⚡ ephemeral)
• • Start / Stop / Flush buttons with inline confirmation

Header actions

• • Start All / Stop All — one click for all services
• • Copy .env — copies connection strings for all running services to clipboard
• • Dark mode toggle — persisted in localStorage

Data Browser

The data browser lets you inspect stored data without connecting a client. Available for all running services via the dashboard.

Redis data browser

• • DB selector (0–15) to switch between Redis databases
• • Key table with type badge (string / hash / list / set / zset), TTL, and size
• • Key detail panel — full value display per type (hash fields, list items, set members, sorted set with scores)
• • Pattern filter (supports Redis KEYS glob patterns: user:*, session:?)

PostgreSQL data browser

• • Database selector for multi-database instances
• • Table list with row count
• • Table preview — first 100 rows with column names and types

MongoDB data browser

• • Database selector for configured databases
• • Collection list with live document count
• • Document preview — first 100 documents; BSON ObjectIds shown as hex strings, Dates as ISO strings

Log Panel

Click a service card to open its live log panel. Logs stream in real time over WebSocket.

• • 1 000-line ring buffer — scrollable, colour-coded by level (INFO / WARN / ERROR / DEBUG)
• • Text search with match highlighting
• • Auto-scroll toggle

The same logs are accessible from the CLI: lds logs <service>