CLI Tool

SpinDB

21 engines · 5 platforms · 0 dependencies

One CLI for all your local databases. Create, manage, backup, and connect to PostgreSQL, MySQL, MongoDB, Redis, and 17 more engines. No Docker required.

View on npm View on GitHub

quick start

# Use without installing
$ pnpx spindb

# PostgreSQL for your API
$ spindb create api-db --start

# MongoDB for analytics
$ spindb create analytics -e mongodb --start

# Redis for caching
$ spindb create cache -e redis --start

# All running, all managed the same way

Prerequisites

Before you start

SpinDB requires a JavaScript runtime and a package manager.

You need Node.js (v18+) or Bun and a package manager. Select yours below and all examples will update automatically.

Package manager

01 / Quick Start

Up and running in seconds

Install SpinDB globally, create a database, and start working. That's it.

install

# Use without installing
$ pnpx spindb

# Install globally
$ pnpm add -g spindb

create & connect

$ spindb create myapp --start --connect
Created PostgreSQL instance "myapp" on port 5432
psql (18.1)
Type "help" for help.

myapp=#

Data persists when stopped unless you explicitly run spindb delete.

02 / How It Works

Native binaries, not containers

SpinDB downloads database binaries and runs them as native processes with isolated data directories. No Docker daemon, no VM overhead.

Direct execution

Native process execution. No containers, no VMs, no daemon running in the background.

Isolated storage

Each database gets its own data directory. No version conflicts, no shared state.

Cross-platform

Same commands on macOS, Linux, and Windows. ARM and x64 supported.

data storage

databases/
├── postgresql/
│   └── myapp/
│       ├── container.json
│       ├── data/
│       ├── credentials/
│       └── postgres.log
├── mysql/
└── mongodb/

03 / Engines

21 databases, one interface

Every engine works the same way. Learn one command set, use them all.

PostgreSQL

Relational SQL

spindb create -e postgresql

MySQL

Relational SQL

spindb create -e mysql

MariaDB

Relational SQL

spindb create -e mariadb

SQLite

Embedded SQL

spindb create -e sqlite

DuckDB

Embedded OLAP

spindb create -e duckdb

MongoDB

Document Store

spindb create -e mongodb

FerretDB

Document Store

spindb create -e ferretdb

Redis

Key-Value

spindb create -e redis

Valkey

Key-Value

spindb create -e valkey

ClickHouse

Columnar OLAP

spindb create -e clickhouse

Qdrant

Vector Search

spindb create -e qdrant

Meilisearch

Full-Text Search

spindb create -e meilisearch

CouchDB

Document Store

spindb create -e couchdb

CockroachDB

Distributed SQL

spindb create -e cockroachdb

SurrealDB

Multi-Model

spindb create -e surrealdb

QuestDB

Time-Series

spindb create -e questdb

TypeDB

Knowledge Graph

spindb create -e typedb

InfluxDB

Time-Series

spindb create -e influxdb

Weaviate

Vector Database

spindb create -e weaviate

TigerBeetle

Financial Ledger

spindb create -e tigerbeetle

Engine	Type	Command
PostgreSQL	Relational SQL	`spindb create -e postgresql`
MySQL	Relational SQL	`spindb create -e mysql`
MariaDB	Relational SQL	`spindb create -e mariadb`
SQLite	Embedded SQL	`spindb create -e sqlite`
DuckDB	Embedded OLAP	`spindb create -e duckdb`
MongoDB	Document Store	`spindb create -e mongodb`
FerretDB	Document Store	`spindb create -e ferretdb`
Redis	Key-Value	`spindb create -e redis`
Valkey	Key-Value	`spindb create -e valkey`
ClickHouse	Columnar OLAP	`spindb create -e clickhouse`
Qdrant	Vector Search	`spindb create -e qdrant`
Meilisearch	Full-Text Search	`spindb create -e meilisearch`
CouchDB	Document Store	`spindb create -e couchdb`
CockroachDB	Distributed SQL	`spindb create -e cockroachdb`
SurrealDB	Multi-Model	`spindb create -e surrealdb`
QuestDB	Time-Series	`spindb create -e questdb`
TypeDB	Knowledge Graph	`spindb create -e typedb`
InfluxDB	Time-Series	`spindb create -e influxdb`
Weaviate	Vector Database	`spindb create -e weaviate`
TigerBeetle	Financial Ledger	`spindb create -e tigerbeetle`

04 / Usage

Basic commands

Create, start, connect, query, backup, and restore. Consistent across every engine.

postgresql

$ spindb create myapp
$ spindb start myapp
$ spindb connect myapp
$ spindb run myapp -c "SELECT version()"
$ spindb run myapp ./schema.sql
$ spindb backup myapp --format sql
$ spindb url myapp --copy

mongodb

$ spindb create logs -e mongodb --start
$ spindb run logs -c "db.users.insertOne({name: 'Alice'})"
$ spindb run logs -c "db.users.find().pretty()"
$ spindb connect logs
$ spindb backup logs --format archive

