spindb

v0.47.5

Published

6 hours ago

Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.

SpinDB

One CLI for all your local databases.

SpinDB is a universal database management tool that combines a package manager, a unified API, and native client tooling for 21 different database engines—all from a single command-line interface. No Docker, no VMs, no platform-specific installers. Just databases, running natively on your machine.

npm install -g spindb

# PostgreSQL for your API
spindb create api-db

# MongoDB for analytics
spindb create analytics --engine mongodb

# Redis for caching
spindb create cache --engine redis

# All running side-by-side, all managed the same way

Supported Engines & Platforms

SpinDB supports 21 database engines across 5 platform architectures—all with a consistent API.

| Engine | Type | macOS ARM | macOS Intel | Linux x64 | Linux ARM | Windows | |--------|------|:---------:|:-----------:|:---------:|:---------:|:-------:| | 🐘 PostgreSQL | Relational SQL | ✅ | ✅ | ✅ | ✅ | ✅ | | 🐬 MySQL | Relational SQL | ✅ | ✅ | ✅ | ✅ | ✅ | | 🦭 MariaDB | Relational SQL | ✅ | ✅ | ✅ | ✅ | ✅ | | 🪶 SQLite | Embedded SQL | ✅ | ✅ | ✅ | ✅ | ✅ | | 🦆 DuckDB | Embedded OLAP | ✅ | ✅ | ✅ | ✅ | ✅ | | 🍃 MongoDB | Document Store | ✅ | ✅ | ✅ | ✅ | ✅ | | 🦔 FerretDB | Document Store | ✅ | ✅ | ✅ | ✅ | ⚠️ | | 🔴 Redis | Key-Value | ✅ | ✅ | ✅ | ✅ | ✅ | | 🔷 Valkey | Key-Value | ✅ | ✅ | ✅ | ✅ | ✅ | | 🏠 ClickHouse | Columnar OLAP | ✅ | ✅ | ✅ | ✅ | ❌ | | 🧭 Qdrant | Vector Search | ✅ | ✅ | ✅ | ✅ | ✅ | | 🔍 Meilisearch | Full-Text Search | ✅ | ✅ | ✅ | ✅ | ✅ | | 🛋️ CouchDB | Document Store | ✅ | ✅ | ✅ | ✅ | ✅ | | 🪳 CockroachDB | Distributed SQL | ✅ | ✅ | ✅ | ✅ | ✅ | | 🌀 SurrealDB | Multi-Model | ✅ | ✅ | ✅ | ✅ | ✅ | | ⏱️ QuestDB | Time-Series | ✅ | ✅ | ✅ | ✅ | ✅ | | 🤖 TypeDB | Knowledge Graph | ✅ | ✅ | ✅ | ✅ | ✅ | | 📈 InfluxDB | Time-Series | ✅ | ✅ | ✅ | ✅ | ✅ | | 🔮 Weaviate | Vector Database | ✅ | ✅ | ✅ | ✅ | ✅ | | 🐯 TigerBeetle | Financial Ledger | ✅ | ✅ | ✅ | ✅ | ✅ | | 📚 LibSQL | Embedded SQL Server | ✅ | ✅ | ✅ | ✅ | ❌ |

101+ supported combinations. One CLI. Zero configuration.

ClickHouse and LibSQL are available on Windows via WSL. FerretDB v1 is natively supported on Windows (uses plain PostgreSQL backend); v2 requires macOS/Linux.

Quick Start

# Install
npm install -g spindb    # or: pnpm add -g spindb

# Create and start a PostgreSQL database
spindb create myapp --start --connect

That's it! Your PostgreSQL database is running on localhost:5432, and data persists in ~/.spindb/containers/postgresql/myapp/.

Basic Usage

PostgreSQL

spindb create myapp                              # Create (default engine)
spindb start myapp                               # Start
spindb connect myapp                             # Open psql shell
spindb run myapp -c "SELECT version()"           # Run inline SQL
spindb run myapp ./schema.sql                    # Run SQL file
spindb backup myapp --format sql                 # Backup
spindb url myapp --copy                          # Copy connection string

MongoDB

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

Redis

