\n\n[](https://www.npmjs.com/package/spindb)\n[](https://www.npmjs.com/package/spindb)\n[](LICENSE)\n[](#supported-engines--platforms)\n\n**One CLI for all your local databases.**\n\nSpinDB 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.\n\n```bash\nnpm install -g spindb\n\n# PostgreSQL for your API\nspindb create api-db\n\n# MongoDB for analytics\nspindb create analytics --engine mongodb\n\n# Redis for caching\nspindb create cache --engine redis\n\n# All running side-by-side, all managed the same way\n```\n\n---\n\n## Supported Engines & Platforms\n\nSpinDB supports **21 database engines** across **5 platform architectures**—all with a consistent API.\n\n| Engine | Type | macOS ARM | macOS Intel | Linux x64 | Linux ARM | Windows |\n|--------|------|:---------:|:-----------:|:---------:|:---------:|:-------:|\n| 🐘 **PostgreSQL** | Relational SQL | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🐬 **MySQL** | Relational SQL | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🦭 **MariaDB** | Relational SQL | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🪶 **SQLite** | Embedded SQL | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🦆 **DuckDB** | Embedded OLAP | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🍃 **MongoDB** | Document Store | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🦔 **FerretDB** | Document Store | ✅ | ✅ | ✅ | ✅ | ⚠️ |\n| 🔴 **Redis** | Key-Value | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🔷 **Valkey** | Key-Value | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🏠 **ClickHouse** | Columnar OLAP | ✅ | ✅ | ✅ | ✅ | ❌ |\n| 🧭 **Qdrant** | Vector Search | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🔍 **Meilisearch** | Full-Text Search | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🛋️ **CouchDB** | Document Store | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🪳 **CockroachDB** | Distributed SQL | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🌀 **SurrealDB** | Multi-Model | ✅ | ✅ | ✅ | ✅ | ✅ |\n| ⏱️ **QuestDB** | Time-Series | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🤖 **TypeDB** | Knowledge Graph | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 📈 **InfluxDB** | Time-Series | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🔮 **Weaviate** | Vector Database | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 🐯 **TigerBeetle** | Financial Ledger | ✅ | ✅ | ✅ | ✅ | ✅ |\n| 📚 **LibSQL** | Embedded SQL Server | ✅ | ✅ | ✅ | ✅ | ❌ |\n\n**101+ supported combinations. One CLI. Zero configuration.**\n\n> ClickHouse and LibSQL are available on Windows via WSL. FerretDB v1 is natively supported on Windows (uses plain PostgreSQL backend); v2 requires macOS/Linux.\n\n---\n\n## Quick Start\n\n```bash\n# Install\nnpm install -g spindb\n# Or with pnpm (requires `pnpm setup` first on pnpm 10+):\n# pnpm setup && pnpm add -g spindb\n\n# Create and start a PostgreSQL database\nspindb create myapp --start --connect\n```\n\nThat's it! Your PostgreSQL database is running on `localhost:5432`, and data persists in `~/.spindb/containers/postgresql/myapp/`.\n\n---\n\n## Basic Usage\n\n### PostgreSQL\n\n```bash\nspindb create myapp # Create (default engine)\nspindb start myapp # Start\nspindb connect myapp # Open psql shell\nspindb run myapp -c \"SELECT version()\" # Run inline SQL\nspindb run myapp ./schema.sql # Run SQL file\nspindb backup myapp --format sql # Backup\nspindb url myapp --copy # Copy connection string\nspindb restore myapp dump.sql --pre-sql shims.sql # Create missing extensions/roles first\nspindb restore myapp dump.dump --with-privileges # Replay the dump's GRANTs (dropped by default)\n```\n\n### MongoDB\n\n```bash\nspindb create logs --engine mongodb --start\nspindb run logs -c \"db.users.insertOne({name: 'Alice'})\"\nspindb run logs -c \"db.users.find().pretty()\"\nspindb connect logs # Open mongosh\nspindb backup logs --format archive\n```\n\n### Redis\n\n```bash\nspindb create cache --engine redis --start\nspindb run cache -c \"SET mykey myvalue\"\nspindb run cache -c \"GET mykey\"\nspindb connect cache # Open redis-cli\nspindb connect cache --iredis # Enhanced shell\n```\n\n### InfluxDB\n\n```bash\nspindb create tsdata --engine influxdb --start\nspindb run tsdata ./seed.lp # Seed with line protocol\nspindb run tsdata -c \"SHOW TABLES\" # Run inline SQL\nspindb run tsdata ./queries.sql # Run SQL file\nspindb connect tsdata # Interactive SQL console\n```\n\n> InfluxDB supports two file formats: `.lp` (line protocol) for writing data, `.sql` for queries.\n\n### Weaviate\n\n```bash\nspindb create vectors --engine weaviate --start\nspindb query vectors \"GET /v1/schema\" # Query via REST API\nspindb connect vectors # Open web dashboard\n```\n\n> Weaviate is an AI-native vector database. REST API on default port 8080, gRPC on port+1. Uses classes/collections.\n\n### TigerBeetle\n\n```bash\nspindb create ledger --engine tigerbeetle --start\nspindb connect ledger # Open REPL\n```\n\n> TigerBeetle is a high-performance financial ledger database. Custom binary protocol on default port 3000. Uses REPL for interaction.\n\n### LibSQL\n\n```bash\nspindb create mydata --engine libsql --start\ncurl http://127.0.0.1:8080/health # Health check\nspindb connect mydata # Show HTTP API endpoints\n```\n\n> LibSQL is a SQLite fork by Turso that runs as a server. HTTP API (Hrana protocol) on default port 8080. Query via REST API.\n\n### Enhanced Shells & Visual Tools\n\n```bash\nspindb connect myapp --pgcli # Enhanced PostgreSQL shell\nspindb connect myapp --dblab # Visual TUI (table browser)\nspindb connect mydb --mycli # Enhanced MySQL/MariaDB shell\nspindb connect mydb --ui # Built-in Web UI (DuckDB)\n```\n\n### Any Engine\n\n```bash\nspindb create mydb --engine [postgresql|mysql|mariadb|mongodb|ferretdb|redis|valkey|clickhouse|sqlite|duckdb|qdrant|meilisearch|couchdb|cockroachdb|surrealdb|questdb|typedb|influxdb|weaviate|tigerbeetle|libsql]\nspindb start mydb\nspindb connect mydb\nspindb backup mydb\nspindb restore mydb backup.dump\nspindb restore mydb backup.dump --into-existing # In-place restore (no DROP DATABASE)\nspindb clone mydb mydb-copy\nspindb delete mydb -f\n\n# Database management within containers\nspindb databases create mydb analytics # Create a new database\nspindb databases rename mydb old_name new_name # Rename (backup/restore or native)\nspindb databases drop mydb analytics --force # Drop a database\n```\n\nEvery engine works the same way. Learn one, use them all.\n\n> See [CHEATSHEET.md](CHEATSHEET.md) for the complete command reference, connection strings, backup formats, scripting patterns, and more.\n\n### Branching (copy-on-write)\n\nFork a database instantly, the way Neon/Vercel do — but locally and for **every engine**:\n\n```bash\nspindb branch myapp myapp-feature # instant copy-on-write fork (auto stop/restart if running)\nspindb branch list # see the lineage tree\nspindb branch reset myapp-feature # discard the branch's changes, re-fork from parent\nspindb branch delete myapp-feature\n```\n\nOn 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).\n\n---\n\n## Why SpinDB?\n\n### The Problem with Current Tools\n\n**Docker** is powerful but heavy—requires a daemon, runs containers in a VM (on macOS/Windows), and adds complexity for simple local databases.\n\n**GUI tools** like DBngin and Postgres.app are great but platform-specific, don't support scripting, and lack a unified interface across engines.\n\n**System package managers** (brew, apt, etc.) work but create version conflicts, require manual configuration, and don't provide consistent management across databases.\n\n### SpinDB's Approach\n\nSpinDB runs databases as **native processes** with **isolated data directories**:\n\n- **No Docker daemon or VM overhead** - Direct process execution\n- **No system installation conflicts** - Each database version lives in `~/.spindb/bin/`\n- **No manual configuration** - Databases start with sensible defaults\n- **Cross-platform consistency** - Same commands work on macOS, Linux, and Windows\n- **Multi-version support** - Run PostgreSQL 14 and 18 side-by-side\n- **Unified interface** - Manage PostgreSQL, MongoDB, and Redis the same way\n\n### Comparison: Database GUI Tools\n\n*For developers who prefer visual interfaces or use macOS-native tools.*\n\n| Feature | SpinDB | DBngin | Postgres.app | Laragon |\n|---------|--------|--------|--------------|---------|\n| **Engines supported** | 21 | 3 (PG/MySQL/Redis) | 1 (PostgreSQL) | 4 (PG/MySQL/MariaDB/MongoDB) |\n| CLI-first | ✅ | ❌ GUI-only | ❌ GUI-only | ⚠️ Limited CLI |\n| Multi-version support | ✅ | ✅ | ✅ | ✅ |\n| Built-in backup/restore | ✅ | ✅ | ❌ | ⚠️ Manual |\n| Clone databases | ✅ | ✅ | ❌ | ❌ |\n| macOS | ✅ | ✅ | ✅ | ❌ |\n| Linux | ✅ | ❌ | ❌ | ❌ |\n| Windows | ✅ | ❌ | ❌ | ✅ |\n| Free for commercial use | ❌ | ✅ | ✅ | ✅ |\n\n### Comparison: Docker & Containers\n\n*For developers already using containerization.*\n\n| Feature | SpinDB | Docker Desktop | Podman | OrbStack |\n|---------|--------|----------------|--------|----------|\n| **Engines supported** | 21 unified | Any (manual setup) | Any (manual setup) | Any (manual setup) |\n| Daemon required | ❌ | ✅ | ❌ (rootless) | ✅ |\n| Resource overhead | Native | VM + containers | VM + containers | VM + containers |\n| Built-in backup/restore | ✅ | ❌ Manual | ❌ Manual | ❌ Manual |\n| Connection strings | ✅ Auto-generated | ❌ Manual | ❌ Manual | ❌ Manual |\n| Version switching | ✅ Instant | ⚠️ Pull images | ⚠️ Pull images | ⚠️ Pull images |\n| Database-specific CLI | ✅ Included | ❌ Exec into container | ❌ Exec into container | ❌ Exec into container |\n| Prod parity | ⚠️ Native binaries | ✅ Exact images | ✅ Exact images | ✅ Exact images |\n| Free for commercial use | ❌ | ⚠️ Paid for orgs | ✅ | ⚠️ Paid tiers |\n\n### Comparison: Package Managers\n\n*For developers who \"just install\" databases system-wide.*\n\n| Feature | SpinDB | Homebrew | apt/winget | asdf-vm |\n|---------|--------|----------|------------|---------|\n| **Engines supported** | 21 unified | Many (separate formulas) | Many (separate packages) | Many (plugins) |\n| Multi-version side-by-side | ✅ | ⚠️ Complex | ❌ | ✅ |\n| Isolated data directories | ✅ | ❌ System-wide | ❌ System-wide | ❌ |\n| Built-in backup/restore | ✅ | ❌ | ❌ | ❌ |\n| Unified CLI across engines | ✅ | ❌ | ❌ | ❌ |\n| No root/sudo required | ✅ | ✅ | ❌ | ✅ |\n| macOS | ✅ | ✅ | ❌ | ✅ |\n| Linux | ✅ | ✅ | ✅ | ✅ |\n| Windows | ✅ | ❌ | ✅ (winget) | ⚠️ WSL |\n| Free for commercial use | ❌ | ✅ | ✅ | ✅ |\n\n> **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.\n\n---\n\n## How It Works\n\nSpinDB uses \"container\" terminology loosely—there's no Docker involved. When you create a container, SpinDB:\n\n1. **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.\n2. **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).\n3. **Creates isolated data directories** at `~/.spindb/containers/{engine}/{name}/`\n4. **Runs databases as native processes** on your machine\n\nThe 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.\n\n### Storage Layout\n\n```bash\n~/.spindb/\n├── bin/ # Downloaded binaries\n│ ├── postgresql-18.1.0-darwin-arm64/ # ~45 MB\n│ ├── mysql-9.0.1-darwin-arm64/ # ~200 MB\n│ └── mongodb-8.0-darwin-arm64/ # ~200 MB\n├── containers/ # Server-based databases\n│ ├── postgresql/\n│ │ └── myapp/\n│ │ ├── container.json\n│ │ ├── data/\n│ │ ├── credentials/ # User credential .env. files\n│ │ └── postgres.log\n│ ├── mysql/\n│ └── mongodb/\n├── logs/ # SpinDB error logs\n└── config.json # Tool paths and settings\n\n# File-based databases (SQLite, DuckDB) store in project directories\n./myproject/\n└── app.sqlite # Created with: spindb create app -e sqlite\n```\n\n### Data Persistence\n\nDatabases run as **native processes**, and **data persists across restarts**. Your data is never deleted unless you explicitly run `spindb delete`.\n\n### Export to Docker\n\nSpinDB doesn't require Docker for local development, but it can repackage your database as a Docker image for deployment:\n\n```bash\nspindb export docker mydb -o ./deploy\ncd ./deploy && docker compose build --no-cache && docker compose up -d\n```\n\nSee [DEPLOY.md](DEPLOY.md) for comprehensive deployment documentation.\n\n---\n\n## Limitations\n\n- **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`).\n- **ClickHouse Windows** - Not supported (hostdb doesn't build for Windows).\n- **FerretDB Windows** - v1 supported natively (plain PostgreSQL backend). v2 not supported (postgresql-documentdb has startup issues); use WSL for v2.\n- **Qdrant, Meilisearch, CouchDB, Weaviate, LibSQL** - Use REST API instead of CLI shell. Access via HTTP at the configured port.\n- **LibSQL Windows** - Not supported (hostdb doesn't build for Windows). Use WSL.\n- **TigerBeetle** - Custom binary protocol only. No SQL or REST API. Interact via REPL (`spindb connect`) or client libraries.\n\n---\n\n## Troubleshooting\n\n### Port Already in Use\n\n```bash\nspindb create mydb --port 5433\n```\n\n### Container Won't Start\n\n```bash\nspindb logs mydb\n```\n\n### Client Tool Not Found\n\n```bash\nspindb deps install\nspindb deps check\n```\n\n### Health Check\n\n```bash\nspindb doctor # Interactive health check\nspindb doctor --fix # Auto-fix all issues\n```\n\n### Reset Everything\n\n```bash\nrm -rf ~/.spindb\n```\n\nThis deletes all containers, binaries, and configuration. Use with caution.\n\n---\n\n## Roadmap\n\nSee [TODO.md](TODO.md) for the complete roadmap and future plans.\n\n---\n\n## Use Cases\n\n### Migration & Portability\n\n- **Cloud Migration Pipeline** - Create a SpinDB container, restore from an existing database, export to Docker, deploy to any cloud provider\n- **Cross-Platform Migration** - Move databases between ARM Mac, x64 Linux, Windows, and Apple Silicon transparently via backup/restore\n- **MongoDB to FerretDB** - Test MongoDB-to-FerretDB migration locally before infrastructure changes\n\n### Development Workflow\n\n- **Multiple Database Versions** - Run PostgreSQL 14 and 18 side-by-side for compatibility testing\n- **Git-Triggered Database Branching** - Use git hooks to clone database state per branch\n- **Environment Synchronization** - Pull production data locally for realistic development\n- **Rapid Prototyping** - Spin up PostgreSQL, MongoDB, and Redis in minutes, compare patterns, delete without cleanup\n\n### Testing & CI/CD\n\n- **Ephemeral Test Databases** - Fresh database instances for each test run with automatic teardown\n- **Schema Migration Testing** - Clone production, run migrations, validate, iterate without risk\n- **Data Validation** - Use DuckDB or PostgreSQL to validate data pipelines with aggregate queries\n\n### Platform Gaps\n\n- **Redis/Valkey on Windows** - No official Windows builds exist; SpinDB provides them\n- **ClickHouse on macOS** - No Homebrew complexity\n- **FerretDB anywhere** - MongoDB-compatible without Docker\n\n### Embedding & Integration\n\n- **LLM Agent Integration** - Connect AI agents to databases via CLI with JSON output mode\n- **AI Tool Embedding** - Qdrant for vector search, DuckDB for analytics, SQLite for conversation history\n- **Desktop Applications** - Ship relocatable database binaries inside apps\n\n### Deployment\n\n- **Local-to-Cloud** - Export to Docker image, push to registry, deploy to any container platform\n- **Production Data Anonymization** - Clone production, anonymize, develop safely\n- **Disaster Recovery Practice** - Practice restore workflows without production risk\n\n### Infrastructure\n\nSpinDB can serve as the database layer for larger systems:\n\n- **Backend-as-a-Service** - A database-agnostic Neon/Supabase-style platform using SpinDB primitives (`create`, `clone`, `backup`, `restore`)\n- **Desktop GUI** - A cross-platform database management app (Tauri/Electron) wrapping SpinDB\n- **Team Environments** - Export/import container configurations for consistent team setups\n\n---\n\n## Contributing\n\nWe welcome contributions! SpinDB is built with:\n\n- **Runtime:** Node.js 18+ with TypeScript\n- **Execution:** `tsx` for direct TypeScript execution\n- **Package Manager:** pnpm (strictly enforced)\n- **CLI Framework:** Commander.js\n- **Interactive UI:** Inquirer.js, Chalk, Ora\n\nSee [TODO.md](TODO.md#contributing) for development setup, PR requirements, and testing guidelines.\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for project architecture details.\n\nSee [CLAUDE.md](CLAUDE.md) for AI-assisted development context.\n\nSee [ENGINE_CHECKLIST.md](ENGINE_CHECKLIST.md) for adding new database engines.\n\n---\n\n## Acknowledgments\n\nSpinDB is powered by:\n\n- **[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.\n\n---\n\n## License\n\n[PolyForm Noncommercial 1.0.0](LICENSE)\n\nSpinDB is **free** for:\n- Personal use and hobby projects\n- Educational institutions and students\n- Academic and scientific research\n- Nonprofit organizations\n- Government agencies\n\n**Commercial use requires a separate license.** For commercial licensing inquiries, please open an issue or contact the maintainer.\n\n---\n\n## Links\n\n- **GitHub:** [github.com/robertjbass/spindb](https://github.com/robertjbass/spindb)\n- **npm:** [npmjs.com/package/spindb](https://www.npmjs.com/package/spindb)\n- **hostdb:** [github.com/robertjbass/hostdb](https://github.com/robertjbass/hostdb)\n- **Issues:** [github.com/robertjbass/spindb/issues](https://github.com/robertjbass/spindb/issues)\n\n---\n\n**Questions? Found a bug? Have a feature request?**\n\nOpen an issue: [github.com/robertjbass/spindb/issues](https://github.com/robertjbass/spindb/issues)\n","readmeFilename":"README.md"}
![\"Layerbase\"](\"assets/layerbase-icon.svg\"){kind=icon}
\n Sponsored by Layerbase\n \n