spindb 0.19.5 → 0.21.3

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 9 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 10 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]
+spindb create mydb --engine [postgresql|mysql|mariadb|mongodb|redis|valkey|clickhouse|sqlite|duckdb|qdrant]
 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 **9 database engines** and **5 platform architectures** with a **single, consistent API**.
+SpinDB works across **10 database engines** and **5 platform architectures** with a **single, consistent API**.
 
 | Database | macOS ARM64 | macOS Intel | Linux x64 | Linux ARM64 | Windows x64 |
 |----------|:-----------:|:-----------:|:---------:|:-----------:|:-----------:|
@@ -83,8 +83,9 @@ SpinDB works across **9 database engines** and **5 platform architectures** with
 | 🔴 **Redis** | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🔷 **Valkey** | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🏠 **ClickHouse** | ✅ | ✅ | ✅ | ✅ | ❌ |
+| 🧭 **Qdrant** | ✅ | ✅ | ✅ | ✅ | ✅ |
 
-**44 combinations. One CLI. Zero configuration.**
+**49 combinations. One CLI. Zero configuration.**
 
 ---
 
@@ -163,7 +164,7 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 | Feature | SpinDB | Docker | DBngin | Postgres.app | XAMPP |
 |---------|--------|--------|--------|--------------|-------|
 | No Docker required | ✅ | ❌ | ✅ | ✅ | ✅ |
-| Multiple DB engines | ✅ 9 engines | ✅ Unlimited | ✅ 3 engines | ❌ PostgreSQL only | ⚠️ MySQL only |
+| Multiple DB engines | ✅ 10 engines | ✅ Unlimited | ✅ 3 engines | ❌ PostgreSQL only | ⚠️ MySQL only |
 | CLI-first | ✅ | ✅ | ❌ GUI-first | ❌ GUI-first | ❌ GUI-first |
 | Multiple versions | ✅ | ✅ | ✅ | ✅ | ❌ |
 | Clone databases | ✅ | Manual | ✅ | ❌ | ❌ |
@@ -177,7 +178,7 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 
 ## Supported Databases
 
-SpinDB supports **9 database engines** with **multiple versions** for each:
+SpinDB supports **10 database engines** with **multiple versions** for each:
 
 | Engine | Type | Versions | Default Port | Query Language |
 |--------|------|----------|--------------|----------------|
@@ -190,10 +191,11 @@ SpinDB supports **9 database engines** with **multiple versions** for each:
 | 🔴 **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) |
+| 🧭 **Qdrant** | Vector Search | 1 | 6333 (HTTP), 6334 (gRPC) | REST API |
 
 ### Engine Categories
 
-**Server-Based Databases** (PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Valkey, ClickHouse):
+**Server-Based Databases** (PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Valkey, ClickHouse, Qdrant):
 - Start/stop server processes
 - Bind to localhost ports
 - Data stored in `~/.spindb/containers/{engine}/{name}/`
@@ -269,8 +271,8 @@ psql $(spindb url mydb)
 spindb backup mydb                              # Auto-generated filename
 spindb backup mydb --name production-backup     # Custom name
 spindb backup mydb --output ./backups/          # Custom directory
-spindb backup mydb --format sql                 # SQL text format
-spindb backup mydb --format dump                # Binary format
+spindb backup mydb --format sql                 # SQL text format (PostgreSQL)
+spindb backup mydb --format custom              # Custom binary format (PostgreSQL)
 
 # Restore from backups
 spindb restore mydb backup.dump
@@ -307,6 +309,12 @@ spindb edit mydb --relocate ~/new/path          # Move SQLite/DuckDB file
 spindb logs mydb
 spindb logs mydb --follow                       # Follow mode (tail -f)
 spindb logs mydb -n 100                         # Last 100 lines
+
+# Manage database tracking (for external scripts)
+spindb databases list mydb                      # List tracked databases
+spindb databases add mydb analytics             # Add to tracking
+spindb databases remove mydb old_backup         # Remove from tracking
+spindb databases sync mydb oldname newname      # Sync after rename
 ```
 
 ### Engine & System Management
@@ -430,7 +438,7 @@ spindb create modern --engine postgresql --db-version 18
 
 # Backup formats
 spindb backup myapp --format sql      # Plain SQL (.sql)
-spindb backup myapp --format dump     # Binary custom format (.dump)
+spindb backup myapp --format custom   # Binary custom format (.dump)
 ```
 
 **Versions:** 15, 16, 17, 18
