spindb 0.17.3 → 0.18.0

package/README.md

@@ -7,7 +7,7 @@
 
 **The first npm CLI for running local databases without Docker.**
 
-Spin up PostgreSQL, MySQL, MariaDB, SQLite, MongoDB, Redis, and Valkey 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, MariaDB, SQLite, MongoDB, Redis, Valkey, and ClickHouse instances for local development. No Docker daemon, no container networking, no volume mounts. Just databases running on localhost, ready in seconds.
 
 ---
 
@@ -343,6 +343,46 @@ spindb connect myvalkey --iredis
 
 **Note:** Valkey uses `redis://` connection scheme for client compatibility since it's wire-compatible with Redis.
 
+#### ClickHouse
+
+| | |
+|---|---|
+| Versions | 25.12 |
+| Default port | 9000 (native TCP), 8123 (HTTP) |
+| Default user | `default` |
+| Binary source | [hostdb](https://github.com/robertjbass/hostdb) |
+
+ClickHouse is a column-oriented OLAP database designed for fast analytics on large datasets. SpinDB downloads ClickHouse server binaries automatically from [hostdb](https://github.com/robertjbass/hostdb) on GitHub Releases.
+
+**Note:** ClickHouse is only available on macOS and Linux. Windows is not supported.
+
+```bash
+# Create a ClickHouse container (downloads binaries automatically)
+spindb create mydb --engine clickhouse
+
+# Create with specific version
+spindb create mydb --engine clickhouse --version 25.12
+
+# Check what's available
+spindb deps check --engine clickhouse
+```
+
+ClickHouse uses SQL (with ClickHouse-specific extensions):
+
+```bash
+# Create a table
+spindb run mych -c "CREATE TABLE users (id UInt64, name String) ENGINE = MergeTree() ORDER BY id"
+
+# Insert data
+spindb run mych -c "INSERT INTO users VALUES (1, 'Alice'), (2, 'Bob')"
+
+# Query data
+spindb run mych -c "SELECT * FROM users"
+
+# Run a SQL file
+spindb run mych --file ./scripts/seed.sql
+```
+
 ### hostdb Platform Coverage
 
 SpinDB downloads database binaries from [hostdb](https://github.com/robertjbass/hostdb), a repository of pre-built database binaries for all major platforms. The following table shows current platform support and integration status:
@@ -363,6 +403,7 @@ SpinDB downloads database binaries from [hostdb](https://github.com/robertjbass/
 | MongoDB* | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Redis* | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Valkey | ✅ | ✅ | ✅ | ✅ | ✅ |
+| ClickHouse* | ✅ | ✅ | ✅ | ✅ | ❌ |
 | **Planned for hostdb** |||||
 | CockroachDB | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
 | TimescaleDB | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
@@ -375,7 +416,6 @@ SpinDB downloads database binaries from [hostdb](https://github.com/robertjbass/
 | ArangoDB | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
 | Qdrant | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
 | Apache Cassandra | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
-| ClickHouse | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
 | InfluxDB | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
 | CouchDB | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
 | KeyDB | 🟪 | 🟪 | 🟪 | 🟪 | 🟪 |
@@ -386,6 +426,7 @@ SpinDB downloads database binaries from [hostdb](https://github.com/robertjbass/
 **Notes:**
 - **\*** Licensing considerations for commercial use — consider Valkey (Redis) or FerretDB (MongoDB) as alternatives
 - **PostgreSQL** uses [EDB](https://www.enterprisedb.com/) binaries on Windows instead of hostdb
+- **ClickHouse** Windows binaries are not available on hostdb (macOS and Linux only)
 - **Valkey** is a Redis-compatible drop-in replacement with permissive licensing
 - **CockroachDB** is planned for both hostdb and SpinDB (see [roadmap](TODO.md))
 - All databases under "Planned for hostdb" have permissive open-source licenses (Apache 2.0, MIT, or BSD)

package/cli/commands/create.ts

@@ -515,6 +515,7 @@ export const createCommand = new Command('create')
 
         try {
           await dbEngine.initDataDir(containerName, version, {
+            port,
             superuser: engineDefaults.superuser,
             maxConnections: options.maxConnections
               ? parseInt(options.maxConnections, 10)

package/cli/commands/engines.ts

@@ -51,6 +51,7 @@ import { mongodbBinaryManager } from '../../engines/mongodb/binary-manager'
 import { redisBinaryManager } from '../../engines/redis/binary-manager'
 import { valkeyBinaryManager } from '../../engines/valkey/binary-manager'
 import { sqliteBinaryManager } from '../../engines/sqlite/binary-manager'
+import { clickhouseBinaryManager } from '../../engines/clickhouse/binary-manager'
 
 // Pad string to width, accounting for emoji taking 2 display columns
 function padWithEmoji(str: string, width: number): string {
@@ -1218,9 +1219,69 @@ enginesCommand
         return
       }
 
+      if (['clickhouse', 'ch'].includes(normalizedEngine)) {
+        // Check platform support
+        const { platform } = platformService.getPlatformInfo()
+        if (platform === 'win32') {
+          console.error(
+            uiError('ClickHouse is not supported on Windows via hostdb'),
+          )
+          console.log(
+            chalk.gray(
+              '  ClickHouse binaries are only available for macOS and Linux.',
+            ),
+          )
+          process.exit(1)
+        }
+
+        if (!version) {
+          console.error(uiError('ClickHouse requires a version (e.g., 25.12)'))
+          process.exit(1)
+        }
+
+        const engine = getEngine(Engine.ClickHouse)
+
+        const spinner = createSpinner(
+          `Checking ClickHouse ${version} binaries...`,
+        )
+        spinner.start()
+
+        let wasCached = false
+        await engine.ensureBinaries(version, ({ stage, message }) => {
+          if (stage === 'cached') {
+            wasCached = true
+            spinner.text = `ClickHouse ${version} binaries ready (cached)`
+          } else {
+            spinner.text = message
+          }
+        })
+
+        if (wasCached) {
+          spinner.succeed(`ClickHouse ${version} binaries already installed`)
+        } else {
+          spinner.succeed(`ClickHouse ${version} binaries downloaded`)
+        }
+
+        // Show the path for reference
+        const { platform: chPlatform, arch: chArch } =
+          platformService.getPlatformInfo()
+        const chFullVersion = clickhouseBinaryManager.getFullVersion(version)
+        const binPath = paths.getBinaryPath({
+          engine: 'clickhouse',
+          version: chFullVersion,
+          platform: chPlatform,
+          arch: chArch,
+        })
+        console.log(chalk.gray(`  Location: ${binPath}`))
+
+        // Check for bundled client tools and install missing ones
+        await checkAndInstallClientTools('clickhouse', binPath)
+        return
+      }
+
       console.error(
         uiError(
-          `Unknown engine "${engineName}". Supported: postgresql, mysql, sqlite, mongodb, redis, valkey`,
+          `Unknown engine "${engineName}". Supported: postgresql, mysql, sqlite, mongodb, redis, valkey, clickhouse`,
         ),
       )
       process.exit(1)

package/cli/commands/menu/engine-handlers.ts

@@ -16,6 +16,7 @@ import {
   type InstalledMongodbEngine,
   type InstalledRedisEngine,
   type InstalledValkeyEngine,
+  type InstalledClickHouseEngine,
 } from '../../helpers'
 
 import { type MenuChoice } from './shared'
@@ -55,6 +56,7 @@ export async function handleEngines(): Promise<void> {
     mongodbEngines,
     redisEngines,
     valkeyEngines,
+    clickhouseEngines,
   ] = [
     engines.filter(
       (e): e is InstalledPostgresEngine => e.engine === 'postgresql',
@@ -65,6 +67,9 @@ export async function handleEngines(): Promise<void> {
     engines.filter((e): e is InstalledMongodbEngine => e.engine === 'mongodb'),
     engines.filter((e): e is InstalledRedisEngine => e.engine === 'redis'),
     engines.filter((e): e is InstalledValkeyEngine => e.engine === 'valkey'),
+    engines.filter(
+      (e): e is InstalledClickHouseEngine => e.engine === 'clickhouse',
+    ),
   ]
 
   const totalPgSize = pgEngines.reduce((acc, e) => acc + e.sizeBytes, 0)
@@ -80,6 +85,10 @@ export async function handleEngines(): Promise<void> {
   )
   const totalRedisSize = redisEngines.reduce((acc, e) => acc + e.sizeBytes, 0)
   const totalValkeySize = valkeyEngines.reduce((acc, e) => acc + e.sizeBytes, 0)
+  const totalClickhouseSize = clickhouseEngines.reduce(
+    (acc, e) => acc + e.sizeBytes,
+    0,
+  )
 
   const COL_ENGINE = 14
   const COL_VERSION = 12
@@ -104,6 +113,7 @@ export async function handleEngines(): Promise<void> {
     ...mongodbEngines,
     ...redisEngines,
     ...valkeyEngines,
+    ...clickhouseEngines,
   ]
 
   for (const engine of allEnginesSorted) {
@@ -172,6 +182,13 @@ export async function handleEngines(): Promise<void> {
       ),
     )
   }
+  if (clickhouseEngines.length > 0) {
+    console.log(
+      chalk.gray(
+        `  ClickHouse: ${clickhouseEngines.length} version(s), ${formatBytes(totalClickhouseSize)}`,
+      ),
+    )
+  }
   console.log()
 
   const choices: MenuChoice[] = allEnginesSorted.map((e) => ({

package/cli/commands/menu/shell-handlers.ts

@@ -507,6 +507,20 @@ async function launchShell(
       config.database,
     ]
     installHint = 'spindb engines download valkey'
+  } else if (config.engine === 'clickhouse') {
+    // ClickHouse uses a unified binary with subcommands
+    const clickhousePath = await configManager.getBinaryPath('clickhouse')
+    shellCmd = clickhousePath || 'clickhouse'
+    shellArgs = [
+      'client',
+      '--host',
+      '127.0.0.1',
+      '--port',
+      String(config.port),
+      '--database',
+      config.database,
+    ]
+    installHint = 'spindb engines download clickhouse'
   } else {
     shellCmd = 'psql'
     shellArgs = [connectionString]

package/cli/constants.ts

@@ -8,6 +8,7 @@ export const ENGINE_ICONS: Record<string, string> = {
   mongodb: '🍃',
   redis: '🔴',
   valkey: '🔷',
+  clickhouse: '🏠',
 }
 
 export const DEFAULT_ENGINE_ICON = '▣'

package/cli/helpers.ts

@@ -134,6 +134,16 @@ export type InstalledValkeyEngine = {
   source: 'downloaded'
 }
 
+export type InstalledClickHouseEngine = {
+  engine: 'clickhouse'
+  version: string
+  platform: string
+  arch: string
+  path: string
+  sizeBytes: number
+  source: 'downloaded'
+}
+
 export type InstalledEngine =
   | InstalledPostgresEngine
   | InstalledMariadbEngine
@@ -142,6 +152,7 @@ export type InstalledEngine =
   | InstalledMongodbEngine
   | InstalledRedisEngine
   | InstalledValkeyEngine
+  | InstalledClickHouseEngine
 
 async function getPostgresVersion(binPath: string): Promise<string | null> {
   const ext = platformService.getExecutableExtension()
@@ -535,6 +546,61 @@ async function getInstalledValkeyEngines(): Promise<InstalledValkeyEngine[]> {
   return engines
 }
 
+// Get ClickHouse version from binary path
+async function getClickHouseVersion(binPath: string): Promise<string | null> {
+  const clickhousePath = join(binPath, 'bin', 'clickhouse')
+  if (!existsSync(clickhousePath)) {
+    return null
+  }
+
+  try {
+    const { stdout } = await execFileAsync(clickhousePath, ['client', '--version'])
+    // Parse output like "ClickHouse client version 25.12.3.21 (official build)"
+    const match = stdout.match(/version\s+([\d.]+)/)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+
+// Get installed ClickHouse engines from downloaded binaries
+async function getInstalledClickHouseEngines(): Promise<InstalledClickHouseEngine[]> {
+  const binDir = paths.bin
+
+  if (!existsSync(binDir)) {
+    return []
+  }
+
+  const entries = await readdir(binDir, { withFileTypes: true })
+  const engines: InstalledClickHouseEngine[] = []
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (!entry.name.startsWith('clickhouse-')) continue
+
+    const parsed = parseEngineDirectory(entry.name, 'clickhouse-', binDir)
+    if (!parsed) continue
+
+    const actualVersion =
+      (await getClickHouseVersion(parsed.path)) || parsed.version
+    const sizeBytes = await calculateDirectorySize(parsed.path)
+
+    engines.push({
+      engine: 'clickhouse',
+      version: actualVersion,
+      platform: parsed.platform,
+      arch: parsed.arch,
+      path: parsed.path,
+      sizeBytes,
+      source: 'downloaded',
+    })
+  }
+
+  engines.sort((a, b) => compareVersions(b.version, a.version))
+
+  return engines
+}
+
 export function compareVersions(a: string, b: string): number {
   const partsA = a.split('.').map((p) => parseInt(p, 10) || 0)
   const partsB = b.split('.').map((p) => parseInt(p, 10) || 0)
@@ -571,6 +637,9 @@ export async function getInstalledEngines(): Promise<InstalledEngine[]> {
   const valkeyEngines = await getInstalledValkeyEngines()
   engines.push(...valkeyEngines)
 
+  const clickhouseEngines = await getInstalledClickHouseEngines()
+  engines.push(...clickhouseEngines)
+
   return engines
 }
 
@@ -581,4 +650,5 @@ export {
   getInstalledMongodbEngines,
   getInstalledRedisEngines,
   getInstalledValkeyEngines,
+  getInstalledClickHouseEngines,
 }

package/config/backup-formats.ts

@@ -122,6 +122,22 @@ export const BACKUP_FORMATS: Record<string, EngineBackupFormats> = {
     supportsFormatChoice: true,
     defaultFormat: 'dump',
   },
+  clickhouse: {
+    sql: {
+      extension: '.sql',
+      label: '.sql',
+      description: 'SQL dump - DDL + INSERT statements',
+      spinnerLabel: 'SQL',
+    },
+    dump: {
+      extension: '.sql',
+      label: '.sql',
+      description: 'SQL dump - DDL + INSERT statements',
+      spinnerLabel: 'SQL',
+    },
+    supportsFormatChoice: false, // Only SQL format supported
+    defaultFormat: 'sql',
+  },
 }
 
 // Get backup format info for an engine

package/config/engine-defaults.ts

@@ -129,6 +129,20 @@ export const engineDefaults: Record<string, EngineDefaults> = {
     clientTools: ['valkey-cli'],
     maxConnections: 0, // Not applicable for Valkey
   },
+  clickhouse: {
+    defaultVersion: '25.12',
+    defaultPort: 9000, // Native TCP port (HTTP is 8123)
+    portRange: { start: 9000, end: 9100 },
+    supportedVersions: ['25.12'], // Keep in sync with engines/clickhouse/version-maps.ts
+    latestVersion: '25.12',
+    superuser: 'default', // Default user in ClickHouse
+    connectionScheme: 'clickhouse',
+    logFileName: 'clickhouse-server.log',
+    pidFileName: 'clickhouse.pid',
+    dataSubdir: 'data',
+    clientTools: ['clickhouse'],
+    maxConnections: 0, // Not applicable
+  },
 }
 
 /**

package/config/engines.json

@@ -104,6 +104,22 @@
       "clientTools": ["valkey-server", "valkey-cli"],
       "licensing": "BSD-3-Clause",
       "notes": "Redis fork with permissive licensing. Shares default port 6379 with Redis; port conflicts are resolved automatically."
+    },
+    "clickhouse": {
+      "displayName": "ClickHouse",
+      "icon": "🏠",
+      "status": "integrated",
+      "binarySource": "hostdb",
+      "supportedVersions": ["25.12.3.21"],
+      "defaultVersion": "25.12.3.21",
+      "defaultPort": 9000,
+      "runtime": "server",
+      "queryLanguage": "sql",
+      "connectionScheme": "clickhouse",
+      "superuser": "default",
+      "clientTools": ["clickhouse"],
+      "licensing": "Apache-2.0",
+      "notes": "Column-oriented OLAP database. Uses YY.MM.X.build versioning. Native port 9000, HTTP port 8123."
     }
   }
 }

package/config/os-dependencies.ts

@@ -651,6 +651,41 @@ const valkeyDependencies: EngineDependencies = {
   ],
 }
 
+// =============================================================================
+// ClickHouse Dependencies
+// =============================================================================
+
+const clickhouseDependencies: EngineDependencies = {
+  engine: 'clickhouse',
+  displayName: 'ClickHouse',
+  dependencies: [
+    {
+      name: 'clickhouse',
+      binary: 'clickhouse',
+      description: 'ClickHouse server and client (unified binary)',
+      packages: {
+        brew: { package: 'clickhouse' },
+        // ClickHouse requires their own apt repository
+      },
+      manualInstall: {
+        darwin: [
+          'Install with Homebrew: brew install clickhouse',
+          'Or use SpinDB: spindb engines download clickhouse 25.12',
+        ],
+        linux: [
+          'ClickHouse provides official packages.',
+          'Add their apt repository: https://clickhouse.com/docs/en/install#install-from-deb-packages',
+          'Or use SpinDB: spindb engines download clickhouse 25.12',
+        ],
+        win32: [
+          'ClickHouse does not officially support Windows.',
+          'Use WSL2 with Linux installation instructions.',
+        ],
+      },
+    },
+  ],
+}
+
 // =============================================================================
 // Optional Tools (engine-agnostic)
 // =============================================================================
@@ -807,6 +842,7 @@ export const engineDependencies: EngineDependencies[] = [
   mongodbDependencies,
   redisDependencies,
   valkeyDependencies,
+  clickhouseDependencies,
 ]
 
 // Get dependencies for a specific engine

package/core/platform-service.ts

@@ -120,6 +120,13 @@ export abstract class BasePlatformService {
   // Check if a process is running by PID
   abstract isProcessRunning(pid: number): boolean
 
+  /**
+   * Find process PIDs listening on a specific port
+   * @param port - Port number to check
+   * @returns Array of PIDs listening on the port (empty if none found)
+   */
+  abstract findProcessByPort(port: number): Promise<number[]>
+
   // Copy text to clipboard
   async copyToClipboard(text: string): Promise<boolean> {
     const config = this.getClipboardConfig()
@@ -344,6 +351,21 @@ class DarwinPlatformService extends BasePlatformService {
     }
   }
 
+  async findProcessByPort(port: number): Promise<number[]> {
+    try {
+      const { stdout } = await execAsync(`lsof -ti tcp:${port} 2>/dev/null || true`)
+      const pids = stdout
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map((pid) => parseInt(pid, 10))
+        .filter((pid) => !isNaN(pid))
+      return pids
+    } catch {
+      return []
+    }
+  }
+
   protected buildToolPath(dir: string, toolName: string): string {
     return `${dir}/${toolName}`
   }
@@ -544,6 +566,21 @@ class LinuxPlatformService extends BasePlatformService {
     }
   }
 
+  async findProcessByPort(port: number): Promise<number[]> {
+    try {
+      const { stdout } = await execAsync(`lsof -ti tcp:${port} 2>/dev/null || true`)
+      const pids = stdout
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map((pid) => parseInt(pid, 10))
+        .filter((pid) => !isNaN(pid))
+      return pids
+    } catch {
+      return []
+    }
+  }
+
   protected buildToolPath(dir: string, toolName: string): string {
     return `${dir}/${toolName}`
   }
@@ -700,6 +737,37 @@ class Win32PlatformService extends BasePlatformService {
     }
   }
 
+  async findProcessByPort(port: number): Promise<number[]> {
+    try {
+      // Use netstat to find PIDs listening on the port
+      // -a = all connections, -n = numeric, -o = owner PID
+      const { stdout } = await execAsync(`netstat -ano | findstr :${port}`)
+      const pids: number[] = []
+
+      // Parse netstat output to find LISTENING processes on this exact port
+      // Format: TCP    0.0.0.0:PORT    0.0.0.0:0    LISTENING    PID
+      const lines = stdout.trim().split('\n')
+      for (const line of lines) {
+        // Match lines with LISTENING state on the specific port
+        const parts = line.trim().split(/\s+/)
+        if (parts.length >= 5 && parts[3] === 'LISTENING') {
+          const localAddress = parts[1]
+          // Check if this is the exact port (not just containing the port number)
+          if (localAddress.endsWith(`:${port}`)) {
+            const pid = parseInt(parts[4], 10)
+            if (!isNaN(pid) && !pids.includes(pid)) {
+              pids.push(pid)
+            }
+          }
+        }
+      }
+
+      return pids
+    } catch {
+      return []
+    }
+  }
+
   protected buildToolPath(dir: string, toolName: string): string {
     return `${dir}\\${toolName}.exe`
   }

package/engines/base-engine.ts

@@ -122,6 +122,15 @@ export abstract class BaseEngine {
     throw new Error('valkey-cli not found')
   }
 
+  /**
+   * Get the path to the clickhouse client if available
+   * Default implementation throws; engines that can provide a bundled or
+   * configured clickhouse should override this method.
+   */
+  async getClickHouseClientPath(): Promise<string> {
+    throw new Error('clickhouse client not found')
+  }
+
   /**
    * Get the path to the sqlite3 client if available
    * Default implementation returns null; SQLite engine overrides this method.