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.
Node.js 18+ required. PostgreSQL emulator uses
@electric-sql/pglite (WebAssembly) which requires the Web Crypto API available in Node 18+.
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
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Whether to start this service on lds start |
port | number | varies | TCP port. Must not conflict with other services or running databases. |
persistence | boolean | false | Persist data to disk. Requires data_dir. |
data_dir | string | n/a | Directory for persistent data. Created automatically if missing. |
password | string | "" | Empty string = no authentication required. |
databases | string[] | ["postgres"] | PostgreSQL only. List of database names to initialise. |
Tip: Commit
localdb-simulator.yaml to your repo so the whole team uses the same ports and database names. Add .localdb/ to .gitignore.