@@ -527,6 +535,23 @@ spindb run warehouse -c "SELECT * FROM system.tables"
 **Ports:** 9000 (native TCP), 8123 (HTTP)
 **Tools:** `clickhouse-client`, `clickhouse-server` (included)
 
+### Qdrant 🧭
+
+```bash
+# Create Qdrant database (vector similarity search)
+spindb create vectors --engine qdrant
+spindb start vectors
+
+# Access via REST API
+curl http://127.0.0.1:6333/collections
+```
+
+**Version:** 1 (1.16.3)
+**Platforms:** macOS, Linux, Windows (all platforms)
+**Ports:** 6333 (REST/HTTP), 6334 (gRPC)
+**Query interface:** REST API (no CLI shell - use curl or API clients)
+**Tools:** `qdrant` (included)
+
 ---
 
 ## Enhanced CLI Tools
@@ -544,6 +569,7 @@ SpinDB supports enhanced database shells with auto-completion, syntax highlighti
 | Redis | `redis-cli` | `iredis` | - |
 | Valkey | `valkey-cli` | `iredis` (compatible) | - |
 | ClickHouse | `clickhouse-client` | - | `usql` |
+| Qdrant | REST API | - | - |
 
 Install and use in one command:
 
@@ -563,12 +589,12 @@ Every engine supports backup and restore with engine-specific formats:
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | pg_dump | Human-readable, portable |
-| Custom | `.dump` | pg_dump -Fc | Compressed, faster restore |
+| sql | `.sql` | pg_dump | Human-readable, portable |
+| custom | `.dump` | pg_dump -Fc | Compressed, faster restore |
 
 ```bash
-spindb backup mydb --sql                # Plain SQL
-spindb backup mydb --dump               # Binary custom format
+spindb backup mydb --format sql         # Plain SQL
+spindb backup mydb --format custom      # Binary custom format
 spindb restore mydb backup.dump
 ```
 
@@ -576,23 +602,23 @@ spindb restore mydb backup.dump
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | mysqldump / mariadb-dump | Human-readable |
-| Compressed | `.sql.gz` | mysqldump + gzip | Smaller file size |
+| sql | `.sql` | mysqldump / mariadb-dump | Human-readable |
+| compressed | `.sql.gz` | mysqldump + gzip | Smaller file size |
 
 ```bash
-spindb backup mydb --sql                # Plain SQL
-spindb backup mydb --dump               # Compressed SQL
+spindb backup mydb --format sql         # Plain SQL
+spindb backup mydb --format compressed  # Compressed SQL
 ```
 
 ### MongoDB
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| BSON | `.bson` | mongodump | Binary, preserves all types |
-| Archive | `.archive` | mongodump --archive | Single compressed file |
+| bson | _(directory)_ | mongodump | Binary, preserves all types |
+| archive | `.archive` | mongodump --archive | Single compressed file |
 
 ```bash
-spindb backup mydb                      # BSON directory
+spindb backup mydb --format bson        # BSON directory
 spindb backup mydb --format archive     # Single .archive file
 ```
 
@@ -600,12 +626,12 @@ spindb backup mydb --format archive     # Single .archive file
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| RDB | `.rdb` | BGSAVE | Binary snapshot, requires restart |
-| Text | `.redis` / `.valkey` | Custom | Human-readable commands |
+| rdb | `.rdb` | BGSAVE | Binary snapshot, requires stop/start |
+| text | `.redis` / `.valkey` | Custom | Human-readable commands |
 
 ```bash
-spindb backup mydb --dump               # RDB snapshot
-spindb backup mydb --sql                # Text commands
+spindb backup mydb --format rdb         # RDB snapshot (default)
+spindb backup mydb --format text        # Text commands
 
 # Restore with merge or replace strategy
 spindb restore mydb backup.redis        # Prompts: Replace all / Merge
@@ -615,23 +641,32 @@ spindb restore mydb backup.redis        # Prompts: Replace all / Merge
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | .dump / duckdb | Human-readable |
-| Binary | `.sqlite` / `.duckdb` | File copy | Exact database copy |
+| sql | `.sql` | .dump / duckdb | Human-readable |
+| binary | `.sqlite` / `.duckdb` | File copy | Exact database copy |
 
 ```bash