redis

$ spindb create cache -e redis --start
$ spindb run cache -c "SET mykey myvalue"
$ spindb run cache -c "GET mykey"
$ spindb connect cache
$ spindb connect cache --iredis

any engine

$ spindb create mydb -e [engine] --start
$ spindb connect mydb
$ spindb backup mydb
$ spindb restore mydb backup.dump
$ spindb clone mydb mydb-copy
$ spindb delete mydb -f

05 / Lifecycle

Container management

Full lifecycle control for every database instance.

create & control

$ spindb create mydb -e postgres
$ spindb create mydb -e mysql --db-version 8
$ spindb create mydb --start
$ spindb create mydb --from backup.sql
$ spindb start mydb
$ spindb stop mydb
$ spindb stop --all
$ spindb delete mydb -f

inspect

$ spindb list
$ spindb list --json
$ spindb info mydb
$ spindb ports
$ spindb ports --running
$ spindb logs mydb
$ spindb logs mydb -f
$ spindb logs mydb --editor

06 / Connect & Query

Interactive shells and queries

Native database shells, enhanced TUI clients, and structured query output.

connect

# Native shells
$ spindb connect mydb
$ spindb connect mydb -d analytics

# Enhanced shells
$ spindb connect mydb --pgcli
$ spindb connect mydb --mycli
$ spindb connect mydb --litecli
$ spindb connect mydb --iredis
$ spindb connect mydb --dblab
$ spindb connect mydb --ui

query

# Run inline commands
$ spindb run mydb -c "SELECT 1"
$ spindb run mydb ./schema.sql
$ spindb run mydb -d analytics ./init.sql

# Structured output
$ spindb query mydb "SELECT * FROM users"
$ spindb query mydb "SELECT * FROM users" --json

07 / Data

Backup, restore, clone, and pull

Full data lifecycle management with automatic backups and remote sync.

backup & restore

$ spindb backup mydb
$ spindb backup mydb --format sql
$ spindb backup mydb --format custom
$ spindb backup mydb -o ~/backups
$ spindb backup mydb -d analytics

$ spindb restore mydb ./backup.sql
$ spindb restore mydb --from-url "postgresql://user:pass@host/db"

clone & pull

# Clone locally
$ spindb stop mydb
$ spindb clone mydb mydb-copy
$ spindb start mydb-copy

# Pull from remote (auto-backup before replace)
$ spindb pull mydb --from "postgresql://user:pass@prod/db"
$ spindb pull mydb --from-env PROD_DB_URL
$ spindb pull mydb --from-env PROD_DB_URL --as mydb_prod
$ spindb pull mydb --from-env PROD_DB_URL --dry-run

08 / Remote

Link remote databases

Manage cloud-hosted or external databases through SpinDB. Auto-detects Neon, Supabase, PlanetScale, Upstash, Railway, Aiven, and more.

terminal

$ spindb link "postgresql://user:pass@ep-cool-123.neon.tech/mydb"
$ spindb link "mongodb+srv://user:pass@cluster.mongodb.net/mydb"
$ spindb link "redis://default:pass@us1-cat.upstash.io:6379"

# Custom name
$ spindb link "postgresql://user:pass@host/db" production-pg

# Use linked database
$ spindb connect production-pg
$ spindb url production-pg
$ spindb url production-pg --password

09 / Connection Strings

Auto-generated URLs

Every engine provides a connection string. Copy to clipboard or pipe to your app.

commands

$ spindb url mydb
$ spindb url mydb --copy
$ spindb url mydb -d analytics
$ spindb url mydb --json

# Use in your app
$ export DATABASE_URL=$(spindb url mydb)
$ psql $(spindb url mydb)

PostgreSQL

postgresql://postgres@127.0.0.1:5432/mydb

MySQL

mysql://root@127.0.0.1:3306/mydb

MariaDB

mysql://root@127.0.0.1:3307/mydb

MongoDB

mongodb://127.0.0.1:27017/mydb

Redis

redis://127.0.0.1:6379/0

ClickHouse

clickhouse://default@127.0.0.1:9000/default

CockroachDB

postgresql://root@127.0.0.1:26257/defaultdb

SurrealDB

ws://root:root@127.0.0.1:8000/test/test

QuestDB

postgresql://admin:quest@127.0.0.1:8812/qdb

SQLite

sqlite:///path/to/file.sqlite

DuckDB

duckdb:///path/to/file.duckdb

