SpinDB

0.48.1 verified Sat Apr 25 auth: no javascript

SpinDB (v0.48.1) is a zero-configuration, Docker-free local database management tool that packages 21 database engines (PostgreSQL, MySQL, MariaDB, SQLite, DuckDB, MongoDB, FerretDB, Redis, Valkey, ClickHouse, Qdrant, Meilisearch, CouchDB, CockroachDB, SurrealDB, QuestDB, TypeDB, InfluxDB, Weaviate, TigerBeetle, LibSQL) into a single CLI. It runs directly on macOS, Linux, and Windows without Docker or VMs, providing commands to create, start, connect, run SQL/shell, backup, and clone databases. The tool persists data in ~/.spindb and exposes connection URLs. It is licensed under PolyForm Noncommercial and requires Node.js >=22 and pnpm >=8. Key differentiators include broad engine support, simple CLI, and no external dependencies like Docker.

Common errors

error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/spindb' ↓

cause Installing global npm packages without proper sudo or prefix.

fix

Run 'sudo npm install -g spindb' or configure npm prefix: 'npm config set prefix ~/.npm-global' then add to PATH.

error spindb: command not found ↓

cause Global npm module not added to PATH.

fix

Add npm global bin to PATH: export PATH=$(npm bin -g):$PATH (Linux/macOS) or use npx spindb.

error Error: This version of spindb requires Node.js >=22 ↓

cause Outdated Node.js version.

fix

Upgrade Node.js to v22 or later; use nvm or download from nodejs.org.

error Error: listen EADDRINUSE: address already in use :::5432 ↓

cause Default PostgreSQL port 5432 is already occupied.

fix

Use 'spindb create mydb --port 5433' to assign a different port, or stop the existing service on 5432.

error Error: (FetchError) request to https://github.com/... failed, reason: connect ECONNREFUSED ↓

cause Network issue or GitHub blocked; SpinDB downloads database binaries from GitHub.

fix

Check internet connection or proxy; set HTTP_PROXY if behind corporate firewall.

Warnings

gotcha Node.js 22+ is required; older versions cause cryptic errors on install. ↓

fix Upgrade Node.js to >=22 (LTS).

deprecated FerretDB v2 requires macOS/Linux; v1 on Windows uses plain PostgreSQL backend (not a full MongoDB replacement). ↓

fix On Windows, use FerretDB v1 explicitly with --ferretdb-version 1, or use MongoDB engine instead.

gotcha Data persists in ~/.spindb/; accidental deletion of this directory removes all databases. ↓

fix Backup regularly; use spindb backup before deleting ~/.spindb.

breaking CLI commands changed in v0.30.0: 'spindb run' now requires -c or file argument; inline scripts removed. ↓

fix Use 'spindb run mydb -c "SQL"' instead of 'spindb run mydb SQL'.

gotcha ClickHouse and LibSQL on Windows require WSL; native Windows is not supported. ↓

fix Install WSL and run the spindb commands inside WSL, or use a different engine.

deprecated License is PolyForm Noncommercial; commercial use requires a separate license. ↓

fix Contact the author for commercial licenses; do not use in paid products without permission.

gotcha Global install may require sudo on macOS/Linux; non-sudo installs may break PATH. ↓

fix Use 'npm install -g spindb' without sudo, or configure npm prefix to user directory.

Install

npm install spindb

yarn add spindb

pnpm add spindb

Imports

spindb (CLI)
wrong
```
npm install spindb (without -g)
```
correct
```
npm install -g spindb
```
SpinDB is primarily a CLI tool; install globally or use npx.
spindb (programmatic usage not supported)
```
N/A - no programmatic API
```
Current version 0.48.1 provides only CLI; there is no npm package export for programmatic use.
spindb create
wrong
```
spindb mydb create (wrong order)
```
correct
```
spindb create mydb --start --connect
```
Verb must come first; flags like --engine specify the database type.

Quickstart

Installs SpinDB globally, creates and connects to a PostgreSQL database, runs a query, and creates a backup.

npm install -g spindb
spindb create testdb --engine postgresql --start --connect
# Then inside psql:
SELECT version();
\q
spindb backup testdb --format sql --out backup.sql