-spindb backup mydb --sql                # SQL dump
-spindb backup mydb --dump               # Binary copy
+spindb backup mydb --format sql         # SQL dump
+spindb backup mydb --format binary      # Binary copy (default)
 ```
 
 ### ClickHouse
 
 | Format | Extension | Tool | Use Case |
 |--------|-----------|------|----------|
-| SQL | `.sql` | clickhouse-client | Plain SQL dump |
-| Native | `.clickhouse` | clickhouse-backup | Native format (future) |
+| sql | `.sql` | clickhouse-client | Plain SQL dump |
+
+```bash
+spindb backup mydb --format sql         # SQL dump (only format)
+```
+
+### Qdrant
+
+| Format | Extension | Tool | Use Case |
+|--------|-----------|------|----------|
+| snapshot | `.snapshot` | REST API | Full database snapshot |
 
 ```bash
-spindb backup mydb --sql                # SQL dump
+spindb backup mydb --format snapshot    # Snapshot (only format)
 ```
 
 ---
@@ -652,7 +687,7 @@ spindb start staging
 
 ### Restore from Remote
 
-Pull production data into local databases:
+Pull production data into local databases. **All engines support remote restore via connection strings:**
 
 ```bash
 # Create new database from remote
@@ -662,6 +697,19 @@ spindb create prod-copy --from "postgresql://user:pass@prod-host:5432/production
 spindb restore mydb --from-url "postgresql://user:pass@prod-host:5432/production"
 ```
 
+**Supported connection string formats:**
+
+| Engine | Format | Example |
+|--------|--------|---------|
+| PostgreSQL | `postgresql://` or `postgres://` | `postgresql://user:pass@host:5432/db` |
+| MySQL | `mysql://` | `mysql://root:pass@host:3306/db` |
+| MariaDB | `mysql://` or `mariadb://` | `mariadb://root:pass@host:3307/db` |
+| MongoDB | `mongodb://` or `mongodb+srv://` | `mongodb://user:pass@host:27017/db` |
+| Redis | `redis://` | `redis://:password@host:6379/0` |
+| Valkey | `redis://` | `redis://:password@host:6379/0` |
+| ClickHouse | `clickhouse://` or `http://` | `clickhouse://default:pass@host:8123/db` |
+| Qdrant | `qdrant://` or `http://` | `http://host:6333?api_key=KEY` |
+
 ### Multi-Version Support
 
 Run different versions of the same database simultaneously:
@@ -742,7 +790,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).
-- **Redis/Valkey remote dump** - Cannot create containers directly from remote connection strings. Use backup/restore workflow instead.
+- **Qdrant** - Uses REST API instead of CLI shell. Access via HTTP at the configured port.
 
 ---
 
@@ -817,7 +865,7 @@ See [FEATURE.md](FEATURE.md) for adding new database engines.
 
 SpinDB is powered by:
 
