# SpinDB
Sponsored by Layerbase
[](https://www.npmjs.com/package/spindb)
[](https://www.npmjs.com/package/spindb)
[](LICENSE)
[](#supported-engines--platforms)
**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.
```bash
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
```bash
# Install
npm install -g spindb
# Or with pnpm (requires `pnpm setup` first on pnpm 10+):
# pnpm setup && 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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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 restore mydb backup.dump --into-existing # In-place restore (no DROP DATABASE)
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](CHEATSHEET.md) for the complete command reference, connection strings, backup formats, scripting patterns, and more.
### Branching (copy-on-write)
Fork a database instantly, the way Neon/Vercel do โ but locally and for **every engine**:
```bash
spindb branch myapp myapp-feature # instant copy-on-write fork (auto stop/restart if running)
spindb branch list # see the lineage tree
spindb branch reset myapp-feature # discard the branch's changes, re-fork from parent
spindb branch delete myapp-feature
```
On copy-on-write filesystems (APFS on macOS; Btrfs / XFS-reflink / ZFS on Linux) a branch is instant and shares disk blocks with its source until they diverge; elsewhere it falls back to a full copy. See [docs/BRANCHING.md](docs/BRANCHING.md).
---
## 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](#license) for details.
---
## How It Works
SpinDB uses "container" terminology looselyโthere's no Docker involved. When you create a container, SpinDB:
1. **Resolves the version** via the [`hostdb` npm package](https://www.npmjs.com/package/hostdb), which is pinned as a SpinDB dependency. `hostdb` bundles a registry snapshot (`databases.json` + `releases.json`) at publish time, so the resolution is offline and deterministic โ `spindb create postgresql 18` always picks the exact same patch for a given SpinDB release.
2. **Downloads database binaries** from `registry.layerbase.host` (Cloudflare R2 mirror of [hostdb](https://github.com/robertjbass/hostdb)). When a new database version is published to hostdb, SpinDB picks it up on the next release (we bump the `hostdb` dep and republish SpinDB).
3. **Creates isolated data directories** at `~/.spindb/containers/{engine}/{name}/`
4. **Runs databases as native processes** on your machine
The container config persists the **full resolved version** (e.g. `18.4.0`), not the shorthand (`18`). This means a future SpinDB upgrade will not silently switch your existing data to a different patch โ the binary you originally built against is what your container keeps running on. Use `spindb doctor --dry-run` to see version drift; `spindb doctor` (interactive) or `spindb doctor --fix` to migrate older containers created before this guarantee was in place.
### Storage Layout
```bash
~/.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. 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:
```bash
spindb export docker mydb -o ./deploy
cd ./deploy && docker compose build --no-cache && docker compose up -d
```
See [DEPLOY.md](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
```bash
spindb create mydb --port 5433
```
### Container Won't Start
```bash
spindb logs mydb
```
### Client Tool Not Found
```bash
spindb deps install
spindb deps check
```
### Health Check
```bash
spindb doctor # Interactive health check
spindb doctor --fix # Auto-fix all issues
```
### Reset Everything
```bash
rm -rf ~/.spindb
```
This deletes all containers, binaries, and configuration. Use with caution.
---
## Roadmap
See [TODO.md](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](TODO.md#contributing) for development setup, PR requirements, and testing guidelines.
See [ARCHITECTURE.md](ARCHITECTURE.md) for project architecture details.
See [CLAUDE.md](CLAUDE.md) for AI-assisted development context.
See [ENGINE_CHECKLIST.md](ENGINE_CHECKLIST.md) for adding new database engines.
---
## Acknowledgments
SpinDB is powered by:
- **[hostdb](https://github.com/robertjbass/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](LICENSE)
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.
---
## Links
- **GitHub:** [github.com/robertjbass/spindb](https://github.com/robertjbass/spindb)
- **npm:** [npmjs.com/package/spindb](https://www.npmjs.com/package/spindb)
- **hostdb:** [github.com/robertjbass/hostdb](https://github.com/robertjbass/hostdb)
- **Issues:** [github.com/robertjbass/spindb/issues](https://github.com/robertjbass/spindb/issues)
---
**Questions? Found a bug? Have a feature request?**
Open an issue: [github.com/robertjbass/spindb/issues](https://github.com/robertjbass/spindb/issues)