spindb 0.36.2 → 0.37.2

package/cli/helpers.ts

@@ -5,9 +5,28 @@ import { execFile } from 'child_process'
 import { promisify } from 'util'
 import { paths } from '../config/paths'
 import { platformService } from '../core/platform-service'
+import { type Engine } from '../types'
+import { getEngineConfig } from '../config/engines-registry'
 
 const execFileAsync = promisify(execFile)
 
+export type EngineMetadata = {
+  queryLanguage: string
+  runtime: 'server' | 'embedded'
+  connectionScheme: string | null
+}
+
+export async function getEngineMetadata(
+  engine: string,
+): Promise<EngineMetadata> {
+  const config = await getEngineConfig(engine as Engine)
+  return {
+    queryLanguage: config.queryLanguage,
+    runtime: config.runtime,
+    connectionScheme: config.connectionScheme,
+  }
+}
+
 // Parsed engine directory info
 type ParsedEngineDir = {
   version: string
@@ -254,6 +273,16 @@ export type InstalledWeaviateEngine = {
   source: 'downloaded'
 }
 
+export type InstalledTigerBeetleEngine = {
+  engine: 'tigerbeetle'
+  version: string
+  platform: string
+  arch: string
+  path: string
+  sizeBytes: number
+  source: 'downloaded'
+}
+
 export type InstalledEngine =
   | InstalledPostgresEngine
   | InstalledMariadbEngine
@@ -274,6 +303,7 @@ export type InstalledEngine =
   | InstalledTypeDBEngine
   | InstalledInfluxDBEngine
   | InstalledWeaviateEngine
+  | InstalledTigerBeetleEngine
 
 async function getPostgresVersion(binPath: string): Promise<string | null> {
   const ext = platformService.getExecutableExtension()
@@ -1347,6 +1377,64 @@ async function getInstalledWeaviateEngines(): Promise<
   return engines
 }
 
+// Get TigerBeetle version from binary path
+async function getTigerBeetleVersion(binPath: string): Promise<string | null> {
+  const ext = platformService.getExecutableExtension()
+  const tigerbeetlePath = join(binPath, 'bin', `tigerbeetle${ext}`)
+  if (!existsSync(tigerbeetlePath)) {
+    return null
+  }
+
+  try {
+    const { stdout } = await execFileAsync(tigerbeetlePath, ['version'])
+    // Parse output like "TigerBeetle v0.16.70" or "0.16.70"
+    const match = stdout.match(/(?:TigerBeetle\s+)?v?(\d+\.\d+\.\d+)/)
+    return match ? match[1] : null
+  } catch {
+    return null
+  }
+}
+
+// Get installed TigerBeetle engines from downloaded binaries
+async function getInstalledTigerBeetleEngines(): Promise<
+  InstalledTigerBeetleEngine[]
+> {
+  const binDir = paths.bin
+
+  if (!existsSync(binDir)) {
+    return []
+  }
+
+  const entries = await readdir(binDir, { withFileTypes: true })
+  const engines: InstalledTigerBeetleEngine[] = []
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (!entry.name.startsWith('tigerbeetle-')) continue
+
+    const parsed = parseEngineDirectory(entry.name, 'tigerbeetle-', binDir)
+    if (!parsed) continue
+
+    const actualVersion =
+      (await getTigerBeetleVersion(parsed.path)) || parsed.version
+    const sizeBytes = await calculateDirectorySize(parsed.path)
+
+    engines.push({
+      engine: 'tigerbeetle',
+      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)
@@ -1384,6 +1472,7 @@ const ENGINE_PREFIXES = [
   'typedb-',
   'influxdb-',
   'weaviate-',
+  'tigerbeetle-',
 ] as const
 
 /**
@@ -1433,6 +1522,7 @@ export async function getInstalledEngines(): Promise<InstalledEngine[]> {
     typedbEngines,
     influxdbEngines,
     weaviateEngines,
+    tigerbeetleEngines,
   ] = await Promise.all([
     getInstalledPostgresEngines(),
     getInstalledMariadbEngines(),
@@ -1453,6 +1543,7 @@ export async function getInstalledEngines(): Promise<InstalledEngine[]> {
     getInstalledTypeDBEngines(),
     getInstalledInfluxDBEngines(),
     getInstalledWeaviateEngines(),
+    getInstalledTigerBeetleEngines(),
   ])
 
   return [
@@ -1475,6 +1566,7 @@ export async function getInstalledEngines(): Promise<InstalledEngine[]> {
     ...typedbEngines,
     ...influxdbEngines,
     ...weaviateEngines,
+    ...tigerbeetleEngines,
   ]
 }
 
@@ -1497,4 +1589,5 @@ export {
   getInstalledTypeDBEngines,
   getInstalledInfluxDBEngines,
   getInstalledWeaviateEngines,
+  getInstalledTigerBeetleEngines,
 }

package/config/backup-formats.ts

@@ -29,6 +29,7 @@ import {
   type TypeDBFormat,
   type InfluxDBFormat,
   type WeaviateFormat,
+  type TigerBeetleFormat,
   type BackupFormatType,
 } from '../types'
 
@@ -67,6 +68,7 @@ export const BACKUP_FORMATS: {
   [Engine.TypeDB]: EngineBackupFormats<TypeDBFormat>
   [Engine.InfluxDB]: EngineBackupFormats<InfluxDBFormat>
   [Engine.Weaviate]: EngineBackupFormats<WeaviateFormat>
+  [Engine.TigerBeetle]: EngineBackupFormats<TigerBeetleFormat>
 } = {
   [Engine.PostgreSQL]: {
     formats: {
@@ -350,6 +352,18 @@ export const BACKUP_FORMATS: {
     supportsFormatChoice: false, // Only snapshot format supported
     defaultFormat: 'snapshot',
   },
+  [Engine.TigerBeetle]: {
+    formats: {
+      binary: {
+        extension: '.tigerbeetle',
+        label: '.tigerbeetle',
+        description: 'TigerBeetle data file - full database copy',
+        spinnerLabel: 'binary',
+      },
+    },
+    supportsFormatChoice: false, // Only binary format supported
+    defaultFormat: 'binary',
+  },
 }
 
 /**

package/config/engine-defaults.ts

@@ -278,6 +278,19 @@ export const engineDefaults: Record<Engine, EngineDefaults> = {
     clientTools: [], // Weaviate uses REST/GraphQL API, no separate CLI tools
     maxConnections: 0, // Not applicable for vector DB
   },
+  [Engine.TigerBeetle]: {
+    defaultVersion: '0.16',
+    defaultPort: 3000,
+    portRange: { start: 3000, end: 3100 },
+    latestVersion: '0.16',
+    superuser: '', // No auth
+    connectionScheme: '', // Custom binary protocol, no URI scheme
+    logFileName: 'tigerbeetle.log',
+    pidFileName: 'tigerbeetle.pid',
+    dataSubdir: 'data',
+    clientTools: ['tigerbeetle'], // Single binary serves as both server and REPL
+    maxConnections: 0, // Not applicable
+  },
 }
 
 /**

package/config/engines.json

@@ -326,6 +326,23 @@
       "clientTools": ["weaviate"],
       "licensing": "BSD-3-Clause",
       "notes": "AI-native vector database. REST API on port 8080, gRPC on port+1. Uses classes/collections instead of databases."
+    },
+    "tigerbeetle": {
+      "displayName": "TigerBeetle",
+      "icon": "🐯",
+      "status": "integrated",
+      "binarySource": "hostdb",
+      "supportedVersions": ["0.16.70"],
+      "defaultVersion": "0.16.70",
+      "defaultPort": 3000,
+      "runtime": "server",
+      "queryLanguage": "custom",
+      "scriptFileLabel": null,
+      "connectionScheme": null,
+      "superuser": null,
+      "clientTools": ["tigerbeetle"],
+      "licensing": "Apache-2.0",
+      "notes": "High-performance financial ledger database. Custom binary protocol, REPL client. Uses --development flag for local dev."
     }
   }
 }

package/core/config-manager.ts

@@ -84,6 +84,8 @@ const INFLUXDB_TOOLS: BinaryTool[] = ['influxdb3']
 
 const WEAVIATE_TOOLS: BinaryTool[] = ['weaviate']
 
+const TIGERBEETLE_TOOLS: BinaryTool[] = ['tigerbeetle']
+
 const PGWEB_TOOLS: BinaryTool[] = ['pgweb']
 
 const DBLAB_TOOLS: BinaryTool[] = ['dblab']
@@ -113,6 +115,7 @@ const ALL_TOOLS: BinaryTool[] = [
   ...TYPEDB_TOOLS,
   ...INFLUXDB_TOOLS,
   ...WEAVIATE_TOOLS,
+  ...TIGERBEETLE_TOOLS,
   ...PGWEB_TOOLS,
   ...DBLAB_TOOLS,
   ...SQLITE_TOOLS,
@@ -139,6 +142,7 @@ const ENGINE_BINARY_MAP: Partial<Record<Engine, BinaryTool[]>> = {
   [Engine.TypeDB]: TYPEDB_TOOLS,
   [Engine.InfluxDB]: INFLUXDB_TOOLS,
   [Engine.Weaviate]: WEAVIATE_TOOLS,
+  [Engine.TigerBeetle]: TIGERBEETLE_TOOLS,
 }
 
 export class ConfigManager {
@@ -637,6 +641,7 @@ export {
   TYPEDB_TOOLS,
   INFLUXDB_TOOLS,
   WEAVIATE_TOOLS,
+  TIGERBEETLE_TOOLS,
   PGWEB_TOOLS,
   DBLAB_TOOLS,
   SQLITE_TOOLS,

package/core/dependency-manager.ts

@@ -88,6 +88,8 @@ const KNOWN_BINARY_TOOLS: readonly BinaryTool[] = [
   'influxdb3',
   // Weaviate
   'weaviate',
+  // TigerBeetle
+  'tigerbeetle',
   // Web panels
   'pgweb',
   // TUI tools

package/core/docker-exporter.ts

@@ -73,6 +73,7 @@ function getEngineDisplayName(engine: Engine): string {
     [Engine.TypeDB]: 'TypeDB',
     [Engine.InfluxDB]: 'InfluxDB',
     [Engine.Weaviate]: 'Weaviate',
+    [Engine.TigerBeetle]: 'TigerBeetle',
   }
   return displayNames[engine] || engine
 }
@@ -149,6 +150,9 @@ const _ENGINE_BINARY_CONFIG: Record<
   [Engine.Weaviate]: {
     primaryBinaries: [], // REST/GraphQL API only, no CLI tools
   },
+  [Engine.TigerBeetle]: {
+    primaryBinaries: ['tigerbeetle'],
+  },
 }
 
 /**
@@ -218,6 +222,9 @@ function getConnectionStringTemplate(
     case Engine.TypeDB:
       return `typedb://<host>:${port}`
 
+    case Engine.TigerBeetle:
+      return `<host>:${port}`
+
     case Engine.SQLite:
     case Engine.DuckDB:
       return `File-based database (no network connection)`
@@ -517,6 +524,13 @@ echo "No authentication required for local InfluxDB 3.x"
       userCreationCommands = `
 # TypeDB community edition does not support user management
 echo "No authentication required"
+`
+      break
+
+    case Engine.TigerBeetle:
+      userCreationCommands = `
+# TigerBeetle has no authentication
+echo "No authentication required"
 `
       break
 
@@ -1315,6 +1329,9 @@ export async function getDockerConnectionString(
     case Engine.TypeDB:
       return `typedb://${host}:${port}`
 
+    case Engine.TigerBeetle:
+      return `${host}:${port}`
+
     case Engine.SQLite:
     case Engine.DuckDB:
       return `File-based database (no network connection)`

package/core/library-env.ts

@@ -58,8 +58,7 @@ export function detectLibraryError(
     lower.includes('dyld:') ||
     lower.includes('dyld[')
   ) {
-    const needsOpenssl =
-      lower.includes('libssl') || lower.includes('libcrypto')
+    const needsOpenssl = lower.includes('libssl') || lower.includes('libcrypto')
 
     if (needsOpenssl && plat === 'darwin') {
       return (
@@ -97,8 +96,7 @@ export function detectLibraryError(
     lower.includes('error while loading shared libraries') ||
     lower.includes('cannot open shared object file')
   ) {
-    const needsOpenssl =
-      lower.includes('libssl') || lower.includes('libcrypto')
+    const needsOpenssl = lower.includes('libssl') || lower.includes('libcrypto')
 
     if (needsOpenssl) {
       return (

package/core/update-manager.ts

@@ -2,6 +2,7 @@ import { exec } from 'child_process'
 import { promisify } from 'util'
 import { createRequire } from 'module'
 import { configManager } from './config-manager'
+import { logDebug } from './error-handler'
 
 const execAsync = promisify(exec)
 const require = createRequire(import.meta.url)
@@ -11,6 +12,17 @@ const CHECK_THROTTLE_MS = 24 * 60 * 60 * 1000 // 24 hours
 
 type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun'
 
+const KNOWN_PACKAGE_MANAGERS: PackageManager[] = ['pnpm', 'yarn', 'bun', 'npm']
+
+export function parseUserAgent(
+  userAgent: string | undefined,
+): PackageManager | null {
+  if (!userAgent) return null
+  const firstToken = userAgent.split('/')[0]?.toLowerCase().trim()
+  if (!firstToken) return null
+  return KNOWN_PACKAGE_MANAGERS.find((pm) => pm === firstToken) ?? null
+}
+
 export type UpdateCheckResult = {
   currentVersion: string
   latestVersion: string
@@ -75,49 +87,59 @@ export class UpdateManager {
     }
   }
 
-  // Checks pnpm, yarn, bun first since npm is the fallback
+  // Checks all PMs in parallel, falls back to npm_config_user_agent, then npm
   async detectPackageManager(): Promise<PackageManager> {
-    try {
-      const { stdout } = await execAsync('pnpm list -g spindb --json', {
-        timeout: 5000,
-        cwd: '/',
-      })
-      const data = JSON.parse(stdout) as Array<{
-        dependencies?: { spindb?: unknown }
-      }>
-      if (data[0]?.dependencies?.spindb) {
-        return 'pnpm'
-      }
-    } catch {
-      // pnpm not installed or spindb not found
+    const checks = await Promise.all([
+      this.checkGlobalInstall(
+        'pnpm',
+        'pnpm list -g spindb --json',
+        (stdout) => {
+          const data = JSON.parse(stdout) as Array<{
+            dependencies?: { spindb?: unknown }
+          }>
+          return !!data[0]?.dependencies?.spindb
+        },
+      ),
+      this.checkGlobalInstall('yarn', 'yarn global list --json', (stdout) => {
+        return stdout.includes('"spindb@')
+      }),
+      this.checkGlobalInstall('bun', 'bun pm ls -g', (stdout) => {
+        return stdout.includes('spindb@')
+      }),
+      this.checkGlobalInstall('npm', 'npm list -g spindb --json', (stdout) => {
+        const data = JSON.parse(stdout) as {
+          dependencies?: { spindb?: unknown }
+        }
+        return !!data.dependencies?.spindb
+      }),
+    ])
+
+    const globalPm = checks.find((result) => result !== null)
+    if (globalPm) {
+      logDebug(`Detected global install via ${globalPm}`)
+      return globalPm
     }
 
-    try {
-      const { stdout } = await execAsync('yarn global list --json', {
-        timeout: 5000,
-        cwd: '/',
-      })
-      // yarn outputs newline-delimited JSON, look for spindb in any line
-      if (stdout.includes('"spindb@')) {
-        return 'yarn'
-      }
-    } catch {
-      // yarn not installed or spindb not found
+    const agentPm = parseUserAgent(process.env.npm_config_user_agent)
+    if (agentPm) {
+      logDebug(`Detected package manager from user agent: ${agentPm}`)
+      return agentPm
     }
 
+    return 'npm'
+  }
+
+  private async checkGlobalInstall(
+    pm: PackageManager,
+    command: string,
+    checkOutput: (stdout: string) => boolean,
+  ): Promise<PackageManager | null> {
     try {
-      const { stdout } = await execAsync('bun pm ls -g', {
-        timeout: 5000,
-        cwd: '/',
-      })
-      if (stdout.includes('spindb@')) {
-        return 'bun'
-      }
+      const { stdout } = await execAsync(command, { timeout: 5000, cwd: '/' })
+      return checkOutput(stdout) ? pm : null
     } catch {
-      // bun not installed or spindb not found
+      return null
     }
-
-    return 'npm'
   }
 
   getInstallCommand(pm: PackageManager): string {

package/engines/base-engine.ts

@@ -169,6 +169,14 @@ export abstract class BaseEngine {
     throw new Error('influxdb3 not found')
   }
 
+  /**
+   * Get the path to the tigerbeetle binary if available
+   * Default implementation throws; TigerBeetle engine overrides this method.
+   */
+  async getTigerBeetlePath(_version?: string): Promise<string> {
+    throw new Error('tigerbeetle not found')
+  }
+
   /**
    * Get the path to the sqlite3 client if available
    * Default implementation returns null; SQLite engine overrides this method.

package/engines/index.ts

@@ -17,6 +17,7 @@ import { questdbEngine } from './questdb'
 import { typedbEngine } from './typedb'
 import { influxdbEngine } from './influxdb'
 import { weaviateEngine } from './weaviate'
+import { tigerbeetleEngine } from './tigerbeetle'
 import { platformService } from '../core/platform-service'
 import { Engine, Platform } from '../types'
 import type { BaseEngine } from './base-engine'
@@ -87,6 +88,9 @@ export const engines: Record<string, BaseEngine> = {
   // Weaviate and aliases
   [Engine.Weaviate]: weaviateEngine,
   wv: weaviateEngine,
+  // TigerBeetle and aliases
+  [Engine.TigerBeetle]: tigerbeetleEngine,
+  tb: tigerbeetleEngine,
 }
 
 // Get an engine by name

package/engines/mariadb/index.ts

@@ -259,7 +259,10 @@ export class MariaDBEngine extends BaseEngine {
       return new Promise((resolve, reject) => {
         exec(
           cmd,
-          { timeout: 120000, env: { ...process.env, ...getLibraryEnv(binPath) } },
+          {
+            timeout: 120000,
+            env: { ...process.env, ...getLibraryEnv(binPath) },
+          },
           async (error, stdout, stderr) => {
             if (error) {
               await cleanupOnFailure()
@@ -493,9 +496,7 @@ export class MariaDBEngine extends BaseEngine {
               }
 
               reject(
-                new Error(
-                  libError || 'MariaDB failed to start within timeout',
-                ),
+                new Error(libError || 'MariaDB failed to start within timeout'),
               )
             }
           }

package/engines/redis/index.ts

@@ -594,6 +594,20 @@ export class RedisEngine extends BaseEngine {
           if (settled) return
 
           if (ready) {
+            // On Windows, Cygwin binaries may fork internally, making proc.pid stale.
+            // Find the actual PID by port and update the PID file (same pattern as QuestDB).
+            try {
+              const pids = await platformService.findProcessByPort(port)
+              if (pids.length > 0 && pids[0] !== proc.pid) {
+                logDebug(
+                  `Redis actual PID ${pids[0]} differs from spawn PID ${proc.pid}, updating PID file`,
+                )
+                await writeFile(pidFile, String(pids[0]))
+              }
+            } catch {
+              // Non-fatal - PID file already has proc.pid from earlier write
+            }
+
             settled = true
             resolve({
               port,
@@ -698,10 +712,7 @@ export class RedisEngine extends BaseEngine {
             }
 
             // Check for library loading errors
-            const libError = detectLibraryError(
-              stderr + logContent,
-              'Redis',
-            )
+            const libError = detectLibraryError(stderr + logContent, 'Redis')
             if (libError) {
               reject(new Error(libError))
               return

package/engines/tigerbeetle/README.md

@@ -0,0 +1,61 @@
+# TigerBeetle Engine
+
+TigerBeetle is a high-performance financial ledger database written in Zig,
+designed for mission-critical safety and performance.
+
+## Platform Support
+
+All 5 platforms:
+- darwin-arm64
+- darwin-x64
+- linux-arm64
+- linux-x64
+- win32-x64
+
+## Binary Structure
+
+Single binary: `tigerbeetle` (handles both server and REPL client)
+
+## Two-Step Initialization
+
+TigerBeetle requires a format step before starting:
+
+1. **Format**: `tigerbeetle format --cluster=0 --replica=0 --replica-count=1 --development <data-file>`
+2. **Start**: `tigerbeetle start --addresses=127.0.0.1:<port> --development <data-file>`
+
+The `--development` flag is always passed since SpinDB is a local dev tool
+(relaxes Direct I/O requirements).
+
+## REPL Usage
+
+Connect to a running instance:
+```bash
+tigerbeetle repl --cluster=0 --addresses=127.0.0.1:<port>
+```
+
+## Version Grouping
+
+Uses xy-format: `0.16.70` groups as `0.16` (like MariaDB/ClickHouse).
+
+## Backup/Restore
+
+Stop-and-copy of the single `0_0.tigerbeetle` data file.
+The server must be stopped before backup (the file is exclusively locked).
+TigerBeetle is designed for abrupt shutdown (SIGTERM/SIGKILL are safe).
+
+## Key Characteristics
+
+- **Protocol**: Custom binary protocol (not REST, not SQL)
+- **Auth**: None
+- **Multi-database**: No (single ledger per instance)
+- **Health check**: TCP port check + PID (no HTTP endpoint)
+- **License**: Apache-2.0
+- **Default port**: 3000
+
+## Linux / Docker Note
+
+TigerBeetle uses `io_uring` for I/O on Linux. This works on regular Linux systems
+(bare metal, VMs, GitHub Actions runners) but Docker's default seccomp profile blocks
+`io_uring_*` syscalls. When running TigerBeetle inside Docker, the container must be
+started with `--security-opt seccomp=unconfined`. The `pnpm test:docker` wrapper
+handles this automatically. This does not affect macOS or Windows.

package/engines/tigerbeetle/backup.ts

@@ -0,0 +1,49 @@
+/**
+ * TigerBeetle backup module
+ * Supports stop-and-copy backup of the single data file.
+ *
+ * TigerBeetle stores all data in a single file (e.g., 0_0.tigerbeetle).
+ * Backup requires the server to be stopped first since the data file
+ * is exclusively locked by the running process.
+ */
+
+import { copyFile, mkdir, stat } from 'fs/promises'
+import { existsSync } from 'fs'
+import { dirname, join } from 'path'
+import { logDebug } from '../../core/error-handler'
+import type { BackupOptions, BackupResult } from '../../types'
+
+/**
+ * Create a backup by copying the TigerBeetle data file.
+ * The server MUST be stopped before calling this function.
+ */
+export async function createBackup(
+  dataDir: string,
+  outputPath: string,
+  _options: BackupOptions,
+): Promise<BackupResult> {
+  const dataFile = join(dataDir, '0_0.tigerbeetle')
+
+  if (!existsSync(dataFile)) {
+    throw new Error(
+      `TigerBeetle data file not found at ${dataFile}. Has the database been initialized?`,
+    )
+  }
+
+  // Ensure output parent directory exists
+  const outputDir = dirname(outputPath)
+  if (!existsSync(outputDir)) {
+    await mkdir(outputDir, { recursive: true })
+  }
+
+  logDebug(`Copying TigerBeetle data file to ${outputPath}`)
+  await copyFile(dataFile, outputPath)
+
+  const stats = await stat(outputPath)
+
+  return {
+    path: outputPath,
+    format: 'binary',
+    size: stats.size,
+  }
+}