spindb 0.36.2 → 0.37.1

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 19 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 20 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
@@ -28,7 +28,7 @@ spindb create cache --engine redis
 
 ## Supported Engines & Platforms
 
-SpinDB supports **19 database engines** across **5 platform architectures**—all with a consistent API.
+SpinDB supports **20 database engines** across **5 platform architectures**—all with a consistent API.
 
 | Engine | Type | macOS ARM | macOS Intel | Linux x64 | Linux ARM | Windows |
 |--------|------|:---------:|:-----------:|:---------:|:---------:|:-------:|
@@ -51,8 +51,9 @@ SpinDB supports **19 database engines** across **5 platform architectures**—al
 | 🤖 **TypeDB** | Knowledge Graph | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 📈 **InfluxDB** | Time-Series | ✅ | ✅ | ✅ | ✅ | ✅ |
 | 🔮 **Weaviate** | Vector Database | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 🐯 **TigerBeetle** | Financial Ledger | ✅ | ✅ | ✅ | ✅ | ✅ |
 
-**95 combinations. One CLI. Zero configuration.**
+**100 combinations. One CLI. Zero configuration.**
 
 > ClickHouse is available on Windows via WSL. FerretDB v1 is natively supported on Windows (uses plain PostgreSQL backend); v2 requires macOS/Linux.
 
@@ -128,6 +129,15 @@ spindb connect vectors                            # Open web dashboard
 
 > Weaviate is an AI-native vector database. REST API on default port 8080, gRPC on port+1. Uses classes/collections.
 
+### TigerBeetle
+
+```bash
+spindb create ledger --engine tigerbeetle --start
+spindb connect ledger                            # Open REPL
+```
+
+> TigerBeetle is a high-performance financial ledger database. Custom binary protocol on default port 3000. Uses REPL for interaction.
+
 ### Enhanced Shells & Visual Tools
 
 ```bash
@@ -140,7 +150,7 @@ spindb connect mydb --ui                         # Built-in Web UI (DuckDB)
 ### Any Engine
 
 ```bash
-spindb create mydb --engine [postgresql|mysql|mariadb|mongodb|ferretdb|redis|valkey|clickhouse|sqlite|duckdb|qdrant|meilisearch|couchdb|cockroachdb|surrealdb|questdb|typedb|influxdb|weaviate]
+spindb create mydb --engine [postgresql|mysql|mariadb|mongodb|ferretdb|redis|valkey|clickhouse|sqlite|duckdb|qdrant|meilisearch|couchdb|cockroachdb|surrealdb|questdb|typedb|influxdb|weaviate|tigerbeetle]
 spindb start mydb
 spindb connect mydb
 spindb backup mydb
@@ -182,7 +192,7 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 
 | Feature | SpinDB | DBngin | Postgres.app | Laragon |
 |---------|--------|--------|--------------|---------|
-| **Engines supported** | 19 | 3 (PG/MySQL/Redis) | 1 (PostgreSQL) | 4 (PG/MySQL/MariaDB/MongoDB) |
+| **Engines supported** | 20 | 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 |
@@ -198,7 +208,7 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 
 | Feature | SpinDB | Docker Desktop | Podman | OrbStack |
 |---------|--------|----------------|--------|----------|
-| **Engines supported** | 19 unified | Any (manual setup) | Any (manual setup) | Any (manual setup) |
+| **Engines supported** | 20 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 |
@@ -214,7 +224,7 @@ SpinDB runs databases as **native processes** with **isolated data directories**
 
 | Feature | SpinDB | Homebrew | apt/winget | asdf-vm |
 |---------|--------|----------|------------|---------|
