spindb 0.22.0 → 0.23.5

package/README.md

@@ -7,7 +7,7 @@
 
 **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 11 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.
+SpinDB is a universal database management tool that combines a package manager, a unified API, and native client tooling for 12 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
@@ -48,7 +48,7 @@ One consistent interface across SQL databases, document stores, key-value stores
 
 ```bash
 # Same commands work for ANY database
-spindb create mydb --engine [postgresql|mysql|mariadb|mongodb|redis|valkey|clickhouse|sqlite|duckdb|qdrant|meilisearch]
+spindb create mydb --engine [postgresql|mysql|mariadb|mongodb|ferretdb|redis|valkey|clickhouse|sqlite|duckdb|qdrant|meilisearch]
 spindb start mydb
 spindb connect mydb
 spindb backup mydb
@@ -70,7 +70,7 @@ spindb run mydb -c "SELECT * FROM system.tables"        # ClickHouse
 
 ## Platform Coverage
 
-SpinDB works across **11 database engines** and **5 platform architectures** with a **single, consistent API**.
+SpinDB works across **12 database engines** and **5 platform architectures** with a **single, consistent API**.
 
 | Database | macOS ARM64 | macOS Intel | Linux x64 | Linux ARM64 | Windows x64 |
 |----------|:-----------:|:-----------:|:---------:|:-----------:|:-----------:|
@@ -80,13 +80,14 @@ SpinDB works across **11 database engines** and **5 platform architectures** wit
 | 🪶 **SQLite** | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🦆 **DuckDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🍃 **MongoDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 🦔 **FerretDB** | ✅ | ✅ | ✅ | ✅ | ❌ |
 | 🔴 **Redis** | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🔷 **Valkey** | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🏠 **ClickHouse** | ✅ | ✅ | ✅ | ✅ | ❌ |
 | 🧭 **Qdrant** | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🔍 **Meilisearch** | ✅ | ✅ | ✅ | ✅ | ✅ |
 
-**54 combinations. One CLI. Zero configuration.**
+**58 combinations. One CLI. Zero configuration.**
 
 ---
 
@@ -165,7 +166,7 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 | Feature | SpinDB | Docker | DBngin | Postgres.app | XAMPP |
 |---------|--------|--------|--------|--------------|-------|
 | No Docker required | ✅ | ❌ | ✅ | ✅ | ✅ |
-| Multiple DB engines | ✅ 11 engines | ✅ Unlimited | ✅ 3 engines | ❌ PostgreSQL only | ⚠️ MySQL only |
+| Multiple DB engines | ✅ 12 engines | ✅ Unlimited | ✅ 3 engines | ❌ PostgreSQL only | ⚠️ MySQL only |
 | CLI-first | ✅ | ✅ | ❌ GUI-first | ❌ GUI-first | ❌ GUI-first |
 | Multiple versions | ✅ | ✅ | ✅ | ✅ | ❌ |
 | Clone databases | ✅ | Manual | ✅ | ❌ | ❌ |
@@ -179,7 +180,7 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 
 ## Supported Databases
 
-SpinDB supports **11 database engines** with **multiple versions** for each:
+SpinDB supports **12 database engines** with **multiple versions** for each:
 
 | Engine | Type | Versions | Default Port | Query Language |
 |--------|------|----------|--------------|----------------|
@@ -189,6 +190,7 @@ SpinDB supports **11 database engines** with **multiple versions** for each:
 | 🪶 **SQLite** | Embedded (SQL) | 3 | N/A (file-based) | SQL |
 | 🦆 **DuckDB** | Embedded OLAP | 1.4.3 | N/A (file-based) | SQL |
 | 🍃 **MongoDB** | Document Store | 7.0, 8.0, 8.2 | 27017 | JavaScript (mongosh) |
+| 🦔 **FerretDB** | Document Store | 2 | 27017 | JavaScript (mongosh) |
 | 🔴 **Redis** | Key-Value Store | 7, 8 | 6379 | Redis commands |
 | 🔷 **Valkey** | Key-Value Store | 8, 9 | 6379 | Redis commands |
 | 🏠 **ClickHouse** | Columnar OLAP | 25.12 | 9000 (TCP), 8123 (HTTP) | SQL (ClickHouse dialect) |
@@ -197,7 +199,7 @@ SpinDB supports **11 database engines** with **multiple versions** for each:
 
 ### Engine Categories
 
-**Server-Based Databases** (PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Valkey, ClickHouse, Qdrant, Meilisearch):
+**Server-Based Databases** (PostgreSQL, MySQL, MariaDB, MongoDB, FerretDB, Redis, Valkey, ClickHouse, Qdrant, Meilisearch):
 - Start/stop server processes
 - Bind to localhost ports
 - Data stored in `~/.spindb/containers/{engine}/{name}/`
@@ -337,8 +339,10 @@ spindb config show                              # Show current config
 spindb config detect                            # Re-detect tool paths
 spindb config update-check on                   # Enable update notifications
 
-# System health
+# Doctor
 spindb doctor                                   # Interactive health check
+spindb doctor --fix                             # Auto-fix all issues
+spindb doctor --dry-run                         # Preview fixes without applying
 spindb doctor --json                            # JSON output
 
 # Version management
@@ -481,6 +485,29 @@ spindb connect logs
 **Query language:** JavaScript (via `mongosh`)
 **Tools:** `mongod`, `mongosh`, `mongodump`, `mongorestore` (included)
 
+### FerretDB 🦔
+
+```bash
+# Create FerretDB database (MongoDB-compatible, PostgreSQL backend)
+spindb create docs --engine ferretdb
+
+# Same MongoDB queries work
+spindb run docs -c "db.users.insertOne({name: 'Alice'})"
+spindb run docs -c "db.users.find().pretty()"
+
+# Connect with mongosh
+spindb connect docs
+```
+
+**Version:** 2 (2.7.0)
+**Platforms:** macOS, Linux (no Windows support)
+**Architecture:** FerretDB proxy + PostgreSQL with DocumentDB extension
+**Query language:** JavaScript (via `mongosh`)
+**Backups:** Uses `pg_dump` on embedded PostgreSQL backend
+**Tools:** `ferretdb`, `mongosh` (for client connections), `pg_dump`/`pg_restore` (bundled with embedded PostgreSQL)
+
+FerretDB is a MongoDB-compatible database that stores data in PostgreSQL. It's useful when you want MongoDB's API but PostgreSQL's reliability and SQL access to your data.
+
 ### Redis 🔴 & Valkey 🔷
 
 ```bash
