spindb 0.36.2 → 0.37.1

package/engines/tigerbeetle/restore.ts

@@ -0,0 +1,130 @@
+/**
+ * TigerBeetle restore module
+ * Supports restoring from a TigerBeetle data file backup.
+ *
+ * Restore copies the backup data file into the container's data directory.
+ * The server must be stopped before restore.
+ */
+
+import { copyFile, mkdir, stat } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { logDebug } from '../../core/error-handler'
+import type { BackupFormat, RestoreResult } from '../../types'
+
+/**
+ * Detect backup format from a file path.
+ * TigerBeetle backups are single binary data files.
+ */
+export async function detectBackupFormat(
+  filePath: string,
+): Promise<BackupFormat> {
+  if (!existsSync(filePath)) {
+    throw new Error(`Backup file not found: ${filePath}`)
+  }
+
+  const stats = await stat(filePath)
+
+  // TigerBeetle data files are regular files (not directories)
+  if (stats.isFile()) {
+    if (filePath.endsWith('.tigerbeetle')) {
+      return {
+        format: 'binary',
+        description: 'TigerBeetle data file',
+        restoreCommand: 'Copy to data directory (spindb restore handles this)',
+      }
+    }
+
+    // Check for common backup naming patterns
+    return {
+      format: 'binary',
+      description: 'TigerBeetle data file (assumed from file)',
+      restoreCommand: 'Copy to data directory (spindb restore handles this)',
+    }
+  }
+
+  return {
+    format: 'unknown',
+    description: 'Unknown backup format',
+    restoreCommand: 'Use a TigerBeetle data file (.tigerbeetle) for restore',
+  }
+}
+
+// Restore options for TigerBeetle
+export type RestoreOptions = {
+  containerName: string
+  dataDir: string
+}
+
+/**
+ * Restore from a TigerBeetle data file backup.
+ * Copies the backup file into the container's data directory.
+ */
+export async function restoreBackup(
+  backupPath: string,
+  options: RestoreOptions,
+): Promise<RestoreResult> {
+  const { dataDir } = options
+
+  if (!existsSync(backupPath)) {
+    throw new Error(`Backup not found: ${backupPath}`)
+  }
+
+  const format = await detectBackupFormat(backupPath)
+  logDebug(`Detected backup format: ${format.format}`)
+
+  // Ensure data directory exists
+  if (!existsSync(dataDir)) {
+    await mkdir(dataDir, { recursive: true })
+  }
+
+  const targetPath = join(dataDir, '0_0.tigerbeetle')
+
+  logDebug(`Restoring TigerBeetle data file to: ${targetPath}`)
+  await copyFile(backupPath, targetPath)
+
+  return {
+    format: 'binary',
+    stdout: `Restored TigerBeetle data file to ${targetPath}`,
+    code: 0,
+  }
+}
+
+/**
+ * Parse TigerBeetle connection string
+ * Format: host:port or 127.0.0.1:port
+ *
+ * TigerBeetle uses a custom binary protocol (no URI scheme).
+ */
+export function parseConnectionString(connectionString: string): {
+  host: string
+  port: number
+} {
+  if (!connectionString || typeof connectionString !== 'string') {
+    throw new Error(
+      'Invalid TigerBeetle connection string: expected a non-empty string',
+    )
+  }
+
+  const trimmed = connectionString.trim()
+
+  // Parse host:port format
+  const parts = trimmed.split(':')
+  if (parts.length !== 2) {
+    throw new Error(
+      `Invalid TigerBeetle connection string: "${trimmed}". ` +
+        'Expected format: host:port (e.g., 127.0.0.1:3000)',
+    )
+  }
+
+  const host = parts[0] || '127.0.0.1'
+  const port = parseInt(parts[1], 10)
+
+  if (isNaN(port) || port <= 0 || port > 65535) {
+    throw new Error(
+      `Invalid TigerBeetle port: "${parts[1]}". Expected a number between 1 and 65535.`,
+    )
+  }
+
+  return { host, port }
+}

package/engines/tigerbeetle/version-maps.ts