spindb create cache --engine redis --start
spindb run cache -c "SET mykey myvalue"
spindb run cache -c "GET mykey"
spindb connect cache                             # Open redis-cli
spindb connect cache --iredis                    # Enhanced shell

InfluxDB

spindb create tsdata --engine influxdb --start
spindb run tsdata ./seed.lp                      # Seed with line protocol
spindb run tsdata -c "SHOW TABLES"               # Run inline SQL
spindb run tsdata ./queries.sql                   # Run SQL file
spindb connect tsdata                             # Interactive SQL console

InfluxDB supports two file formats: .lp (line protocol) for writing data, .sql for queries.

Weaviate

spindb create vectors --engine weaviate --start
spindb query vectors "GET /v1/schema"             # Query via REST API
spindb connect vectors                            # Open web dashboard

Weaviate is an AI-native vector database. REST API on default port 8080, gRPC on port+1. Uses classes/collections.

TigerBeetle

spindb create ledger --engine tigerbeetle --start
spindb connect ledger                            # Open REPL

TigerBeetle is a high-performance financial ledger database. Custom binary protocol on default port 3000. Uses REPL for interaction.

LibSQL

spindb create mydata --engine libsql --start
curl http://127.0.0.1:8080/health                 # Health check
spindb connect mydata                              # Show HTTP API endpoints

LibSQL is a SQLite fork by Turso that runs as a server. HTTP API (Hrana protocol) on default port 8080. Query via REST API.

Enhanced Shells & Visual Tools

spindb connect myapp --pgcli                     # Enhanced PostgreSQL shell
spindb connect myapp --dblab                     # Visual TUI (table browser)
spindb connect mydb --mycli                      # Enhanced MySQL/MariaDB shell
spindb connect mydb --ui                         # Built-in Web UI (DuckDB)

Any Engine

spindb create mydb --engine [postgresql|mysql|mariadb|mongodb|ferretdb|redis|valkey|clickhouse|sqlite|duckdb|qdrant|meilisearch|couchdb|cockroachdb|surrealdb|questdb|typedb|influxdb|weaviate|tigerbeetle|libsql]
spindb start mydb
spindb connect mydb
spindb backup mydb
spindb restore mydb backup.dump
spindb clone mydb mydb-copy
spindb delete mydb -f

# Database management within containers
spindb databases create mydb analytics          # Create a new database
spindb databases rename mydb old_name new_name  # Rename (backup/restore or native)
spindb databases drop mydb analytics --force    # Drop a database

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

See CHEATSHEET.md for the complete command reference, connection strings, backup formats, scripting patterns, and more.

Why SpinDB?

The Problem with Current Tools

Docker is powerful but heavy—requires a daemon, runs containers in a VM (on macOS/Windows), and adds complexity for simple local databases.

GUI tools like DBngin and Postgres.app are great but platform-specific, don't support scripting, and lack a unified interface across engines.

System package managers (brew, apt, etc.) work but create version conflicts, require manual configuration, and don't provide consistent management across databases.

SpinDB's Approach

SpinDB runs databases as native processes with isolated data directories:

No Docker daemon or VM overhead - Direct process execution
No system installation conflicts - Each database version lives in ~/.spindb/bin/
No manual configuration - Databases start with sensible defaults
Cross-platform consistency - Same commands work on macOS, Linux, and Windows
Multi-version support - Run PostgreSQL 14 and 18 side-by-side
Unified interface - Manage PostgreSQL, MongoDB, and Redis the same way

Comparison: Database GUI Tools

For developers who prefer visual interfaces or use macOS-native tools.

| Feature | SpinDB | DBngin | Postgres.app | Laragon | |---------|--------|--------|--------------|---------| | Engines supported | 21 | 3 (PG/MySQL/Redis) | 1 (PostgreSQL) | 4 (PG/MySQL/MariaDB/MongoDB) | | CLI-first | ✅ | ❌ GUI-only | ❌ GUI-only | ⚠️ Limited CLI | | Multi-version support | ✅ | ✅ | ✅ | ✅ | | Built-in backup/restore | ✅ | ✅ | ❌ | ⚠️ Manual | | Clone databases | ✅ | ✅ | ❌ | ❌ | | macOS | ✅ | ✅ | ✅ | ❌ | | Linux | ✅ | ❌ | ❌ | ❌ | | Windows | ✅ | ❌ | ❌ | ✅ | | Free for commercial use | ❌ | ✅ | ✅ | ✅ |