@@ -568,6 +595,7 @@ SpinDB supports enhanced database shells with auto-completion, syntax highlighti
 | SQLite | `sqlite3` | `litecli` | `usql` |
 | DuckDB | `duckdb` | - | `usql` |
 | MongoDB | `mongosh` | - | - |
+| FerretDB | `mongosh` | - | - |
 | Redis | `redis-cli` | `iredis` | - |
 | Valkey | `valkey-cli` | `iredis` (compatible) | - |
 | ClickHouse | `clickhouse-client` | - | `usql` |
@@ -779,7 +807,6 @@ See [TODO.md](TODO.md) for the complete roadmap.
 
 ### v1.2 - Additional Engines
 - **CockroachDB** - Distributed PostgreSQL-compatible database
-- **FerretDB** - MongoDB-compatible database built on PostgreSQL
 
 ### v1.3 - Advanced Features
 - Container templates for common configurations
@@ -803,6 +830,7 @@ The following engines may be added based on community interest:
 
 - **Local only** - Databases bind to `127.0.0.1`. Remote connection support planned for v1.1.
 - **ClickHouse Windows** - Not supported (hostdb doesn't build for Windows).
+- **FerretDB Windows** - Not supported (postgresql-documentdb has startup issues on Windows).
 - **Qdrant & Meilisearch** - Use REST API instead of CLI shell. Access via HTTP at the configured port.
 
 ---

package/cli/bin.ts

@@ -4,5 +4,7 @@ import { run } from './index'
 
 run().catch((err) => {
   console.error(err)
+  console.error('')
+  console.error('If this error persists, try running: spindb doctor --fix')
   process.exit(1)
 })

package/cli/commands/create.ts

@@ -13,14 +13,14 @@ import {
   promptConfirm,
 } from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
-import { header, uiError, connectionBox } from '../ui/theme'
+import { header, connectionBox } from '../ui/theme'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { getMissingDependencies } from '../../core/dependency-manager'
 import { platformService } from '../../core/platform-service'
 import { startWithRetry } from '../../core/start-with-retry'
 import { TransactionManager } from '../../core/transaction-manager'
-import { isValidDatabaseName } from '../../core/error-handler'
+import { isValidDatabaseName, exitWithError } from '../../core/error-handler'
 import { resolve } from 'path'
 import { Engine } from '../../types'
 import type { BaseEngine } from '../../engines/base-engine'
@@ -49,8 +49,10 @@ async function createSqliteContainer(
   const missingDeps = await getMissingDependencies('sqlite')
   if (missingDeps.length > 0) {
     if (json) {
-      console.log(JSON.stringify({ error: `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}` }))
-      process.exit(1)
+      return exitWithError({
+        message: `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
+        json: true,
+      })
     }
     depsSpinner?.warn(
       `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
@@ -60,7 +62,7 @@ async function createSqliteContainer(
       'sqlite',
     )
     if (!installed) {
-      process.exit(1)
+      return exitWithError({ message: 'Required tools not installed' })
     }
   } else {
     depsSpinner?.succeed('Required tools available')
@@ -69,8 +71,10 @@ async function createSqliteContainer(
   // Check if container already exists
   if (await containerManager.exists(containerName)) {
     if (json) {
-      console.log(JSON.stringify({ error: `Container "${containerName}" already exists` }))
-      process.exit(1)
+      return exitWithError({
+        message: `Container "${containerName}" already exists`,
+        json: true,
+      })
     }
     while (await containerManager.exists(containerName)) {
       console.log(chalk.yellow(`  Container "${containerName}" already exists.`))
@@ -84,12 +88,10 @@ async function createSqliteContainer(
 
   // Check if file already exists
   if (existsSync(absolutePath)) {
-    if (json) {
-      console.log(JSON.stringify({ error: `File already exists: ${absolutePath}` }))
-    } else {
-      console.error(uiError(`File already exists: ${absolutePath}`))
-    }
-    process.exit(1)
+    return exitWithError({
+      message: `File already exists: ${absolutePath}`,
+      json,
+    })
   }
 
   const createSpinnerInstance = json ? null : createSpinner('Creating SQLite database...')
@@ -196,8 +198,10 @@ async function createDuckDBContainer(
   const missingDeps = await getMissingDependencies('duckdb')
   if (missingDeps.length > 0) {
     if (json) {
-      console.log(JSON.stringify({ error: `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}` }))
-      process.exit(1)
+      return exitWithError({
+        message: `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
+        json: true,
+      })
     }
     depsSpinner?.warn(
       `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
@@ -207,7 +211,7 @@ async function createDuckDBContainer(
       'duckdb',
     )
     if (!installed) {
-      process.exit(1)
+      return exitWithError({ message: 'Required tools not installed' })
     }
   } else {
     depsSpinner?.succeed('Required tools available')
@@ -216,8 +220,10 @@ async function createDuckDBContainer(
   // Check if container already exists
   if (await containerManager.exists(containerName)) {
     if (json) {
-      console.log(JSON.stringify({ error: `Container "${containerName}" already exists` }))
-      process.exit(1)
+      return exitWithError({
+        message: `Container "${containerName}" already exists`,
+        json: true,
+      })
     }
     while (await containerManager.exists(containerName)) {
       console.log(chalk.yellow(`  Container "${containerName}" already exists.`))
@@ -231,12 +237,10 @@ async function createDuckDBContainer(
 
   // Check if file already exists
   if (existsSync(absolutePath)) {
-    if (json) {
-      console.log(JSON.stringify({ error: `File already exists: ${absolutePath}` }))
-    } else {
-      console.error(uiError(`File already exists: ${absolutePath}`))
-    }
-    process.exit(1)
+    return exitWithError({
+      message: `File already exists: ${absolutePath}`,
+      json,
+    })
   }
 
   const createSpinnerInstance = json ? null : createSpinner('Creating DuckDB database...')
@@ -379,7 +383,7 @@ export const createCommand = new Command('create')
   .argument('[name]', 'Container name')
   .option(
     '-e, --engine <engine>',
-    'Database engine (postgresql, mysql, mariadb, sqlite, duckdb, mongodb, redis, valkey, clickhouse, qdrant, meilisearch)',
+    'Database engine (postgresql, mysql, mariadb, sqlite, duckdb, mongodb, ferretdb, redis, valkey, clickhouse, qdrant, meilisearch)',
   )
   .option('--db-version <version>', 'Database version (e.g., 17, 8.0)')
   .option('-d, --database <database>', 'Database name')
@@ -431,22 +435,10 @@ export const createCommand = new Command('create')
           const locationInfo = detectLocationType(options.from)
 
           if (locationInfo.type === 'not_found') {
-            if (options.json) {
-              console.log(JSON.stringify({ error: `Location not found: ${options.from}` }))
-            } else {
-              console.error(uiError(`Location not found: ${options.from}`))
-              console.log(
-                chalk.gray(
-                  '  Provide a valid file path or connection string:',
-                ),
-              )
-              console.log(
-                chalk.gray(
-                  '  postgresql://, mysql://, mongodb://, redis://, sqlite://, duckdb://',
-                ),
-              )
-            }
-            process.exit(1)
+            return exitWithError({
+              message: `Location not found: ${options.from}. Provide a valid file path or connection string (postgresql://, mysql://, redis://, sqlite://, duckdb://)`,
+              json: options.json,
+            })
           }
 
           restoreLocation = options.from
@@ -464,16 +456,10 @@ export const createCommand = new Command('create')
           }
 
           if (options.start === false) {
-            if (options.json) {
-              console.log(JSON.stringify({ error: 'Cannot use --no-start with --from (restore requires running container)' }))
-            } else {
-              console.error(
-                uiError(
-                  'Cannot use --no-start with --from (restore requires running container)',
-                ),
-              )
-            }
-            process.exit(1)
+            return exitWithError({
+              message: 'Cannot use --no-start with --from (restore requires running container)',
+              json: options.json,
+            })
           }
         }
 
@@ -486,8 +472,7 @@ export const createCommand = new Command('create')
         if (!containerName) {
           // JSON mode requires container name argument
           if (options.json) {
-            console.log(JSON.stringify({ error: 'Container name is required' }))
-            process.exit(1)
+            return exitWithError({ message: 'Container name is required', json: true })
           }
 
           const answers = await promptCreateOptions()
@@ -504,35 +489,26 @@ export const createCommand = new Command('create')
           // Validate Redis/Valkey database is a pure integer string 0-15
           // Reject decimals ("1.5"), scientific notation ("1e2"), and trailing garbage ("5abc")
           if (!/^[0-9]+$/.test(database)) {
-            const errorMsg = 'Redis/Valkey database must be an integer between 0 and 15'
-            if (options.json) {
-              console.log(JSON.stringify({ error: errorMsg }))
-            } else {
-              console.error(uiError(errorMsg))
-            }
-            process.exit(1)
+            return exitWithError({
+              message: 'Redis/Valkey database must be an integer between 0 and 15',
+              json: options.json,
+            })
           }
           const dbIndex = parseInt(database, 10)
           if (dbIndex < 0 || dbIndex > 15) {
-            const errorMsg = 'Redis/Valkey database must be an integer between 0 and 15'
-            if (options.json) {
-              console.log(JSON.stringify({ error: errorMsg }))
-            } else {
-              console.error(uiError(errorMsg))
-            }
-            process.exit(1)
+            return exitWithError({
+              message: 'Redis/Valkey database must be an integer between 0 and 15',
+              json: options.json,
+            })
           }
         } else {
           database = database ?? containerName.replace(/-/g, '_')
           // Validate database name to prevent SQL injection
           if (!isValidDatabaseName(database)) {
-            const errorMsg = 'Database name must start with a letter and contain only letters, numbers, and underscores'
-            if (options.json) {
-              console.log(JSON.stringify({ error: errorMsg }))
-            } else {
-              console.error(uiError(errorMsg))
-            }
-            process.exit(1)
+            return exitWithError({
+              message: 'Database name must start with a letter and contain only letters, numbers, and underscores',
+              json: options.json,
+            })
           }
         }
 
@@ -568,33 +544,28 @@ export const createCommand = new Command('create')
 
         // For server databases, validate --connect with --no-start
         if (options.connect && options.start === false) {
-          const errorMsg = 'Cannot use --no-start with --connect (connection requires running container)'
-          if (options.json) {
-            console.log(JSON.stringify({ error: errorMsg }))
-          } else {
-            console.error(uiError(errorMsg))
-          }
-          process.exit(1)
+          return exitWithError({
+            message: 'Cannot use --no-start with --connect (connection requires running container)',
+            json: options.json,
+          })
         }
 
         // In JSON mode, require explicit --start or --no-start flag to avoid interactive prompts
         if (options.json && options.start === undefined && !restoreLocation && !options.connect) {
-          const errorMsg = 'In JSON mode, you must specify --start or --no-start for server databases'
-          console.log(JSON.stringify({ error: errorMsg }))
-          process.exit(1)
+          return exitWithError({
+            message: 'In JSON mode, you must specify --start or --no-start for server databases',
+            json: true,
+          })
         }
 
         // Validate --max-connections if provided
         if (options.maxConnections) {
           const parsed = parseInt(options.maxConnections, 10)
           if (!Number.isFinite(parsed) || parsed <= 0) {
-            const errorMsg = 'Invalid --max-connections value: must be a positive integer'
-            if (options.json) {
-              console.log(JSON.stringify({ error: errorMsg }))
-            } else {
-              console.error(uiError(errorMsg))
-            }
-            process.exit(1)
+            return exitWithError({
+              message: 'Invalid --max-connections value: must be a positive integer',
+              json: options.json,
+            })
           }
         }
 
@@ -606,12 +577,11 @@ export const createCommand = new Command('create')
           port = parseInt(options.port, 10)
           const available = await portManager.isPortAvailable(port)
           if (!available) {
-            if (options.json) {
-              console.log(JSON.stringify({ error: `Port ${port} is already in use` }))
-            } else {
-              portSpinner?.fail(`Port ${port} is already in use`)
-            }
-            process.exit(1)
+            portSpinner?.fail(`Port ${port} is already in use`)
+            return exitWithError({
+              message: `Port ${port} is already in use`,
+              json: options.json,
+            })
           }
           portSpinner?.succeed(`Using port ${port}`)
         } else {
@@ -661,10 +631,10 @@ export const createCommand = new Command('create')
         if (missingDeps.length > 0) {
           // In JSON mode, error out instead of prompting
           if (options.json) {
-            console.log(JSON.stringify({
-              error: `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
-            }))
-            process.exit(1)
+            return exitWithError({
+              message: `Missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
+              json: true,
+            })
           }
 
           depsSpinner?.warn(
@@ -677,17 +647,14 @@ export const createCommand = new Command('create')
           )
 
           if (!installed) {
-            process.exit(1)
+            return exitWithError({ message: 'Required tools not installed' })
           }
 
           missingDeps = await getMissingDependencies(engine)
           if (missingDeps.length > 0) {
-            console.error(
-              uiError(
-                `Still missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
-              ),
-            )
-            process.exit(1)
+            return exitWithError({
+              message: `Still missing tools: ${missingDeps.map((d) => d.name).join(', ')}`,
+            })
           }
 
           console.log(chalk.green('  ✓ All required tools are now available'))
@@ -717,23 +684,23 @@ export const createCommand = new Command('create')
             )
             binarySpinner?.succeed(`${dbEngine.displayName} ${version} binaries ready`)
           } catch (error) {
+            binarySpinner?.fail(`${dbEngine.displayName} ${version} not available`)
             if (options.json) {
-              console.log(JSON.stringify({
-                error: `${dbEngine.displayName} ${version} not available`,
-              }))
-              process.exit(1)
+              return exitWithError({
+                message: `${dbEngine.displayName} ${version} not available`,
+                json: true,
+              })
             }
-            binarySpinner?.fail(`${dbEngine.displayName} ${version} not available`)
             throw error
           }
         }
 
         if (await containerManager.exists(containerName)) {
           if (options.json) {
-            console.log(JSON.stringify({
-              error: `Container "${containerName}" already exists`,
-            }))
-            process.exit(1)
+            return exitWithError({
+              message: `Container "${containerName}" already exists`,
+              json: true,
+            })
           }
           while (await containerManager.exists(containerName)) {
             console.log(
@@ -798,8 +765,14 @@ export const createCommand = new Command('create')
         } else if (options.start === false) {
           shouldStart = false
         } else {
-          console.log()
-          shouldStart = await promptConfirm(`Start ${containerName} now?`, true)
+          // In non-interactive mode (no TTY), default to not starting
+          // This allows scripts/CI to run without --no-start flag
+          if (!process.stdin.isTTY) {
+            shouldStart = false
+          } else {
+            console.log()
+            shouldStart = await promptConfirm(`Start ${containerName} now?`, true)
+          }
         }
 
         const config = await containerManager.getConfig(containerName)
@@ -918,23 +891,29 @@ export const createCommand = new Command('create')
                   e.message.includes('pg_dump not found') ||
                   e.message.includes('ENOENT')
                 ) {
+                  // In JSON mode, don't prompt - just exit with error
+                  if (options.json) {
+                    return exitWithError({ message: 'pg_dump not installed', json: true })
+                  }
                   const installed = await promptInstallDependencies('pg_dump')
                   if (!installed) {
-                    process.exit(1)
+                    return exitWithError({ message: 'pg_dump not installed', json: options.json })
                   }
                   continue
                 }
 
-                console.log()
-                console.error(uiError('pg_dump error:'))
-                console.log(chalk.gray(`  ${e.message}`))
-                process.exit(1)
+                return exitWithError({
+                  message: `pg_dump error: ${e.message}`,
+                  json: options.json,
+                })
               }
             }
 
             if (!dumpSuccess) {
-              console.error(uiError('Failed to create dump after retries'))
-              process.exit(1)
+              return exitWithError({
+                message: 'Failed to create dump after retries',
+                json: options.json,
+              })
             }
           } else {
             backupPath = restoreLocation
@@ -1049,8 +1028,7 @@ export const createCommand = new Command('create')
 
         if (matchingPattern) {
           if (options.json) {
-            console.log(JSON.stringify({ error: e.message }))
-            process.exit(1)
+            return exitWithError({ message: e.message, json: true })
           }
           const missingTool = matchingPattern.replace(' not found', '')
           const installed = await promptInstallDependencies(missingTool)
@@ -1059,15 +1037,10 @@ export const createCommand = new Command('create')
               chalk.yellow('  Please re-run your command to continue.'),
             )
           }
-          process.exit(1)
+          return exitWithError({ message: 'Missing required tools', json: options.json })
         }
 
-        if (options.json) {
-          console.log(JSON.stringify({ error: e.message }))
-        } else {
-          console.error(uiError(e.message))
-        }
-        process.exit(1)
+        return exitWithError({ message: e.message, json: options.json })
       } finally {
         if (tempDumpPath) {
           try {