@@ -0,0 +1,68 @@
+/**
+ * TigerBeetle Version Maps
+ *
+ * TEMPORARY: This version map will be replaced by the hostdb npm package once published.
+ * Until then, manually keep this in sync with robertjbass/hostdb releases.json:
+ * https://github.com/robertjbass/hostdb/blob/main/releases.json
+ *
+ * When updating versions:
+ * 1. Check hostdb releases.json for available versions
+ * 2. Update TIGERBEETLE_VERSION_MAP to match
+ */
+
+import { logDebug } from '../../core/error-handler'
+
+/**
+ * Map of major TigerBeetle versions to their latest stable patch versions.
+ * Must match versions available in hostdb releases.json.
+ *
+ * TigerBeetle uses xy-format grouping (like MariaDB/ClickHouse):
+ * 0.16.70 groups as "0.16"
+ */
+export const TIGERBEETLE_VERSION_MAP: Record<string, string> = {
+  // 1-part: major version → latest
+  '0': '0.16.70',
+  // 2-part: major.minor → latest patch
+  '0.16': '0.16.70',
+  // 3-part: exact version (identity mapping)
+  '0.16.70': '0.16.70',
+}
+
+/**
+ * Supported major TigerBeetle versions (2-part format).
+ * Derived from TIGERBEETLE_VERSION_MAP keys to avoid duplication.
+ * Used for grouping and display purposes.
+ */
+export const SUPPORTED_MAJOR_VERSIONS = Object.keys(
+  TIGERBEETLE_VERSION_MAP,
+).filter((key) => key.split('.').length === 2)
+
+/**
+ * Get the full version string for a major version.
+ *
+ * @param majorVersion - Major version (e.g., '0.16')
+ * @returns Full version string (e.g., '0.16.70') or null if not supported
+ */
+export function getFullVersion(majorVersion: string): string | null {
+  return TIGERBEETLE_VERSION_MAP[majorVersion] || null
+}
+
+/**
+ * Normalize a version string to X.Y.Z format.
+ *
+ * @param version - Version string (e.g., '0', '0.16', '0.16.70')
+ * @returns Normalized version (e.g., '0.16.70')
+ */
+export function normalizeVersion(version: string): string {
+  // If it's a version key in the map (major, major.minor, or full), return the mapped version
+  const fullVersion = TIGERBEETLE_VERSION_MAP[version]
+  if (fullVersion) {
+    return fullVersion
+  }
+
+  // Unknown version - log debug and return as-is
+  logDebug(
+    `TigerBeetle version '${version}' not in version map, may not be available in hostdb`,
+  )
+  return version
+}

package/engines/tigerbeetle/version-validator.ts

@@ -0,0 +1,126 @@
+/**
+ * TigerBeetle version validation utilities
+ * Handles version parsing, comparison, and compatibility checking
+ */
+
+/**
+ * Parse a TigerBeetle version string into components
+ * Handles formats like "0.16.70", "0.16", "v0.16.70"
+ */
+export function parseVersion(versionString: string): {
+  major: number
+  minor: number
+  patch: number
+  raw: string
+} | null {
+  const cleaned = versionString.replace(/^v/, '').trim()
+  if (!cleaned) return null
+
+  const parts = cleaned.split('.')
+
+  const major = parseInt(parts[0], 10)
+  const minor = parts[1] ? parseInt(parts[1], 10) : 0
+  const patch = parts[2] ? parseInt(parts[2], 10) : 0
+
+  if (isNaN(major)) return null
+  if (parts[1] && isNaN(minor)) return null
+  if (parts[2] && isNaN(patch)) return null
+
+  return { major, minor, patch, raw: cleaned }
+}
+
+/**
+ * Check if a TigerBeetle version is supported by SpinDB
+ * Minimum supported version: 0.16.0
+ */
+export function isVersionSupported(version: string): boolean {
+  const parsed = parseVersion(version)
+  if (!parsed) return false
+
+  // Support 0.16+
+  if (parsed.major === 0) {
+    return parsed.minor >= 16
+  }
+  return parsed.major >= 1
+}
+
+/**
+ * Get major version from full version string (xy-format: 2-part)
+ * e.g., "0.16.70" -> "0.16"
+ */
+export function getMajorVersion(version: string): string {
+  const parsed = parseVersion(version)
+  if (!parsed) return version
+  return `${parsed.major}.${parsed.minor}`
+}
+
+/**
+ * Get major.minor version from full version string.
+ * Intentional alias for getMajorVersion — both return the 2-part xy-format
+ * version (e.g., "0.16"). Kept as a separate export for API consistency
+ * with other engine version validators.
+ */
+export function getMajorMinorVersion(version: string): string {
+  return getMajorVersion(version)
+}
+
+/**
+ * Compare two TigerBeetle versions
+ * Returns: -1 if a < b, 0 if a == b, 1 if a > b, null if either version cannot be parsed
+ */
+export function compareVersions(a: string, b: string): number | null {
+  const parsedA = parseVersion(a)
+  const parsedB = parseVersion(b)
+
+  if (!parsedA || !parsedB) {
+    return null
+  }
+
+  if (parsedA.major !== parsedB.major) {
+    return parsedA.major < parsedB.major ? -1 : 1
+  }
+  if (parsedA.minor !== parsedB.minor) {
+    return parsedA.minor < parsedB.minor ? -1 : 1
+  }
+  if (parsedA.patch !== parsedB.patch) {
+    return parsedA.patch < parsedB.patch ? -1 : 1
+  }
+  return 0
+}
+
+/**
+ * Check if a backup version is compatible with the restore version
+ * TigerBeetle data files are generally compatible within minor versions
+ */
+export function isVersionCompatible(
+  backupVersion: string,
+  restoreVersion: string,
+): { compatible: boolean; warning?: string } {
+  const backup = parseVersion(backupVersion)
+  const restore = parseVersion(restoreVersion)
+
+  if (!backup || !restore) {
+    return {
+      compatible: true,
+      warning: 'Could not parse versions, proceeding with restore',
+    }
+  }
+
+  // Must be same major.minor for TigerBeetle
+  if (backup.major !== restore.major || backup.minor !== restore.minor) {
+    return {
+      compatible: false,
+      warning: `Cannot restore TigerBeetle ${backupVersion} data to ${restoreVersion} server. Major.minor versions must match.`,
+    }
+  }
+
+  return { compatible: true }
+}
+
+/**
+ * Validate that a version string matches supported format
+ */
+export function isValidVersionFormat(version: string): boolean {
+  const parsed = parseVersion(version)
+  return parsed !== null
+}

