spindb 0.24.0 → 0.26.2

package/engines/surrealdb/restore.ts

@@ -0,0 +1,297 @@
+/**
+ * SurrealDB restore module
+ * Supports SurrealQL-based restores using surreal import
+ */
+
+import { spawn } from 'child_process'
+import { open } from 'fs/promises'
+import { existsSync, statSync } from 'fs'
+import { logDebug } from '../../core/error-handler'
+import { requireSurrealPath } from './cli-utils'
+import type { BackupFormat, RestoreResult } from '../../types'
+
+/**
+ * SurrealQL keywords that indicate a SurrealDB backup
+ */
+const SURREALQL_KEYWORDS = [
+  'DEFINE',
+  'CREATE',
+  'INSERT',
+  'UPDATE',
+  'SELECT',
+  'DELETE',
+  'RELATE',
+  'LET',
+  'BEGIN',
+  'COMMIT',
+  'USE NS',
+  'USE DB',
+  'OPTION IMPORT',
+]
+
+/**
+ * Check if file content looks like SurrealQL
+ * Only reads first 8KB to avoid loading large files into memory
+ */
+async function looksLikeSurql(filePath: string): Promise<boolean> {
+  try {
+    const HEADER_SIZE = 8192
+    const buffer = Buffer.alloc(HEADER_SIZE)
+
+    const fd = await open(filePath, 'r')
+    let bytesRead: number
+    try {
+      const result = await fd.read(buffer, 0, HEADER_SIZE, 0)
+      bytesRead = result.bytesRead
+    } finally {
+      await fd.close()
+    }
+
+    const content = buffer.toString('utf-8', 0, bytesRead)
+    const lines = content.split(/\r?\n/)
+
+    let surqlStatementsFound = 0
+    const linesToCheck = 20
+    let checkedLines = 0
+
+    for (const line of lines) {
+      if (checkedLines >= linesToCheck) break
+
+      const trimmed = line.trim().toUpperCase()
+
+      // Skip empty lines and comments
+      if (!trimmed || trimmed.startsWith('--') || trimmed.startsWith('#')) continue
+
+      checkedLines++
+
+      // Check for SurrealQL keywords
+      for (const keyword of SURREALQL_KEYWORDS) {
+        if (trimmed.startsWith(keyword)) {
+          surqlStatementsFound++
+          break
+        }
+      }
+
+      if (surqlStatementsFound >= 2) {
+        return true
+      }
+    }
+
+    return surqlStatementsFound > 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Detect backup format from file
+ * Supports:
+ * - SurrealQL: Schema + data statements
+ */
+export async function detectBackupFormat(
+  filePath: string,
+): Promise<BackupFormat> {
+  if (!existsSync(filePath)) {
+    throw new Error(`Backup file not found: ${filePath}`)
+  }
+
+  const stats = statSync(filePath)
+
+  if (stats.isDirectory()) {
+    return {
+      format: 'unknown',
+      description: 'Directory found - SurrealDB restore expects a single file',
+      restoreCommand:
+        'SurrealDB requires a single .surql file for restore',
+    }
+  }
+
+  // Check file extension first for .surql files
+  if (filePath.endsWith('.surql')) {
+    return {
+      format: 'surql',
+      description: 'SurrealDB SurrealQL backup',
+      restoreCommand:
+        'Execute SurrealQL statements via surreal import (spindb restore handles this)',
+    }
+  }
+
+  // Content-based detection
+  if (await looksLikeSurql(filePath)) {
+    return {
+      format: 'surql',
+      description: 'SurrealDB SurrealQL backup (detected by content)',
+      restoreCommand:
+        'Execute SurrealQL statements via surreal import (spindb restore handles this)',
+    }
+  }
+
+  return {
+    format: 'unknown',
+    description: 'Unknown backup format',
+    restoreCommand: 'Use .surql file with SurrealQL statements',
+  }
+}
+
+// Restore options for SurrealDB
+export type RestoreOptions = {
+  containerName: string
+  port: number
+  database?: string
+  version?: string
+}
+
+/**
+ * Restore from SurrealQL backup using surreal import
+ */
+async function restoreSurqlBackup(
+  backupPath: string,
+  port: number,
+  namespace: string,
+  database: string,
+  version?: string,
+): Promise<RestoreResult> {
+  const surrealPath = await requireSurrealPath(version)
+
+  return new Promise<RestoreResult>((resolve, reject) => {
+    const args = [
+      'import',
+      '--endpoint', `http://127.0.0.1:${port}`,
+      '--user', 'root',
+      '--pass', 'root',
+      '--ns', namespace,
+      '--db', database,
+      backupPath,
+    ]
+
+    logDebug(`Running: surreal ${args.join(' ')}`)
+
+    const proc = spawn(surrealPath, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    let stdout = ''
+    let stderr = ''
+
+    proc.stdout.on('data', (data: Buffer) => {
+      stdout += data.toString()
+    })
+
+    proc.stderr.on('data', (data: Buffer) => {
+      stderr += data.toString()
+    })
+
+    proc.on('close', (code) => {
+      if (code === 0) {
+        resolve({
+          format: 'surql',
+          stdout: stdout || 'SurrealQL statements imported successfully',
+          stderr: stderr || undefined,
+          code: 0,
+        })
+      } else {
+        reject(
+          new Error(
+            `surreal import exited with code ${code}${stderr ? `: ${stderr}` : ''}`,
+          ),
+        )
+      }
+    })
+
+    proc.on('error', (error) => {
+      reject(new Error(`Failed to spawn surreal import: ${error.message}`))
+    })
+  })
+}
+
+/**
+ * Restore from backup
+ * Supports:
+ * - SurrealQL: Execute statements via surreal import
+ */
+export async function restoreBackup(
+  backupPath: string,
+  options: RestoreOptions,
+): Promise<RestoreResult> {
+  const { containerName, port, database = 'default', version } = options
+  // Use container name as namespace (convert dashes to underscores)
+  const namespace = containerName.replace(/-/g, '_')
+
+  if (!existsSync(backupPath)) {
+    throw new Error(`Backup file not found: ${backupPath}`)
+  }
+
+  // Detect backup format
+  const format = await detectBackupFormat(backupPath)
+  logDebug(`Detected backup format: ${format.format}`)
+
+  if (format.format === 'surql') {
+    return restoreSurqlBackup(backupPath, port, namespace, database, version)
+  }
+
+  throw new Error(
+    `Invalid backup format: ${format.format}. Use .surql file with SurrealQL statements.`,
+  )
+}
+
+/**
+ * Parse SurrealDB connection string
+ * Format: surrealdb://[user:password@]host[:port][/namespace/database]
+ * Or: ws://host:port or http://host:port
+ */
+export function parseConnectionString(connectionString: string): {
+  host: string
+  port: number
+  namespace: string
+  database: string
+  user?: string
+  password?: string
+} {
+  if (!connectionString || typeof connectionString !== 'string') {
+    throw new Error(
+      'Invalid SurrealDB connection string: expected a non-empty string',
+    )
+  }
+
+  let url: URL
+  try {
+    url = new URL(connectionString)
+  } catch (error) {
+    // Mask credentials in error message if present
+    const sanitized = connectionString.replace(
+      /\/\/([^:]+):([^@]+)@/,
+      '//***:***@',
+    )
+    throw new Error(
+      `Invalid SurrealDB connection string: "${sanitized}". ` +
+        `Expected format: surrealdb://[user:password@]host[:port][/namespace/database]`,
+      { cause: error },
+    )
+  }
+
+  // Validate protocol
+  const validProtocols = ['surrealdb:', 'ws:', 'wss:', 'http:', 'https:']
+  if (!validProtocols.includes(url.protocol)) {
+    throw new Error(
+      `Invalid SurrealDB connection string: unsupported protocol "${url.protocol}". ` +
+        `Expected one of: ${validProtocols.join(', ')}`,
+    )
+  }
+
+  const host = url.hostname || '127.0.0.1'
+  const port = parseInt(url.port, 10) || 8000
+
+  // Parse namespace/database from pathname (e.g., /myns/mydb)
+  const pathParts = url.pathname.split('/').filter(Boolean)
+  const namespace = pathParts[0] || 'test'
+  const database = pathParts[1] || 'test'
+
+  return {
+    host,
+    port,
+    namespace,
+    database,
+    user: url.username || undefined,
+    password: url.password || undefined,
+  }
+}

package/engines/surrealdb/version-maps.ts

@@ -0,0 +1,41 @@
+/**
+ * SurrealDB version mapping
+ *
+ * Maps short version aliases to full versions from hostdb releases.
+ * MUST stay in sync with hostdb releases.json
+ */
+
+// Full version map for SurrealDB
+export const SURREALDB_VERSION_MAP: Record<string, string> = {
+  '2': '2.3.2',
+  '2.3': '2.3.2',
+  '2.3.2': '2.3.2',
+}
+
+// Supported major versions (for CLI display)
+export const SUPPORTED_MAJOR_VERSIONS = ['2']
+
+// Default version
+export const DEFAULT_VERSION = '2'
+
+/**
+ * Normalize a version string to its full version
+ * e.g., '2' -> '2.3.2', '2.3' -> '2.3.2'
+ */
+export function normalizeVersion(version: string): string {
+  return SURREALDB_VERSION_MAP[version] || version
+}
+
+/**
+ * Check if a version is supported
+ */
+export function isVersionSupported(version: string): boolean {
+  return version in SURREALDB_VERSION_MAP
+}
+
+/**
+ * Get the latest patch version for a major version
+ */
+export function getLatestPatch(majorVersion: string): string | undefined {
+  return SURREALDB_VERSION_MAP[majorVersion]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.24.0",
+  "version": "0.26.2",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",
   "type": "module",
   "bin": {
@@ -42,6 +42,8 @@
     "qdrant",
     "meilisearch",
     "couchdb",
+    "cockroachdb",
+    "surrealdb",
     "ferretdb",
     "sqlite",
     "duckdb",

package/types/index.ts

@@ -34,6 +34,8 @@ export enum Engine {
   Qdrant = 'qdrant',
   Meilisearch = 'meilisearch',
   CouchDB = 'couchdb',
+  CockroachDB = 'cockroachdb',
+  SurrealDB = 'surrealdb',
 }
 
 // Supported operating systems (matches Node.js process.platform)
@@ -67,6 +69,8 @@ export const ALL_ENGINES = [
   Engine.Qdrant,
   Engine.Meilisearch,
   Engine.CouchDB,
+  Engine.CockroachDB,
+  Engine.SurrealDB,
 ] as const
 
 // File-based engines (no server process, data stored in user project directories)
@@ -193,6 +197,8 @@ export type QdrantFormat = 'snapshot'
 export type MeilisearchFormat = 'snapshot'
 export type FerretDBFormat = 'sql' | 'custom'
 export type CouchDBFormat = 'json'
+export type CockroachDBFormat = 'sql'
+export type SurrealDBFormat = 'surql'
 
 // Union of all backup formats
 export type BackupFormatType =
@@ -209,6 +215,8 @@ export type BackupFormatType =
   | QdrantFormat
   | MeilisearchFormat
   | CouchDBFormat
+  | CockroachDBFormat
+  | SurrealDBFormat
 
 // Mapping from Engine to its corresponding backup format type
 type EngineFormatMap = {
@@ -225,6 +233,8 @@ type EngineFormatMap = {
   [Engine.Qdrant]: QdrantFormat
   [Engine.Meilisearch]: MeilisearchFormat
   [Engine.CouchDB]: CouchDBFormat
+  [Engine.CockroachDB]: CockroachDBFormat
+  [Engine.SurrealDB]: SurrealDBFormat
 }
 
 // Helper type to get format type for a specific engine
@@ -330,6 +340,10 @@ export type BinaryTool =
   | 'ferretdb'
   // CouchDB tools
   | 'couchdb'
+  // CockroachDB tools
+  | 'cockroach'
+  // SurrealDB tools
+  | 'surreal'
   // Enhanced shells (optional)
   | 'pgcli'
   | 'mycli'
@@ -405,6 +419,10 @@ export type SpinDBConfig = {
     ferretdb?: BinaryConfig
     // CouchDB tools
     couchdb?: BinaryConfig
+    // CockroachDB tools
+    cockroach?: BinaryConfig
+    // SurrealDB tools
+    surreal?: BinaryConfig
     // Enhanced shells (optional)
     pgcli?: BinaryConfig
     mycli?: BinaryConfig