-- **[hostdb](https://github.com/robertjbass/hostdb)** - Pre-compiled database binaries for 9 engines across all major platforms. Makes Docker-free multi-version database support possible.
+- **[hostdb](https://github.com/robertjbass/hostdb)** - Pre-compiled database binaries for 10 engines across all major platforms. Makes Docker-free multi-version database support possible.
 
 ---
 

package/cli/commands/backup.ts

@@ -14,6 +14,15 @@ import {
 import { createSpinner } from '../ui/spinner'
 import { uiSuccess, uiError, uiWarning, formatBytes } from '../ui/theme'
 import { getMissingDependencies } from '../../core/dependency-manager'
+import { isFileBasedEngine } from '../../types'
+import {
+  getBackupExtension,
+  getBackupSpinnerLabel,
+  getDefaultFormat,
+  isValidFormat,
+  getValidFormats,
+} from '../../config/backup-formats'
+import type { BackupFormatType } from '../../types'
 
 function generateTimestamp(): string {
   const now = new Date()
@@ -28,42 +37,6 @@ function generateDefaultFilename(
   return `${containerName}-${database}-backup-${timestamp}`
 }
 
-function getExtension(format: 'sql' | 'dump', engine: string): string {
-  // Handle 'sql' format (human-readable option)
-  if (format === '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'
-  }
-}
-
-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')
   .description('Create a backup of a database')
   .argument('[container]', 'Container name')
@@ -73,9 +46,7 @@ export const backupCommand = new Command('backup')
     '-o, --output <path>',
     'Output directory (defaults to current directory)',
   )
-  .option('--format <format>', 'Output format: sql or dump')
-  .option('--sql', 'Output as plain SQL (shorthand for --format sql)')
-  .option('--dump', 'Output as dump format (shorthand for --format dump)')
+  .option('--format <format>', 'Backup format (engine-specific, e.g., sql, custom, rdb, binary)')
   .option('-j, --json', 'Output result as JSON')
   .action(
     async (
@@ -85,8 +56,6 @@ export const backupCommand = new Command('backup')
         name?: string
         output?: string
         format?: string
-        sql?: boolean
-        dump?: boolean
         json?: boolean
       },
     ) => {
@@ -94,6 +63,12 @@ export const backupCommand = new Command('backup')
         let containerName = containerArg
 
         if (!containerName) {
+          // JSON mode requires container name argument
+          if (options.json) {
+            console.log(JSON.stringify({ error: 'Container name is required' }))
+            process.exit(1)
+          }
+
           const containers = await containerManager.list()
           const running = containers.filter((c) => c.status === 'running')
 
@@ -124,22 +99,30 @@ export const backupCommand = new Command('backup')
 
         const config = await containerManager.getConfig(containerName)
         if (!config) {
-          console.error(uiError(`Container "${containerName}" not found`))
+          if (options.json) {
+            console.log(JSON.stringify({ error: `Container "${containerName}" not found` }))
+          } else {
+            console.error(uiError(`Container "${containerName}" not found`))
+          }
           process.exit(1)
         }
 
         const { engine: engineName } = config
 
-        const running = await processManager.isRunning(containerName, {
-          engine: engineName,
-        })
-        if (!running) {
-          console.error(
-            uiError(
-              `Container "${containerName}" is not running. Start it first.`,
-            ),
-          )
-          process.exit(1)
+        // File-based engines (SQLite, DuckDB) don't need to be "running"
+        if (!isFileBasedEngine(engineName)) {
+          const running = await processManager.isRunning(containerName, {
+            engine: engineName,
+          })
+          if (!running) {
+            const errorMsg = `Container "${containerName}" is not running. Start it first.`
+            if (options.json) {
+              console.log(JSON.stringify({ error: errorMsg }))
+            } else {
+              console.error(uiError(errorMsg))
+            }
+            process.exit(1)
+          }
         }
 
         const engine = getEngine(engineName)
@@ -193,20 +176,26 @@ export const backupCommand = new Command('backup')
           }
         }
 
-        let format: 'sql' | 'dump' = 'sql'
+        let format: BackupFormatType = getDefaultFormat(engineName)
 
-        if (options.sql) {
-          format = 'sql'
-        } else if (options.dump) {
-          format = 'dump'
-        } else if (options.format) {
-          if (options.format !== 'sql' && options.format !== 'dump') {
-            console.error(uiError('Format must be "sql" or "dump"'))
+        if (options.format) {
+          if (!isValidFormat(engineName, options.format)) {
+            const validFormats = getValidFormats(engineName)
+            const errorMsg = `Invalid format "${options.format}" for ${engineName}. Valid formats: ${validFormats.join(', ')}`
+            if (options.json) {
+              console.log(JSON.stringify({ error: errorMsg }))
+            } else {
+              console.error(uiError(errorMsg))
+            }
             process.exit(1)
           }
-          format = options.format as 'sql' | 'dump'
+          // Safe to cast: isValidFormat above guarantees the format is valid
+          format = options.format as BackupFormatType
         } else if (!containerArg) {
-          format = await promptBackupFormat(engineName)
+          const selectedFormat = await promptBackupFormat(engineName)
+          if (selectedFormat) {
+            format = selectedFormat
+          }
         }
 
         const defaultFilename = generateDefaultFilename(
@@ -219,13 +208,13 @@ export const backupCommand = new Command('backup')
           filename = await promptBackupFilename(defaultFilename)
         }
 
-        const extension = getExtension(format, engineName)
+        const extension = getBackupExtension(engineName, format)
         const outputDir = options.output || process.cwd()
         const outputPath = join(outputDir, `${filename}${extension}`)
 
-        const formatDesc = getFormatDescription(format, engineName)
+        const spinnerLabel = getBackupSpinnerLabel(engineName, format)
         const backupSpinner = createSpinner(
-          `Creating ${formatDesc} backup of "${databaseName}"...`,
+          `Creating ${spinnerLabel} backup of "${databaseName}"...`,
         )
         backupSpinner.start()
 
@@ -269,6 +258,10 @@ export const backupCommand = new Command('backup')
         )
 
         if (matchingPattern) {
+          if (options.json) {
+            console.log(JSON.stringify({ error: e.message }))
+            process.exit(1)
+          }
           const missingTool = matchingPattern.replace(' not found', '')
           const installed = await promptInstallDependencies(missingTool)
           if (installed) {
@@ -279,7 +272,11 @@ export const backupCommand = new Command('backup')
           process.exit(1)
         }
 
-        console.error(uiError(e.message))
+        if (options.json) {
+          console.log(JSON.stringify({ error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
         process.exit(1)
       }
     },

package/cli/commands/clone.ts

@@ -23,6 +23,12 @@ export const cloneCommand = new Command('clone')
         let targetName = target
 
         if (!sourceName) {
+          // JSON mode requires source container name argument
+          if (options.json) {
+            console.log(JSON.stringify({ error: 'Source container name is required' }))
+            process.exit(1)
+          }
+
           const containers = await containerManager.list()
           const stopped = containers.filter((c) => c.status !== 'running')
 
@@ -57,7 +63,11 @@ export const cloneCommand = new Command('clone')
 
         const sourceConfig = await containerManager.getConfig(sourceName)
         if (!sourceConfig) {
-          console.error(uiError(`Container "${sourceName}" not found`))
+          if (options.json) {
+            console.log(JSON.stringify({ error: `Container "${sourceName}" not found` }))
+          } else {
+            console.error(uiError(`Container "${sourceName}" not found`))
+          }
           process.exit(1)
         }
 
@@ -65,15 +75,21 @@ export const cloneCommand = new Command('clone')
           engine: sourceConfig.engine,
         })
         if (running) {
-          console.error(
-            uiError(
-              `Container "${sourceName}" is running. Stop it first to clone.`,
-            ),
-          )
+          const errorMsg = `Container "${sourceName}" is running. Stop it first to clone.`
+          if (options.json) {
+            console.log(JSON.stringify({ error: errorMsg }))
+          } else {
+            console.error(uiError(errorMsg))
+          }
           process.exit(1)
         }
 
         if (!targetName) {
+          // JSON mode requires target container name argument
+          if (options.json) {
+            console.log(JSON.stringify({ error: 'Target container name is required' }))
+            process.exit(1)
+          }
           targetName = await promptContainerName(`${sourceName}-copy`)
         }
 
@@ -83,7 +99,12 @@ export const cloneCommand = new Command('clone')
             engine: sourceConfig.engine,
           })
         ) {
-          console.error(uiError(`Container "${targetName}" already exists`))
+          const errorMsg = `Container "${targetName}" already exists`
+          if (options.json) {
+            console.log(JSON.stringify({ error: errorMsg }))
+          } else {
+            console.error(uiError(errorMsg))
+          }
           process.exit(1)
         }
 
@@ -121,7 +142,11 @@ export const cloneCommand = new Command('clone')
         }
       } catch (error) {
         const e = error as Error
-        console.error(uiError(e.message))
+        if (options.json) {
+          console.log(JSON.stringify({ error: e.message }))
+        } else {
+          console.error(uiError(e.message))
+        }
         process.exit(1)
       }
     },