spindb 0.27.6 → 0.30.1

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/spindb.svg)](https://www.npmjs.com/package/spindb)
 [![npm downloads](https://img.shields.io/npm/dm/spindb.svg)](https://www.npmjs.com/package/spindb)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](LICENSE)
-[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#platform-coverage)
+[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](#supported-engines--platforms)
 
 **One CLI for all your local databases.**
 
@@ -26,6 +26,35 @@ spindb create cache --engine redis
 
 ---
 
+## Supported Engines & Platforms
+
+SpinDB supports **16 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 | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+**78 combinations. One CLI. Zero configuration.**
+
+> ClickHouse and FerretDB are available on Windows via WSL.
+
+---
+
 ## What is SpinDB?
 
 SpinDB is **three tools in one**:
@@ -68,33 +97,6 @@ spindb run mydb -c "SELECT * FROM system.tables"        # ClickHouse
 
 ---
 
-## Platform Coverage
-
-SpinDB works across **16 database engines** and **5 platform architectures** with a **single, consistent API**.
-
-| Database | macOS ARM64 | macOS Intel | Linux x64 | Linux ARM64 | Windows x64 |
-|----------|:-----------:|:-----------:|:---------:|:-----------:|:-----------:|
-| 🐘 **PostgreSQL** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🐬 **MySQL** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🦭 **MariaDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🪶 **SQLite** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🦆 **DuckDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🍃 **MongoDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🦔 **FerretDB** | ✅ | ✅ | ✅ | ✅ | ❌ |
-| 🔴 **Redis** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🔷 **Valkey** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🏠 **ClickHouse** | ✅ | ✅ | ✅ | ✅ | ❌ |
-| 🧭 **Qdrant** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🔍 **Meilisearch** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🛋️ **CouchDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🪳 **CockroachDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| 🌀 **SurrealDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
-| ⏱️ **QuestDB** | ✅ | ✅ | ✅ | ✅ | ✅ |
-
-**78 combinations. One CLI. Zero configuration.**
-
----
-
 ## Quick Start
 
 Install SpinDB globally using your preferred package manager:
@@ -165,20 +167,56 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 - **Multi-version support** - Run PostgreSQL 14 and 18 side-by-side
 - **Unified interface** - Manage PostgreSQL, MongoDB, and Redis the same way
 
-### Comparison Matrix
-
-| Feature | SpinDB | Docker | DBngin | Postgres.app | XAMPP |
-|---------|--------|--------|--------|--------------|-------|
-| **All database types unified** | ✅ 16 engines | ❌ | ❌ | ❌ | ❌ |
-| No Docker required | ✅ | ❌ | ✅ | ✅ | ✅ |
-| CLI-first | ✅ | ✅ | ❌ GUI-first | ❌ GUI-first | ❌ GUI-first |
-| Multiple versions side-by-side | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Clone databases | ✅ | Manual | ✅ | ❌ | ❌ |
-| Backup/restore built-in | ✅ | Manual | ✅ | ❌ | ❌ |
-| Low resource usage | ✅ Native | ❌ VM overhead | ✅ Native | ✅ Native | ✅ Native |
-| Linux support | ✅ | ✅ | ❌ | ❌ | ✅ |
-| ARM64 support | ✅ | ✅ | ✅ | ✅ | ❌ |
-| Free for commercial use | ❌ | ⚠️ Paid for orgs | ✅ | ✅ | ✅ |
+### Comparison: Database GUI Tools
+
+*For developers who prefer visual interfaces or use macOS-native tools.*
+
+| Feature | SpinDB | DBngin | Postgres.app | Laragon |
+|---------|--------|--------|--------------|---------|
+| **Engines supported** | 16 | 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** | 16 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** | 16 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.
 
 ---
 
@@ -241,6 +279,7 @@ spindb create mydb --engine mongodb             # MongoDB
 spindb create mydb --engine mysql --db-version 8.0  # MySQL 8.0
 spindb create mydb --port 5433                  # Custom port
 spindb create mydb --start --connect            # Create, start, and connect
+spindb create mydb --force                      # Overwrite existing container
 
 # Start/stop databases
 spindb start mydb
@@ -290,14 +329,63 @@ spindb backup mydb --format custom              # Custom binary format (PostgreS
 spindb restore mydb backup.dump
 spindb restore mydb backup.sql --database prod_copy
 
-# Pull from remote database
-spindb restore mydb --from-url "postgresql://user:pass@prod-host/db"
-
 # Clone existing database
 spindb create prod-copy --from ./prod-backup.dump
 spindb create staging --from "postgresql://user:pass@prod:5432/production"
 ```
 
+### Pull from Remote Database
+
+Sync production data to your local database while automatically backing up your original data:
+
+```bash
+# Pull production data (backs up original, replaces with remote)
+spindb pull mydb --from "postgresql://user:pass@prod-host/db"
+
+# Read URL from environment variable (keeps credentials out of shell history)
+spindb pull mydb --from-env CLONE_FROM_DATABASE_URL
+
+# Clone mode: pull to new database (original untouched)
+spindb pull mydb --from-env PROD_URL --as mydb_prod
+
+# Preview what will happen
+spindb pull mydb --from-env PROD_URL --dry-run
+
+# Run post-pull script (e.g., sync local credentials)
+spindb pull mydb --from-env PROD_URL --post-script ./sync-credentials.ts
+```
+
+### Export to Docker
+
+Generate a Docker-ready package from any SpinDB container:
+
+```bash
+# Export to Docker (generates Dockerfile, docker-compose.yml, etc.)
+spindb export docker mydb
+
+# Custom output directory
+spindb export docker mydb -o ./deploy
+
+# Override port (default: engine's standard port, e.g., 5432 for PostgreSQL)
+spindb export docker mydb -p 5433
+
+# Skip database backup or TLS certificates
+spindb export docker mydb --no-data
+spindb export docker mydb --no-tls
+
+# JSON output for scripting
+spindb export docker mydb --json --force
+```
+
+Generated files:
+- `Dockerfile` - Ubuntu 22.04 + Node.js 22 + SpinDB
+- `docker-compose.yml` - Container orchestration
+- `.env` - Auto-generated credentials
+- `certs/` - TLS certificates (self-signed)
+- `data/` - Database backup
+- `entrypoint.sh` - Startup script
+- `README.md` - Instructions
+
 ### Container Management
 
 ```bash
@@ -440,8 +528,6 @@ Databases run as **native processes**, and **data persists across restarts**. Wh
 
 ## Engine-Specific Details
 
-Each database engine has unique features and behaviors. See full documentation in [ENGINES.md](ENGINES.md).
-
 ### PostgreSQL 🐘
 
 ```bash

package/cli/commands/create.ts

@@ -37,10 +37,17 @@ async function createSqliteContainer(
     path?: string
     from?: string | null
     connect?: boolean
+    force?: boolean
     json?: boolean
   },
 ): Promise<void> {
-  const { path: filePath, from: restoreLocation, connect, json } = options
+  const {
+    path: filePath,
+    from: restoreLocation,
+    connect,
+    force,
+    json,
+  } = options
 
   // Check dependencies
   const depsSpinner = json ? null : createSpinner('Checking required tools...')
@@ -70,17 +77,26 @@ async function createSqliteContainer(
 
   // Check if container already exists
   if (await containerManager.exists(containerName)) {
-    if (json) {
+    if (force) {
+      // Delete existing container with force
+      if (!json) {
+        console.log(
+          chalk.yellow(`  Removing existing container "${containerName}"...`),
+        )
+      }
+      await containerManager.delete(containerName, { force: true })
+    } else if (json) {
       return exitWithError({
-        message: `Container "${containerName}" already exists`,
+        message: `Container "${containerName}" already exists. Use --force to overwrite.`,
         json: true,
       })
-    }
-    while (await containerManager.exists(containerName)) {
-      console.log(
-        chalk.yellow(`  Container "${containerName}" already exists.`),
-      )
-      containerName = await promptContainerName()
+    } else {
+      while (await containerManager.exists(containerName)) {
+        console.log(
+          chalk.yellow(`  Container "${containerName}" already exists.`),
+        )
+        containerName = await promptContainerName()
+      }
     }
   }
 
@@ -190,10 +206,17 @@ async function createDuckDBContainer(
     path?: string
     from?: string | null
     connect?: boolean
+    force?: boolean
     json?: boolean
   },
 ): Promise<void> {
-  const { path: filePath, from: restoreLocation, connect, json } = options
+  const {
+    path: filePath,
+    from: restoreLocation,
+    connect,
+    force,
+    json,
+  } = options
 
   // Check dependencies
   const depsSpinner = json ? null : createSpinner('Checking required tools...')
@@ -223,17 +246,26 @@ async function createDuckDBContainer(
 
   // Check if container already exists
   if (await containerManager.exists(containerName)) {
-    if (json) {
+    if (force) {
+      // Delete existing container with force
+      if (!json) {
+        console.log(
+          chalk.yellow(`  Removing existing container "${containerName}"...`),
+        )
+      }
+      await containerManager.delete(containerName, { force: true })
+    } else if (json) {
       return exitWithError({
-        message: `Container "${containerName}" already exists`,
+        message: `Container "${containerName}" already exists. Use --force to overwrite.`,
         json: true,
       })
-    }
-    while (await containerManager.exists(containerName)) {
-      console.log(
-        chalk.yellow(`  Container "${containerName}" already exists.`),
-      )
-      containerName = await promptContainerName()
+    } else {
+      while (await containerManager.exists(containerName)) {
+        console.log(
+          chalk.yellow(`  Container "${containerName}" already exists.`),
+        )
+        containerName = await promptContainerName()
+      }
     }
   }
 
@@ -404,6 +436,10 @@ export const createCommand = new Command('create')
     '--max-connections <number>',
     'Maximum number of database connections (default: 200)',
   )
+  .option(
+    '-f, --force',
+    'Overwrite existing container without prompting (deletes existing data)',
+  )
   .option('--start', 'Start the container after creation (skip prompt)')
   .option('--no-start', 'Do not start the container after creation')
   .option('--connect', 'Open a shell connection after creation')
@@ -422,6 +458,7 @@ export const createCommand = new Command('create')
         port?: string
         path?: string
         maxConnections?: string
+        force?: boolean
         start?: boolean
         connect?: boolean
         from?: string
@@ -541,6 +578,7 @@ export const createCommand = new Command('create')
             path: options.path,
             from: restoreLocation,
             connect: options.connect,
+            force: options.force,
             json: options.json,
           })
           return
@@ -552,6 +590,7 @@ export const createCommand = new Command('create')
             path: options.path,
             from: restoreLocation,
             connect: options.connect,
+            force: options.force,
             json: options.json,
           })
           return
@@ -733,17 +772,44 @@ export const createCommand = new Command('create')
         }
 
         if (await containerManager.exists(containerName)) {
-          if (options.json) {
+          if (options.force) {
+            // Stop the container if it's running, then delete it
+            const existingConfig =
+              await containerManager.getConfig(containerName)
+            if (existingConfig?.status === 'running') {
+              if (!options.json) {
+                console.log(
+                  chalk.yellow(
+                    `  Stopping existing container "${containerName}"...`,
+                  ),
+                )
+              }
+              try {
+                await dbEngine.stop(existingConfig)
+              } catch {
+                // Ignore stop errors - container may already be stopped
+              }
+            }
+            if (!options.json) {
+              console.log(
+                chalk.yellow(
+                  `  Removing existing container "${containerName}"...`,
+                ),
+              )
+            }
+            await containerManager.delete(containerName, { force: true })
+          } else if (options.json) {
             return exitWithError({
-              message: `Container "${containerName}" already exists`,
+              message: `Container "${containerName}" already exists. Use --force to overwrite.`,
               json: true,
             })
-          }
-          while (await containerManager.exists(containerName)) {
-            console.log(
-              chalk.yellow(`  Container "${containerName}" already exists.`),
-            )
-            containerName = await promptContainerName()
+          } else {
+            while (await containerManager.exists(containerName)) {
+              console.log(
+                chalk.yellow(`  Container "${containerName}" already exists.`),
+              )
+              containerName = await promptContainerName()
+            }
           }
         }