Comparison: Docker & Containers

For developers already using containerization.

| Feature | SpinDB | Docker Desktop | Podman | OrbStack | |---------|--------|----------------|--------|----------| | Engines supported | 21 unified | Any (manual setup) | Any (manual setup) | Any (manual setup) | | Daemon required | ❌ | ✅ | ❌ (rootless) | ✅ | | Resource overhead | Native | VM + containers | VM + containers | VM + containers | | Built-in backup/restore | ✅ | ❌ Manual | ❌ Manual | ❌ Manual | | Connection strings | ✅ Auto-generated | ❌ Manual | ❌ Manual | ❌ Manual | | Version switching | ✅ Instant | ⚠️ Pull images | ⚠️ Pull images | ⚠️ Pull images | | Database-specific CLI | ✅ Included | ❌ Exec into container | ❌ Exec into container | ❌ Exec into container | | Prod parity | ⚠️ Native binaries | ✅ Exact images | ✅ Exact images | ✅ Exact images | | Free for commercial use | ❌ | ⚠️ Paid for orgs | ✅ | ⚠️ Paid tiers |

Comparison: Package Managers

For developers who "just install" databases system-wide.

| Feature | SpinDB | Homebrew | apt/winget | asdf-vm | |---------|--------|----------|------------|---------| | Engines supported | 21 unified | Many (separate formulas) | Many (separate packages) | Many (plugins) | | Multi-version side-by-side | ✅ | ⚠️ Complex | ❌ | ✅ | | Isolated data directories | ✅ | ❌ System-wide | ❌ System-wide | ❌ | | Built-in backup/restore | ✅ | ❌ | ❌ | ❌ | | Unified CLI across engines | ✅ | ❌ | ❌ | ❌ | | No root/sudo required | ✅ | ✅ | ❌ | ✅ | | macOS | ✅ | ✅ | ❌ | ✅ | | Linux | ✅ | ✅ | ✅ | ✅ | | Windows | ✅ | ❌ | ✅ (winget) | ⚠️ WSL | | Free for commercial use | ❌ | ✅ | ✅ | ✅ |

Note on licensing: SpinDB requires a commercial license for business use. For personal projects, education, research, nonprofits, and government use, SpinDB is free. See License for details.

How It Works

SpinDB uses "container" terminology loosely—there's no Docker involved. When you create a container, SpinDB:

Downloads database binaries from hostdb or uses system installations
Creates isolated data directories at ~/.spindb/containers/{engine}/{name}/
Runs databases as native processes on your machine

Storage Layout

~/.spindb/
├── bin/                                    # Downloaded binaries
│   ├── postgresql-18.1.0-darwin-arm64/     # ~45 MB
│   ├── mysql-9.0.1-darwin-arm64/           # ~200 MB
│   └── mongodb-8.0-darwin-arm64/           # ~200 MB
├── containers/                             # Server-based databases
│   ├── postgresql/
│   │   └── myapp/
│   │       ├── container.json
│   │       ├── data/
│   │       ├── credentials/              # User credential .env.<username> files
│   │       └── postgres.log
│   ├── mysql/
│   └── mongodb/
├── logs/                                   # SpinDB error logs
└── config.json                             # Tool paths and settings

# File-based databases (SQLite, DuckDB) store in project directories
./myproject/
└── app.sqlite                              # Created with: spindb create app -e sqlite

Data Persistence

Databases run as native processes, and data persists across restarts. Your data is never deleted unless you explicitly run spindb delete.

Export to Docker

SpinDB doesn't require Docker for local development, but it can repackage your database as a Docker image for deployment:

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

See DEPLOY.md for comprehensive deployment documentation.

Limitations

