spindb 0.12.3 → 0.13.4

package/README.md

@@ -7,7 +7,7 @@
 
 **The first npm CLI for running local databases without Docker.**
 
-Spin up PostgreSQL, MySQL, SQLite, and MongoDB instances for local development. No Docker daemon, no container networking, no volume mounts. Just databases running on localhost, ready in seconds.
+Spin up PostgreSQL, MySQL, SQLite, MongoDB, and Redis instances for local development. No Docker daemon, no container networking, no volume mounts. Just databases running on localhost, ready in seconds.
 
 ---
 
@@ -145,7 +145,7 @@ SpinDB downloads PostgreSQL server binaries automatically:
 - **macOS/Linux:** Pre-compiled binaries from the zonky.io project, hosted on Maven Central
 - **Windows:** Official binaries from EnterpriseDB (EDB)
 
-**Why download binaries instead of using system PostgreSQL?** You might want PostgreSQL 14 for one project and 18 for another. SpinDB lets you run different versions side-by-side without conflicts.
+**Why download binaries instead of using system PostgreSQL?** The [zonky.io project](https://github.com/zonkyio/embedded-postgres-binaries) provides pre-configured, portable PostgreSQL binaries—just extract and run. This lets you run PostgreSQL 14 for one project and 18 for another, side-by-side, without conflicts. No other database engine has an equivalent portable distribution.
 
 **Client tools required:** You still need `psql`, `pg_dump`, and `pg_restore` installed on your system for some operations (connecting, backups, restores). SpinDB can install these for you:
 
@@ -162,7 +162,7 @@ spindb deps install --engine postgresql
 | Default user | `root` |
 | Binary source | System installation |
 
-Unlike PostgreSQL, SpinDB uses your system's MySQL installation. This is because MySQL doesn't have a nice cross-platform binary distribution like zonky.io provides for PostgreSQL.
+Unlike PostgreSQL, SpinDB uses your system's MySQL installation. While Oracle provides MySQL binary downloads, they require system libraries and configuration—there's no "unzip and run" distribution like zonky.io provides for PostgreSQL. For most local development, a single system-installed MySQL version works well.
 
 ```bash
 # macOS
@@ -219,7 +219,7 @@ spindb connect mydb --litecli
 | Default user | None (no auth by default) |
 | Binary source | System installation |
 
-Like MySQL, SpinDB uses your system's MongoDB installation. MongoDB binaries aren't available as a single cross-platform download, so you'll need to install MongoDB via your package manager.
+Like MySQL, SpinDB uses your system's MongoDB installation. While MongoDB provides official binary downloads, they require additional configuration and system dependencies. SpinDB relies on your package manager to handle this setup.
 
 ```bash
 # macOS
@@ -240,20 +240,57 @@ MongoDB uses JavaScript for queries instead of SQL. When using `spindb run`, pas
 
 ```bash
 # Insert a document
-spindb run mydb --sql "db.users.insertOne({name: 'Alice', email: 'alice@example.com'})"
+spindb run mydb -c "db.users.insertOne({name: 'Alice', email: 'alice@example.com'})"
 
 # Query documents
-spindb run mydb --sql "db.users.find().pretty()"
+spindb run mydb -c "db.users.find().pretty()"
 
 # Run a JavaScript file
 spindb run mydb --file ./scripts/seed.js
 ```
 
-### Planned Engines
+#### Redis
 
-| Engine | Type | Status |
-|--------|------|--------|
-| Redis | In-memory key-value | Planned for v1.2 |
+| | |
+|---|---|
+| Versions | 6, 7, 8 |
+| Default port | 6379 |
+| Default user | None (no auth by default) |
+| Binary source | System installation |
+
+Like MySQL and MongoDB, SpinDB uses your system's Redis installation. Redis provides embeddable binaries, but system packages are more reliable for handling dependencies and platform-specific setup.
+
+```bash
+# macOS
+brew install redis
+
+# Ubuntu/Debian
+sudo apt install redis-server redis-tools
+
+# Windows (Chocolatey)
+choco install redis
+
+# Check if SpinDB can find Redis
+spindb deps check --engine redis
+```
+
+Redis uses numbered databases (0-15) instead of named databases. When using `spindb run`, pass Redis commands:
+
+```bash
+# Set a key
+spindb run myredis -c "SET mykey myvalue"
+
+# Get a key
+spindb run myredis -c "GET mykey"
+
+# Run a Redis command file
+spindb run myredis --file ./scripts/seed.redis
+
+# Use iredis for enhanced shell experience
+spindb connect myredis --iredis
+```
+
+**Note:** Redis doesn't support remote dump/restore. Creating containers from remote Redis connection strings is not supported. Use `backup` and `restore` commands for data migration.
 
 ---
 
@@ -267,7 +304,7 @@ spindb run mydb --file ./scripts/seed.js
 spindb create mydb                           # PostgreSQL (default)
 spindb create mydb --engine mysql            # MySQL
 spindb create mydb --engine sqlite           # SQLite (file-based)
-spindb create mydb --version 16              # Specific PostgreSQL version
+spindb create mydb --db-version 16           # Specific PostgreSQL version
 spindb create mydb --port 5433               # Custom port
 spindb create mydb --database my_app         # Custom database name
 spindb create mydb --no-start                # Create without starting
@@ -291,10 +328,10 @@ spindb create mydb --from "postgresql://user:pass@host:5432/production"
 
 | Option | Description |
 |--------|-------------|
-| `--engine`, `-e` | Database engine (`postgresql`, `mysql`, `sqlite`) |
-| `--version`, `-v` | Engine version |
+| `--engine`, `-e` | Database engine (`postgresql`, `mysql`, `sqlite`, `mongodb`, `redis`) |
+| `--db-version` | Engine version (e.g., 17 for PostgreSQL, 8 for Redis) |
 | `--port`, `-p` | Port number (not applicable for SQLite) |
-| `--database`, `-d` | Primary database name |
+| `--database`, `-d` | Primary database name (Redis uses 0-15) |
 | `--path` | File path for SQLite databases |
 | `--max-connections` | Maximum database connections (default: 200) |
 | `--from` | Restore from backup file or connection string |
@@ -355,16 +392,20 @@ spindb connect mydb --install-mycli
 spindb connect mydb --install-tui
 ```
 
-#### `run` - Execute SQL/scripts
+#### `run` - Execute SQL/scripts/commands
 
 ```bash
-spindb run mydb script.sql                    # Run a SQL file
-spindb run mydb --sql "SELECT * FROM users"   # Run inline SQL
-spindb run mydb seed.sql --database my_app    # Target specific database
+spindb run mydb script.sql                  # Run a SQL file
+spindb run mydb -c "SELECT * FROM users"    # Run inline SQL
+spindb run mydb seed.sql --database my_app  # Target specific database
 
 # MongoDB uses JavaScript instead of SQL
-spindb run mydb seed.js                                    # Run a JavaScript file
-spindb run mydb --sql "db.users.find().pretty()"           # Run inline JavaScript
+spindb run mydb seed.js                               # Run a JavaScript file
+spindb run mydb -c "db.users.find().pretty()"         # Run inline JavaScript
+
+# Redis uses Redis commands
+spindb run myredis -c "SET foo bar"                   # Run inline command
+spindb run myredis seed.redis                         # Run command file
 ```
 
 #### `url` - Get connection string
@@ -388,17 +429,24 @@ spindb backup mydb --output ./backups/      # Custom directory
 spindb backup mydb --database my_app        # Backup specific database
 ```
 
-Backup formats:
+Backup formats (vary by engine):
 
 ```bash
-spindb backup mydb --format sql     # Plain SQL (.sql)
-spindb backup mydb --format dump    # Compressed (.dump for PG, .sql.gz for MySQL)
+spindb backup mydb --format sql     # Plain SQL (.sql) or text commands (.redis)
+spindb backup mydb --format dump    # Binary format (.dump for PG, .sql.gz for MySQL, .rdb for Redis)
 
 # Shorthand
 spindb backup mydb --sql
 spindb backup mydb --dump
 ```
 
+Format by engine:
+- PostgreSQL: `.sql` (plain SQL) / `.dump` (pg_dump custom)
+- MySQL: `.sql` (plain SQL) / `.sql.gz` (compressed SQL)
+- SQLite: `.sql` (plain SQL) / `.sqlite` (binary copy)
+- MongoDB: `.bson` (BSON dump) / `.archive` (compressed archive)
+- Redis: `.redis` (text commands) / `.rdb` (RDB snapshot)
+
 <details>
 <summary>All options</summary>
 
@@ -414,6 +462,27 @@ spindb backup mydb --dump
 
 </details>
 
+#### `backups` - List backup files
+
+```bash
+spindb backups                       # List backups in current directory
+spindb backups ./data                # List backups in specific directory
+spindb backups --all                 # Include ~/.spindb/backups
+spindb backups --limit 50            # Show more results
+spindb backups --json                # JSON output
+```
+
+<details>
+<summary>All options</summary>
+
+| Option | Description |
+|--------|-------------|
+| `--all`, `-a` | Include backups from `~/.spindb/backups` |
+| `--limit`, `-n` | Limit number of results (default: 20) |
+| `--json`, `-j` | Output as JSON |
+
+</details>
+
 #### `restore` - Restore from backup
 
 ```bash
@@ -447,6 +516,78 @@ spindb info mydb
 
 </details>
 
+#### Backup & Restore Format Reference
+
+Each engine has specific backup formats and restore behaviors:
+
+<details>
+<summary>PostgreSQL</summary>
+
+| Format | Extension | Tool | Notes |
+|--------|-----------|------|-------|
+| SQL | `.sql` | pg_dump | Plain text SQL, human-readable |
+| Custom | `.dump` | pg_dump -Fc | Compressed, supports parallel restore |
+
+**Restore behavior:** Creates new database or replaces existing. Uses `pg_restore` for `.dump`, `psql` for `.sql`.
+
+</details>
+
+<details>
+<summary>MySQL</summary>
+
+| Format | Extension | Tool | Notes |
+|--------|-----------|------|-------|
+| SQL | `.sql` | mysqldump | Plain text SQL |
+| Compressed | `.sql.gz` | mysqldump + gzip | Gzip compressed SQL |
+
+**Restore behavior:** Creates new database or replaces existing. Pipes to `mysql` client.
+
+</details>
+
+<details>
+<summary>SQLite</summary>
+
+| Format | Extension | Tool | Notes |
+|--------|-----------|------|-------|
+| SQL | `.sql` | .dump | Plain text SQL |
+| Binary | `.sqlite` | File copy | Exact copy of database file |
+
+**Restore behavior:** Creates new file or replaces existing.
+
+</details>
+
+<details>
+<summary>MongoDB</summary>
+
+| Format | Extension | Tool | Notes |
+|--------|-----------|------|-------|
+| BSON | `.bson` | mongodump | Binary JSON per collection |
+| Archive | `.archive` | mongodump --archive | Single compressed file |
+
+**Restore behavior:** Creates new database or replaces existing. Uses `mongorestore`.
+
+</details>
+
+<details>
+<summary>Redis</summary>
+
+| Format | Extension | Tool | Notes |
+|--------|-----------|------|-------|
+| RDB | `.rdb` | BGSAVE | Binary snapshot, requires restart |
+| Text | `.redis` | Custom | Human-readable Redis commands |
+
+**Text format detection:** Files are detected as Redis text commands if they contain valid Redis commands (SET, HSET, DEL, etc.), regardless of file extension. This allows restoring files like `users.txt` or `data` without renaming.
+
+**Restore behavior:**
+- **RDB (`.rdb`):** Requires stopping Redis, copies file to data directory, restart loads data
+- **Text (`.redis`):** Pipes commands to running Redis instance. Prompts for:
+  - **Replace all:** Runs `FLUSHDB` first (clean slate)
+  - **Merge:** Adds/updates keys, keeps existing keys not in backup
+
+**Note:** Redis uses numbered databases (0-15) that always exist. "Create new database" is not applicable.
+
+</details>
+
 ### Container Management
 
 #### `list` - List all containers
@@ -596,7 +737,7 @@ SpinDB supports enhanced database shells that provide features like auto-complet
 | MySQL | `mysql` | `mycli` | `usql` |
 | SQLite | `sqlite3` | `litecli` | `usql` |
 | MongoDB | `mongosh` | - | `usql` |
-| Redis (planned) | `redis-cli` | `iredis` | - |
+| Redis | `redis-cli` | `iredis` | - |
 
 **pgcli / mycli** provide:
 - Intelligent auto-completion (tables, columns, keywords)
@@ -658,7 +799,7 @@ Native processes mean instant startup and no virtualization overhead.
 └── mydb.sqlite                             # Created with: spindb create mydb -e sqlite
 ```
 
-### How Data Persists
+### Data Persistence
 
 SpinDB runs databases as **native processes** on your machine. When you start a container:
 
@@ -676,21 +817,68 @@ When you stop a container:
 
 **Your data is never deleted unless you explicitly delete the container.**
 
+#### Persistence by Engine
+
+Each database engine has its own persistence mechanism:
+
+| Engine | Mechanism | Durability |
+|--------|-----------|------------|
+| PostgreSQL | Write-Ahead Logging (WAL) | Every commit is immediately durable |
+| MySQL | InnoDB transaction logs | Every commit is immediately durable |
+| SQLite | File-based transactions | Every commit is immediately durable |
+| MongoDB | WiredTiger with journaling | Writes journaled before acknowledged |
+| Redis | RDB snapshots | Periodic snapshots (see below) |
+
+**PostgreSQL, MySQL, MongoDB:** These engines use transaction logs or journaling. Every committed write is guaranteed to survive a crash or unexpected shutdown.
+
+**SQLite:** As a file-based database, SQLite writes directly to disk on each commit. No server process means no risk of losing in-flight data.
+
+**Redis:** SpinDB configures Redis with RDB (Redis Database) snapshots:
+- Save after 900 seconds if at least 1 key changed
+- Save after 300 seconds if at least 10 keys changed
+- Save after 60 seconds if at least 10,000 keys changed
+
+This means Redis may lose up to ~60 seconds of writes on an unexpected crash. For local development, this trade-off (speed over strict durability) is typically acceptable. If you need stronger guarantees, use `spindb backup` before stopping work.
+
 ### Binary Sources
 
 **PostgreSQL:** Server binaries are downloaded automatically:
 - **macOS/Linux:** From [zonky.io/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries), hosted on Maven Central
 - **Windows:** From [EnterpriseDB (EDB)](https://www.enterprisedb.com/download-postgresql-binaries), official PostgreSQL distributions
 
-**MySQL:** Uses your system's MySQL installation. SpinDB detects binaries from Homebrew (macOS), apt/pacman (Linux), or Chocolatey/winget/Scoop (Windows).
+**MySQL/MongoDB/Redis:** Uses your system installation. SpinDB detects binaries from Homebrew (macOS), apt/pacman (Linux), or Chocolatey/winget/Scoop (Windows).
+
+### Why Precompiled Binaries for PostgreSQL, but System Installs for Others?
+
+This isn't a preference—it's a practical reality of what's available.
+
+**PostgreSQL has an excellent embedded binary distribution.** The [zonky.io](https://github.com/zonkyio/embedded-postgres-binaries) project maintains minimal, self-contained PostgreSQL server binaries specifically designed for embedding:
+
+- Cross-platform (macOS Intel/ARM, Linux x64/ARM, Windows)
+- Hosted on Maven Central (highly reliable CDN)
+- ~45 MB per version
+- Actively maintained with new PostgreSQL releases
+
+This makes multi-version support trivial: need PostgreSQL 14 for a legacy project and 18 for a new one? SpinDB downloads both, and they run side-by-side without conflicts.
+
+**No equivalent exists for MySQL, MongoDB, or Redis.** None of these databases have a comparable embedded binary project:
+
+- **MySQL:** Oracle distributes MySQL as large installers with system dependencies, not embeddable binaries. There's no "zonky.io for MySQL."
+- **MongoDB:** Server binaries are several hundred MB and aren't designed for portable distribution.
+- **Redis:** While Redis is small (~6-12 MB), there's no official portable distribution. Community Windows ports exist, but macOS/Linux rely on system packages.
+
+For these databases, system packages (Homebrew, apt, choco) are the most reliable option. They handle dependencies, platform quirks, and security updates. SpinDB simply orchestrates what's already installed.
+
+**Does this limit multi-version support?** Yes, for MySQL/MongoDB/Redis you get whatever version your package manager provides. In practice, this is rarely a problem—developers seldom need multiple versions of these databases simultaneously. If zonky.io-style distributions emerged for other databases, SpinDB could adopt them.
 
 ---
 
 ## Limitations
 
-- **Client tools required** - `psql` and `mysql` must be installed separately for some operations
+- **Client tools required** - `psql`, `mysql`, `mongosh`, and `redis-cli` must be installed separately for some operations (connecting, backups, restores)
 - **Local only** - Databases bind to `127.0.0.1`; remote connections planned for v1.1
-- **MySQL requires system install** - Unlike PostgreSQL, we don't download MySQL binaries
+- **Single version for MySQL/MongoDB/Redis** - Unlike PostgreSQL, MySQL, MongoDB, and Redis use system installations, so you're limited to one version per machine (see [Why Precompiled Binaries for PostgreSQL?](#why-precompiled-binaries-for-postgresql-but-system-installs-for-others))
+- **Redis remote dump not supported** - Redis doesn't support creating containers from remote connection strings. Use backup/restore for data migration.
 
 ---
 
@@ -704,15 +892,28 @@ See [TODO.md](TODO.md) for the full roadmap.
 - Secrets management (macOS Keychain)
 
 ### v1.2 - Additional Engines
-- Redis (in-memory key-value)
-- MongoDB (document database)
 - MariaDB as standalone engine
+- CockroachDB (distributed SQL)
 
 ### v1.3 - Advanced Features
 - Container templates
 - Scheduled backups
 - Import from Docker
 
+### Possible Future Engines
+
+These engines are under consideration but not yet on the roadmap. Community interest and feasibility will determine priority:
+
+| Engine | Type | Notes |
+|--------|------|-------|
+| **DuckDB** | Embedded analytical | File-based like SQLite, popular for data/analytics work |
+| **libSQL** | Embedded relational | SQLite fork by Turso with replication and edge support |
+| **Valkey** | Key-value store | Redis fork (post-license change), growing adoption |
+| **Meilisearch** | Search engine | Developer-friendly search, good binary distribution |
+| **Elasticsearch/OpenSearch** | Search engine | Full-text search, common in web applications |
+| **Neo4j** | Graph database | Most popular graph database |
+| **InfluxDB** | Time-series | IoT, metrics, and monitoring use cases |
+
 ---
 
 ## Troubleshooting
@@ -775,6 +976,14 @@ SpinDB wouldn't be possible without:
 
 ---
 
+## Related Work
+
+We're actively contributing to the broader embedded database ecosystem:
+
+- **[hostdb](https://github.com/robertjbass/hostdb)** - A companion project providing downloadable database binaries (Redis, MySQL/MariaDB, etc.) as GitHub releases. This will enable SpinDB to offer multi-version support for additional engines beyond PostgreSQL.
+
+---
+
 ## License
 
 [PolyForm Noncommercial 1.0.0](LICENSE)

package/cli/commands/backup.ts

@@ -29,11 +29,39 @@ function generateDefaultFilename(
 }
 
 function getExtension(format: 'sql' | 'dump', engine: string): string {
+  // Handle 'sql' format (human-readable option)
   if (format === 'sql') {
-    return '.sql'
+    // MongoDB uses BSON directory format for 'sql' choice
+    return engine === 'mongodb' ? '' : '.sql'
+  }
+
+  // Handle 'dump' format (binary/compressed option)
+  switch (engine) {
+    case 'mysql':
+      return '.sql.gz'
+    case 'sqlite':
+      return '.sqlite'
+    case 'mongodb':
+      return '.archive'
+    case 'redis':
+      return '.rdb'
+    case 'postgresql':
+    default:
+      return '.dump'
   }
-  // MySQL dump is gzipped SQL, PostgreSQL dump is custom format
-  return engine === 'mysql' ? '.sql.gz' : '.dump'
+}
+
+function getFormatDescription(format: 'sql' | 'dump', engine: string): string {
+  if (engine === 'redis') {
+    return 'RDB snapshot'
+  }
+  if (engine === 'mongodb') {
+    return format === 'sql' ? 'BSON directory' : 'archive'
+  }
+  if (engine === 'sqlite') {
+    return format === 'sql' ? 'SQL' : 'binary'
+  }
+  return format === 'sql' ? 'SQL' : 'dump'
 }
 
 export const backupCommand = new Command('backup')
@@ -195,8 +223,9 @@ export const backupCommand = new Command('backup')
         const outputDir = options.output || process.cwd()
         const outputPath = join(outputDir, `${filename}${extension}`)
 
+        const formatDesc = getFormatDescription(format, engineName)
         const backupSpinner = createSpinner(
-          `Creating ${format === 'sql' ? 'SQL' : 'dump'} backup of "${databaseName}"...`,
+          `Creating ${formatDesc} backup of "${databaseName}"...`,
         )
         backupSpinner.start()
 
@@ -222,11 +251,8 @@ export const backupCommand = new Command('backup')
           console.log()
           console.log(uiSuccess('Backup complete'))
           console.log()
-          console.log(chalk.gray('  File:'), chalk.cyan(result.path))
-          console.log(
-            chalk.gray('  Size:'),
-            chalk.white(formatBytes(result.size)),
-          )
+          console.log(chalk.gray('  Saved to:'), chalk.cyan(result.path))
+          console.log(chalk.gray('  Size:'), chalk.white(formatBytes(result.size)))
           console.log(chalk.gray('  Format:'), chalk.white(result.format))
           console.log()
         }