-| **Engines supported** | 19 unified | Many (separate formulas) | Many (separate packages) | Many (plugins) |
+| **Engines supported** | 20 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 | ✅ | ❌ | ❌ | ❌ |
@@ -285,6 +295,7 @@ See [DEPLOY.md](DEPLOY.md) for comprehensive deployment documentation.
 - **ClickHouse Windows** - Not supported (hostdb doesn't build for Windows).
 - **FerretDB Windows** - v1 supported natively (plain PostgreSQL backend). v2 not supported (postgresql-documentdb has startup issues); use WSL for v2.
 - **Qdrant, Meilisearch, CouchDB, Weaviate** - Use REST API instead of CLI shell. Access via HTTP at the configured port.
+- **TigerBeetle** - Custom binary protocol only. No SQL or REST API. Interact via REPL (`spindb connect`) or client libraries.
 
 ---
 
@@ -405,7 +416,7 @@ See [ENGINE_CHECKLIST.md](ENGINE_CHECKLIST.md) for adding new database engines.
 
 SpinDB is powered by:
 
-- **[hostdb](https://github.com/robertjbass/hostdb)** - Pre-compiled database binaries for 19 engines across all major platforms. Makes Docker-free multi-version database support possible.
+- **[hostdb](https://github.com/robertjbass/hostdb)** - Pre-compiled database binaries for 20 engines across all major platforms. Makes Docker-free multi-version database support possible.
 
 ---
 

package/cli/commands/create.ts

@@ -28,6 +28,7 @@ import {
   isV1 as isFerretDBv1,
 } from '../../engines/ferretdb/version-maps'
 import type { BaseEngine } from '../../engines/base-engine'
+import { getEngineMetadata } from '../helpers'
 
 /**
  * Simplified SQLite container creation flow
@@ -160,6 +161,7 @@ async function createSqliteContainer(
 
   // Display success
   if (json) {
+    const metadata = await getEngineMetadata('sqlite')
     console.log(
       JSON.stringify({
         success: true,
@@ -170,6 +172,7 @@ async function createSqliteContainer(
         database: containerName,
         connectionString,
         restored: !!restoreLocation,
+        ...metadata,
       }),
     )
   } else {
@@ -329,6 +332,7 @@ async function createDuckDBContainer(
 
   // Display success
   if (json) {
+    const metadata = await getEngineMetadata('duckdb')
     console.log(
       JSON.stringify({
         success: true,
@@ -339,6 +343,7 @@ async function createDuckDBContainer(
         database: containerName,
         connectionString,
         restored: !!restoreLocation,
+        ...metadata,
       }),
     )
   } else {
@@ -1096,6 +1101,7 @@ export const createCommand = new Command('create')
           const connectionString = dbEngine.getConnectionString(finalConfig)
 
           if (options.json) {
+            const metadata = await getEngineMetadata(finalConfig.engine)
             console.log(
               JSON.stringify({
                 success: true,
@@ -1107,6 +1113,7 @@ export const createCommand = new Command('create')
                 connectionString,
                 status: finalConfig.status,
                 restored: !!restoreLocation,
+                ...metadata,
               }),
             )
           } else {

package/cli/commands/databases.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander'
 import chalk from 'chalk'
 import { containerManager } from '../../core/container-manager'
 import { uiError, uiSuccess } from '../ui/theme'
+import { getEngineMetadata } from '../helpers'
 
 /**
  * CLI command for managing database tracking within containers.
@@ -59,16 +60,20 @@ databasesCommand
           }
 
           if (options.json) {
-            const result = containers.map((c) => {
-              const rawDatabases = c.databases || []
-              const databases = [...new Set([c.database, ...rawDatabases])]
-              return {
-                container: c.name,
-                engine: c.engine,
-                primary: c.database,
-                databases,
-              }
-            })
+            const result = await Promise.all(
+              containers.map(async (c) => {
+                const rawDatabases = c.databases || []
+                const databases = [...new Set([c.database, ...rawDatabases])]
+                const metadata = await getEngineMetadata(c.engine)
+                return {
+                  container: c.name,
+                  engine: c.engine,
+                  primary: c.database,
+                  databases,
+                  ...metadata,
+                }
+              }),
+            )
             console.log(JSON.stringify(result, null, 2))
           } else {
             console.log()
@@ -121,8 +126,8 @@ databasesCommand
         const databases = [...new Set([config.database, ...rawDatabases])]
 
         if (options.json) {
-          // Return the full container config - it's already JSON and has all the info
-          console.log(JSON.stringify(config, null, 2))
+          const metadata = await getEngineMetadata(config.engine)
+          console.log(JSON.stringify({ ...config, ...metadata }, null, 2))
         } else {
           console.log()
           console.log(chalk.bold(`Databases in "${container}":`))

package/cli/commands/delete.ts

@@ -6,6 +6,7 @@ import { getEngine } from '../../engines'
 import { promptContainerSelect, promptConfirm } from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
 import { uiWarning } from '../ui/theme'
+import { getEngineMetadata } from '../helpers'
 
 export const deleteCommand = new Command('delete')
   .alias('rm')
@@ -113,12 +114,14 @@ export const deleteCommand = new Command('delete')
         deleteSpinner?.succeed(`Container "${containerName}" deleted`)
 
         if (options.json) {
+          const metadata = await getEngineMetadata(config.engine)
           console.log(
             JSON.stringify({
               success: true,
               deleted: containerName,
               container: containerName,
               engine: config.engine,
+              ...metadata,
             }),
           )
         }

package/cli/commands/engines.ts

@@ -30,7 +30,11 @@ import { promptConfirm } from '../ui/prompts'
 import { createSpinner } from '../ui/spinner'
 import { uiError, uiWarning, uiInfo, uiSuccess, formatBytes } from '../ui/theme'
 import { getEngineIcon } from '../constants'
-import { getInstalledEngines, getInstalledPostgresEngines } from '../helpers'
+import {
+  getInstalledEngines,
+  getInstalledPostgresEngines,
+  getEngineMetadata,
+} from '../helpers'
 import { Engine, Platform } from '../../types'
 import {
   loadEnginesJson,
@@ -55,6 +59,7 @@ import { questdbBinaryManager } from '../../engines/questdb/binary-manager'
 import { typedbBinaryManager } from '../../engines/typedb/binary-manager'
 import { influxdbBinaryManager } from '../../engines/influxdb/binary-manager'
 import { weaviateBinaryManager } from '../../engines/weaviate/binary-manager'
+import { tigerbeetleBinaryManager } from '../../engines/tigerbeetle/binary-manager'
 import {
   DEFAULT_DOCUMENTDB_VERSION,
   DEFAULT_V1_POSTGRESQL_VERSION,
@@ -397,7 +402,13 @@ async function listEngines(options: { json?: boolean }): Promise<void> {
   const engines = await getInstalledEngines()
 
   if (options.json) {
-    console.log(JSON.stringify(engines, null, 2))
+    const enginesWithMetadata = await Promise.all(
+      engines.map(async (e) => ({
+        ...e,
+        ...(await getEngineMetadata(e.engine)),
+      })),
+    )
+    console.log(JSON.stringify(enginesWithMetadata, null, 2))
     return
   }
 
@@ -473,6 +484,7 @@ async function listEngines(options: { json?: boolean }): Promise<void> {
     typedb: 'TypeDB',
     valkey: 'Valkey',
     weaviate: 'Weaviate',
+    tigerbeetle: 'TigerBeetle',
   }
 
   // Group engines by name for summary
@@ -1775,9 +1787,53 @@ enginesCommand
         return
       }
 
+      if (['tigerbeetle', 'tb'].includes(normalizedEngine)) {
+        if (!version) {
+          console.error(uiError('TigerBeetle requires a version (e.g., 0.16)'))
+          process.exit(1)
+        }
+
+        const engine = getEngine(Engine.TigerBeetle)
+
+        const spinner = createSpinner(
+          `Checking TigerBeetle ${version} binaries...`,
+        )
+        spinner.start()
+
+        let wasCached = false
+        await engine.ensureBinaries(version, ({ stage, message }) => {
+          if (stage === 'cached') {
+            wasCached = true
+            spinner.text = `TigerBeetle ${version} binaries ready (cached)`
+          } else {
+            spinner.text = message
+          }
+        })
+
+        if (wasCached) {
+          spinner.succeed(`TigerBeetle ${version} binaries already installed`)
+        } else {
+          spinner.succeed(`TigerBeetle ${version} binaries downloaded`)
+        }
+
+        // Show the path for reference
+        const { platform: tbPlatform, arch: tbArch } =
+          platformService.getPlatformInfo()
+        const tbFullVersion = tigerbeetleBinaryManager.getFullVersion(version)
+        const binPath = paths.getBinaryPath({
+          engine: 'tigerbeetle',
+          version: tbFullVersion,
+          platform: tbPlatform,
+          arch: tbArch,
+        })
+        console.log(chalk.gray(`  Location: ${binPath}`))
+
+        return
+      }
+
       console.error(
         uiError(
-          `Unknown engine "${engineName}". Supported: postgresql, mysql, mariadb, sqlite, duckdb, mongodb, ferretdb, redis, valkey, clickhouse, qdrant, meilisearch, couchdb, cockroachdb, surrealdb, questdb, typedb, influxdb, weaviate`,
+          `Unknown engine "${engineName}". Supported: postgresql, mysql, mariadb, sqlite, duckdb, mongodb, ferretdb, redis, valkey, clickhouse, qdrant, meilisearch, couchdb, cockroachdb, surrealdb, questdb, typedb, influxdb, weaviate, tigerbeetle`,
         ),
       )
       process.exit(1)

package/cli/commands/info.ts

@@ -10,6 +10,7 @@ import { getEngine } from '../../engines'
 import { uiError, uiInfo, header } from '../ui/theme'
 import { getEngineIcon } from '../constants'
 import { isFileBasedEngine, type ContainerConfig } from '../../types'
+import { getEngineMetadata } from '../helpers'
 
 function formatDate(dateString: string): string {
   const date = new Date(dateString)
@@ -43,6 +44,7 @@ async function displayContainerInfo(
   })
 
   if (options.json) {
+    const metadata = await getEngineMetadata(config.engine)
     console.log(
       JSON.stringify(
         {
@@ -50,6 +52,7 @@ async function displayContainerInfo(
           status: actualStatus,
           connectionString,
           dataDir,
+          ...metadata,
         },
         null,
         2,
@@ -147,11 +150,13 @@ async function displayAllContainersInfo(
         const dataDir = paths.getContainerDataPath(config.name, {
           engine: config.engine,
         })
+        const metadata = await getEngineMetadata(config.engine)
         return {
           ...config,
           status: actualStatus,
           connectionString,
           dataDir,
+          ...metadata,
         }
       }),
     )

package/cli/commands/list.ts

@@ -14,6 +14,7 @@ import {
   getRegistryForEngine,
   type UnregisteredFile,
 } from '../../engines/file-based-utils'
+import { getEngineMetadata } from '../helpers'
 
 type UnregisteredFileWithEngine = UnregisteredFile & { engine: Engine }
 
@@ -159,6 +160,7 @@ export const listCommand = new Command('list')
         const containersWithSize = await Promise.all(
           containers.map(async (container) => ({
             ...container,
+            ...(await getEngineMetadata(container.engine)),
             sizeBytes: await getContainerSize(container),
           })),
         )

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

@@ -228,6 +228,8 @@ function validateConnectionString(
         return 'Connection string must start with http:// or https://'
       }
       break
+    case Engine.TigerBeetle:
+      return 'TigerBeetle does not support remote dumps (custom binary protocol)'
     case Engine.SQLite:
     case Engine.DuckDB:
       return 'File-based engines do not support remote connection strings'

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

@@ -49,6 +49,7 @@ function generatePreviewLine(mode: IconMode): string {
       [Engine.TypeDB]: '[TB]',
       [Engine.InfluxDB]: '[IX]',
       [Engine.Weaviate]: '[WV]',
+      [Engine.TigerBeetle]: '[TT]',
     }
     const icons = PREVIEW_ENGINES.map((engine) => {
       const icon = ASCII_ICONS[engine] || '[??]'
@@ -79,6 +80,7 @@ function generatePreviewLine(mode: IconMode): string {
       [Engine.TypeDB]: '\ue706',
       [Engine.InfluxDB]: '\udb85\udf95',
       [Engine.Weaviate]: '\uf0e8',
+      [Engine.TigerBeetle]: '\uf0d6',
     }
     const icons = PREVIEW_ENGINES.map((engine) => {
       const icon = NERD_ICONS[engine] || '\ue706'
@@ -109,6 +111,7 @@ function generatePreviewLine(mode: IconMode): string {
     [Engine.TypeDB]: '\u{1F916}',
     [Engine.InfluxDB]: '\u{1F4C8}',
     [Engine.Weaviate]: '\u{1F52E}',
+    [Engine.TigerBeetle]: '\u{1F42F}',
   }
   const icons = PREVIEW_ENGINES.map((engine) => EMOJI_ICONS[engine] || '\u25A3')
   return icons.join(' ')

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

@@ -288,6 +288,13 @@ export async function handleOpenShell(
     engineSpecificInstalled = false
     engineSpecificValue = null
     engineSpecificInstallValue = null
+  } else if (config.engine === 'tigerbeetle') {
+    // TigerBeetle uses tigerbeetle repl command
+    defaultShellName = 'tigerbeetle repl'
+    engineSpecificCli = null
+    engineSpecificInstalled = false
+    engineSpecificValue = null
+    engineSpecificInstallValue = null
   } else {
     defaultShellName = 'psql'
     engineSpecificCli = 'pgcli'
@@ -1737,6 +1744,22 @@ async function launchShell(
       shellArgs = ['console', ...getConsoleBaseArgs(config.port)]
     }
     installHint = 'spindb engines download typedb'
+  } else if (config.engine === 'tigerbeetle') {
+    // TigerBeetle uses tigerbeetle repl command
+    // Cluster ID 0 is the default for local single-node development.
+    // TigerBeetle format/start also use cluster 0 (see engines/tigerbeetle/index.ts).
+    const clusterId = 0
+    const engine = getEngine(config.engine)
+    const tigerbeetlePath = await engine
+      .getTigerBeetlePath(config.version)
+      .catch(() => null)
+    shellCmd = tigerbeetlePath || 'tigerbeetle'
+    shellArgs = [
+      'repl',
+      `--cluster=${clusterId}`,
+      `--addresses=127.0.0.1:${config.port}`,
+    ]
+    installHint = 'spindb engines download tigerbeetle'
   } else {
     // PostgreSQL default shell - look up downloaded binary path
     const psqlPath = await configManager.getBinaryPath('psql')

package/cli/commands/restore.ts

@@ -20,6 +20,7 @@ import { platformService } from '../../core/platform-service'
 import { TransactionManager } from '../../core/transaction-manager'
 import { isFileBasedEngine } from '../../types'
 import { logDebug } from '../../core/error-handler'
+import { getEngineMetadata } from '../helpers'
 
 export const restoreCommand = new Command('restore')
   .description('Restore a backup to a container')
@@ -502,6 +503,7 @@ export const restoreCommand = new Command('restore')
         )
 
         if (options.json) {
+          const metadata = await getEngineMetadata(engineName)
           console.log(
             JSON.stringify({
               success: true,
@@ -512,6 +514,7 @@ export const restoreCommand = new Command('restore')
               sourceType: options.fromUrl ? 'remote' : 'file',
               connectionString,
               overwritten: databaseExists,
+              ...metadata,
             }),
           )
         } else {

package/cli/commands/start.ts

@@ -11,6 +11,7 @@ import { createSpinner } from '../ui/spinner'
 import { uiWarning } from '../ui/theme'
 import { Engine, isFileBasedEngine } from '../../types'
 import { exitWithError, logDebug } from '../../core/error-handler'
+import { getEngineMetadata } from '../helpers'
 
 export const startCommand = new Command('start')
   .description('Start a container')
@@ -189,6 +190,7 @@ export const startCommand = new Command('start')
       const connectionString = engine.getConnectionString(config)
 
       if (options.json) {
+        const metadata = await getEngineMetadata(config.engine)
         console.log(
           JSON.stringify({
             success: true,
@@ -197,6 +199,7 @@ export const startCommand = new Command('start')
             port: result.finalPort,
             connectionString,
             portChanged: result.retriesUsed > 0,
+            ...metadata,
           }),
         )
       } else {

package/cli/commands/url.ts

@@ -4,6 +4,7 @@ import { platformService } from '../../core/platform-service'
 import { getEngine } from '../../engines'
 import { promptContainerSelect } from '../ui/prompts'
 import { uiError, uiWarning, uiSuccess } from '../ui/theme'
+import { getEngineMetadata } from '../helpers'
 
 export const urlCommand = new Command('url')
   .alias('connection-string')
@@ -55,6 +56,7 @@ export const urlCommand = new Command('url')
         )
 
         if (options.json) {
+          const metadata = await getEngineMetadata(config.engine)
           const jsonOutput =
             config.engine === 'sqlite'
               ? {
@@ -62,6 +64,7 @@ export const urlCommand = new Command('url')
                   path: databaseName,
                   engine: config.engine,
                   container: config.name,
+                  ...metadata,
                 }
               : {
                   connectionString,
@@ -71,6 +74,7 @@ export const urlCommand = new Command('url')
                   user: config.engine === 'postgresql' ? 'postgres' : 'root',
                   engine: config.engine,
                   container: config.name,
+                  ...metadata,
                 }
           console.log(JSON.stringify(jsonOutput, null, 2))
           return

package/cli/constants.ts

@@ -78,6 +78,7 @@ export const ENGINE_BRAND_COLORS: Record<Engine, BrandColor> = {
   [Engine.TypeDB]: { foreground: '#FFFFFF', background: '#7B2D8E' }, // White on purple
   [Engine.InfluxDB]: { foreground: '#FFFFFF', background: '#9394FF' }, // White on indigo/purple
   [Engine.Weaviate]: { foreground: '#FFFFFF', background: '#00D1A8' }, // White on green
+  [Engine.TigerBeetle]: { foreground: '#FFFFFF', background: '#FF6600' }, // White on orange
 }
 
 // ASCII fallback icons - work in any terminal
@@ -101,6 +102,7 @@ const ASCII_ICONS: Record<Engine, string> = {
   [Engine.TypeDB]: '[TB]',
   [Engine.InfluxDB]: '[IX]',
   [Engine.Weaviate]: '[WV]',
+  [Engine.TigerBeetle]: '[TT]',
 }
 
 // Nerd Font icons - require a patched font
@@ -125,6 +127,7 @@ const NERD_ICONS: Record<Engine, string> = {
   [Engine.TypeDB]: '\ue706', // nf-dev-database (knowledge graph)
   [Engine.InfluxDB]: '\udb85\udf95', // nf-md-chart-line (time-series)
   [Engine.Weaviate]: '\uf0e8', // nf-fa-sitemap (vector graph)
+  [Engine.TigerBeetle]: '\uf0d6', // nf-fa-money (financial ledger)
 }
 
 // Emoji icons - original icons, inconsistent width across terminals
@@ -148,6 +151,7 @@ const EMOJI_ICONS: Record<Engine, string> = {
   [Engine.TypeDB]: '🤖',
   [Engine.InfluxDB]: '📈',
   [Engine.Weaviate]: '🔮',
+  [Engine.TigerBeetle]: '🐯',
 }
 
 const DEFAULT_ICONS: Record<IconMode, string> = {