Local by default - Databases bind to 127.0.0.1. Use spindb link to connect to remote databases (supports connect, query, url, info, list, delete).
ClickHouse Windows - Not supported (hostdb doesn't build for Windows).
FerretDB Windows - v1 supported natively (plain PostgreSQL backend). v2 not supported (postgresql-documentdb has startup issues); use WSL for v2.
Qdrant, Meilisearch, CouchDB, Weaviate, LibSQL - Use REST API instead of CLI shell. Access via HTTP at the configured port.
LibSQL Windows - Not supported (hostdb doesn't build for Windows). Use WSL.
TigerBeetle - Custom binary protocol only. No SQL or REST API. Interact via REPL (spindb connect) or client libraries.

Troubleshooting

Port Already in Use

spindb create mydb --port 5433

Container Won't Start

spindb logs mydb

Client Tool Not Found

spindb deps install
spindb deps check

Health Check

spindb doctor          # Interactive health check
spindb doctor --fix    # Auto-fix all issues

Reset Everything

rm -rf ~/.spindb

This deletes all containers, binaries, and configuration. Use with caution.

Roadmap

See TODO.md for the complete roadmap and future plans.

Use Cases

Migration & Portability

Cloud Migration Pipeline - Create a SpinDB container, restore from an existing database, export to Docker, deploy to any cloud provider
Cross-Platform Migration - Move databases between ARM Mac, x64 Linux, Windows, and Apple Silicon transparently via backup/restore
MongoDB to FerretDB - Test MongoDB-to-FerretDB migration locally before infrastructure changes

Development Workflow

Multiple Database Versions - Run PostgreSQL 14 and 18 side-by-side for compatibility testing
Git-Triggered Database Branching - Use git hooks to clone database state per branch
Environment Synchronization - Pull production data locally for realistic development
Rapid Prototyping - Spin up PostgreSQL, MongoDB, and Redis in minutes, compare patterns, delete without cleanup

Testing & CI/CD

Ephemeral Test Databases - Fresh database instances for each test run with automatic teardown
Schema Migration Testing - Clone production, run migrations, validate, iterate without risk
Data Validation - Use DuckDB or PostgreSQL to validate data pipelines with aggregate queries

Platform Gaps

Redis/Valkey on Windows - No official Windows builds exist; SpinDB provides them
ClickHouse on macOS - No Homebrew complexity
FerretDB anywhere - MongoDB-compatible without Docker

Embedding & Integration

LLM Agent Integration - Connect AI agents to databases via CLI with JSON output mode
AI Tool Embedding - Qdrant for vector search, DuckDB for analytics, SQLite for conversation history
Desktop Applications - Ship relocatable database binaries inside apps

Deployment

Local-to-Cloud - Export to Docker image, push to registry, deploy to any container platform
Production Data Anonymization - Clone production, anonymize, develop safely
Disaster Recovery Practice - Practice restore workflows without production risk

Infrastructure

SpinDB can serve as the database layer for larger systems:

Backend-as-a-Service - A database-agnostic Neon/Supabase-style platform using SpinDB primitives (create, clone, backup, restore)
Desktop GUI - A cross-platform database management app (Tauri/Electron) wrapping SpinDB
Team Environments - Export/import container configurations for consistent team setups

Contributing

We welcome contributions! SpinDB is built with:

Runtime: Node.js 18+ with TypeScript
Execution: tsx for direct TypeScript execution
Package Manager: pnpm (strictly enforced)
CLI Framework: Commander.js
Interactive UI: Inquirer.js, Chalk, Ora

See TODO.md for development setup, PR requirements, and testing guidelines.

See ARCHITECTURE.md for project architecture details.

See CLAUDE.md for AI-assisted development context.

See ENGINE_CHECKLIST.md for adding new database engines.

Acknowledgments

SpinDB is powered by:

hostdb - Pre-compiled database binaries for 21 engines across all major platforms. Makes Docker-free multi-version database support possible.

License

PolyForm Noncommercial 1.0.0

SpinDB is free for:

Personal use and hobby projects
Educational institutions and students
Academic and scientific research
Nonprofit organizations
Government agencies

Commercial use requires a separate license. For commercial licensing inquiries, please open an issue or contact the maintainer.