Engine	URL Format
PostgreSQL	`postgresql://postgres@127.0.0.1:5432/mydb`
MySQL	`mysql://root@127.0.0.1:3306/mydb`
MariaDB	`mysql://root@127.0.0.1:3307/mydb`
MongoDB	`mongodb://127.0.0.1:27017/mydb`
Redis	`redis://127.0.0.1:6379/0`
ClickHouse	`clickhouse://default@127.0.0.1:9000/default`
CockroachDB	`postgresql://root@127.0.0.1:26257/defaultdb`
SurrealDB	`ws://root:root@127.0.0.1:8000/test/test`
QuestDB	`postgresql://admin:quest@127.0.0.1:8812/qdb`
SQLite	`sqlite:///path/to/file.sqlite`
DuckDB	`duckdb:///path/to/file.duckdb`

10 / Database Management

Manage databases within containers

Create, rename, and drop databases inside a running container. Manage users and credentials.

databases

$ spindb databases create mydb analytics
$ spindb databases rename mydb old_name new_name
$ spindb databases drop mydb analytics --force
$ spindb databases list mydb
$ spindb databases set-default mydb prod
$ spindb databases refresh mydb

users

$ spindb users create mydb
$ spindb users create mydb devuser
$ spindb users create mydb --password p
$ spindb users create mydb --copy
$ spindb users create mydb --json
$ spindb users list mydb

11 / Docker Export

Export to Docker

SpinDB doesn't need Docker, but it can package your database as a Docker image for deployment.

terminal

$ spindb export docker mydb -o ./deploy
$ cd ./deploy
$ docker compose build --no-cache
$ docker compose up -d

# Connect from host
$ source .env
$ psql "postgresql://$SPINDB_USER:$SPINDB_PASSWORD@localhost:$PORT/$DATABASE"

Generates a Dockerfile, docker-compose.yml, entrypoint script, TLS certificates, and credentials. Ready to deploy to any container platform.

12 / Ports

Default ports

SpinDB auto-assigns ports from these ranges. Override with --port on create.

Engine	Default	Range	Notes
PostgreSQL	`5432`	5432-5500
MySQL	`3306`	3306-3400
MariaDB	`3307`	3307-3400
MongoDB	`27017`	27017-27100
FerretDB	`27017`	27017-27100
Redis	`6379`	6379-6400
Valkey	`6379`	6379-6479
ClickHouse	`9000`	9000-9100	HTTP UI on 8123
Qdrant	`6333`	6333-6400	gRPC on port+1
Meilisearch	`7700`	7700-7800
CouchDB	`5984`	5984-6084	Fauxton UI included
CockroachDB	`26257`	26257-26357	HTTP UI on port+1
SurrealDB	`8000`	8000-8100	HTTP/WebSocket
QuestDB	`8812`	8812-8912	Web Console at PG+188
TypeDB	`1729`	1729-1829	HTTP on port+6271
InfluxDB	`8086`	8086-8186	REST API only
Weaviate	`8080`	8080-8180	gRPC on port+1
TigerBeetle	`3000`	3000-3100	Binary protocol
SQLite	`N/A`	File-based
DuckDB	`N/A`	File-based

13 / Scripting

Automation & CI/CD

JSON output for every command. Pipe to jq, use in scripts, or integrate into CI pipelines.

scripting patterns

# Export connection string
$ export DATABASE_URL=$(spindb url mydb)

# Backup all PostgreSQL containers
$ for c in $(spindb list --json | jq -r \
    '.[] | select(.engine=="postgresql") | .name'); do
    spindb backup "$c" -o ./backups/
  done

# Check if running
$ if spindb info mydb --json | \
    jq -e '.status == "running"' > /dev/null; then
    echo "Container is running"
  fi

CI/CD (GitHub Actions)

# .github/workflows/test.yml
- name: Install SpinDB
  run: pnpm add -g spindb

- name: Install database tools
  run: spindb deps install --engine postgresql

- name: Create test database
  run: spindb create testdb --start

- name: Run migrations
  run: spindb run testdb ./schema.sql

- name: Run tests
  run: pnpm test

package.json scripts

# Example scripts section
$ "db:create": "spindb create myapp --start"
$ "db:reset": "spindb delete myapp -f && spindb create myapp --start"
$ "db:migrate": "spindb run myapp ./migrations/*.sql"
$ "db:seed": "spindb run myapp ./seeds/dev-data.sql"
$ "db:backup": "spindb backup myapp --format sql -o ./backups"

14 / Config & Troubleshooting

Configuration and diagnostics

Manage tool paths, run health checks, and resolve common issues.

configuration

$ spindb config show
$ spindb config detect
$ spindb config set psql /opt/pg/bin/psql
$ spindb config unset psql
$ spindb config update-check on
$ spindb engines
$ spindb engines download postgresql 18
$ spindb deps check
$ spindb deps install

troubleshooting

# Port conflict
$ spindb create mydb --port 5433

# Container won't start
$ spindb logs mydb

# Health check
$ spindb doctor
$ spindb doctor --fix
$ spindb doctor --dry-run

# Reset everything
$ rm -rf ~/.spindb

Get started with SpinDB

One command to install. One command to create a database. Works on macOS, Linux, and Windows.

View on npm View on GitHub