package/engines/valkey/index.ts

@@ -601,6 +601,20 @@ export class ValkeyEngine 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(
+                  `Valkey 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,
@@ -703,10 +717,7 @@ export class ValkeyEngine extends BaseEngine {
             } catch {
               logContent = ''
             }
-            const libError = detectLibraryError(
-              stderr + logContent,
-              'Valkey',
-            )
+            const libError = detectLibraryError(stderr + logContent, 'Valkey')
             if (libError) {
               reject(new Error(libError))
               return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.36.2",
+  "version": "0.37.1",
   "author": "Bob Bass <bob@bbass.co>",
   "license": "PolyForm-Noncommercial-1.0.0",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",
@@ -57,6 +57,7 @@
     "typedb",
     "influxdb",
     "weaviate",
+    "tigerbeetle",
     "layerbase",
     "docker-free",
     "tui",

package/types/index.ts

@@ -40,6 +40,7 @@ export enum Engine {
   TypeDB = 'typedb',
   InfluxDB = 'influxdb',
   Weaviate = 'weaviate',
+  TigerBeetle = 'tigerbeetle',
 }
 
 // Icon display mode for engine icons in CLI output
@@ -82,6 +83,7 @@ export const ALL_ENGINES = [
   Engine.TypeDB,
   Engine.InfluxDB,
   Engine.Weaviate,
+  Engine.TigerBeetle,
 ] as const
 
 // File-based engines (no server process, data stored in user project directories)
@@ -214,6 +216,7 @@ export type QuestDBFormat = 'sql'
 export type TypeDBFormat = 'typeql'
 export type InfluxDBFormat = 'sql'
 export type WeaviateFormat = 'snapshot'
+export type TigerBeetleFormat = 'binary'
 
 // Query command types
 export type QueryResultRow = Record<string, unknown>
@@ -294,6 +297,7 @@ export type BackupFormatType =
   | TypeDBFormat
   | InfluxDBFormat
   | WeaviateFormat
+  | TigerBeetleFormat
 
 // Mapping from Engine to its corresponding backup format type
 type EngineFormatMap = {
@@ -316,6 +320,7 @@ type EngineFormatMap = {
   [Engine.TypeDB]: TypeDBFormat
   [Engine.InfluxDB]: InfluxDBFormat
   [Engine.Weaviate]: WeaviateFormat
+  [Engine.TigerBeetle]: TigerBeetleFormat
 }
 
 // Helper type to get format type for a specific engine
@@ -434,6 +439,8 @@ export type BinaryTool =
   | 'influxdb3'
   // Weaviate tools
   | 'weaviate'
+  // TigerBeetle tools
+  | 'tigerbeetle'
   // Web panels
   | 'pgweb'
   // TUI tools
@@ -532,6 +539,8 @@ export type SpinDBConfig = {
     influxdb3?: BinaryConfig
     // Weaviate tools
     weaviate?: BinaryConfig
+    // TigerBeetle tools
+    tigerbeetle?: BinaryConfig
     // Web panels
     pgweb?: BinaryConfig
     // TUI tools