spindb 0.26.2 → 0.27.3

package/engines/questdb/restore.ts

@@ -0,0 +1,235 @@
+/**
+ * QuestDB Restore Implementation
+ *
+ * Restores SQL backups to QuestDB using PostgreSQL wire protocol.
+ * QuestDB is compatible with psql for executing SQL statements.
+ */
+
+import { open, readFile } from 'fs/promises'
+import { spawn, spawnSync } from 'child_process'
+import { configManager } from '../../core/config-manager'
+import { logDebug } from '../../core/error-handler'
+import type { BackupFormat, RestoreResult } from '../../types'
+
+// Read only the first 8KB for format detection
+const HEADER_SIZE = 8192
+
+/**
+ * Detect the backup format from file content
+ */
+export async function detectBackupFormat(filePath: string): Promise<BackupFormat> {
+  // Check extension first
+  const lowerPath = filePath.toLowerCase()
+  if (lowerPath.endsWith('.sql')) {
+    return {
+      format: 'sql',
+      description: 'SQL dump file',
+      restoreCommand: 'psql',
+    }
+  }
+
+  // Read file header for content-based detection
+  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/)
+
+  // Check for SQL patterns
+  for (const line of lines.slice(0, 20)) {
+    const trimmed = line.trim().toUpperCase()
+    if (
+      trimmed.startsWith('CREATE TABLE') ||
+      trimmed.startsWith('INSERT INTO') ||
+      trimmed.startsWith('-- QUESTDB') ||
+      trimmed.startsWith('-- TABLE:')
+    ) {
+      return {
+        format: 'sql',
+        description: 'SQL dump file',
+        restoreCommand: 'psql',
+      }
+    }
+  }
+
+  return {
+    format: 'unknown',
+    description: 'Unknown format',
+    restoreCommand: '',
+  }
+}
+
+/**
+ * Parse a QuestDB/PostgreSQL connection string
+ */
+export function parseConnectionString(connectionString: string): {
+  host: string
+  port: number
+  database: string
+  user: string
+  password?: string
+} {
+  // Support both postgresql:// and questdb:// schemes
+  let url: URL
+  try {
+    // Replace questdb:// with postgresql:// for URL parsing
+    const normalized = connectionString.replace(/^questdb:\/\//, 'postgresql://')
+    url = new URL(normalized)
+  } catch {
+    throw new Error(
+      `Invalid connection string: ${connectionString}\n` +
+        'Expected format: postgresql://user:password@host:port/database',
+    )
+  }
+
+  return {
+    host: url.hostname || '127.0.0.1',
+    port: url.port ? parseInt(url.port, 10) : 8812,
+    database: url.pathname.replace(/^\//, '') || 'qdb',
+    user: url.username || 'admin',
+    password: url.password || 'quest',
+  }
+}
+
+export type RestoreOptions = {
+  containerName: string
+  port: number
+  database: string
+  version: string
+  clean?: boolean
+}
+
+/**
+ * Restore a backup to QuestDB
+ */
+export async function restoreBackup(
+  backupPath: string,
+  options: RestoreOptions,
+): Promise<RestoreResult> {
+  const { port, database, clean } = options
+
+  // Detect backup format
+  const format = await detectBackupFormat(backupPath)
+  if (format.format === 'unknown') {
+    throw new Error(
+      `Cannot detect backup format for: ${backupPath}\n` +
+        'Supported formats: .sql (SQL dump)',
+    )
+  }
+
+  logDebug(`Restoring ${format.format} backup to QuestDB database ${database}`)
+
+  // Find psql binary
+  let psqlPath = await configManager.getBinaryPath('psql')
+  if (!psqlPath) {
+    psqlPath = 'psql'
+  }
+
+  // Build restore command args
+  // Use ON_ERROR_STOP to fail fast on any SQL error (otherwise psql continues silently)
+  const args = [
+    '-h', '127.0.0.1',
+    '-p', String(port),
+    '-U', 'admin',
+    '-d', database,
+    '-v', 'ON_ERROR_STOP=1',
+    '-f', backupPath,
+  ]
+
+  // For clean restore, drop existing tables before restoring
+  if (clean) {
+    logDebug('Clean restore requested - extracting table names from backup')
+
+    // Read the SQL file and extract table names from CREATE TABLE statements
+    const sqlContent = await readFile(backupPath, 'utf-8')
+    // Match CREATE TABLE [IF NOT EXISTS] "table_name" or CREATE TABLE [IF NOT EXISTS] table_name
+    const tableRegex = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|(\w+))/gi
+    const tables: string[] = []
+    let match
+
+    while ((match = tableRegex.exec(sqlContent)) !== null) {
+      const tableName = match[1] || match[2]
+      if (tableName && !tables.includes(tableName)) {
+        tables.push(tableName)
+      }
+    }
+
+    if (tables.length > 0) {
+      logDebug(`Found ${tables.length} tables to drop: ${tables.join(', ')}`)
+
+      // Execute DROP TABLE IF EXISTS for each table
+      for (const table of tables) {
+        const dropQuery = `DROP TABLE IF EXISTS "${table}";`
+        logDebug(`Executing: ${dropQuery}`)
+
+        const dropResult = spawnSync(psqlPath!, [
+          '-h', '127.0.0.1',
+          '-p', String(port),
+          '-U', 'admin',
+          '-d', database,
+          '-c', dropQuery,
+        ], {
+          env: { ...process.env, PGPASSWORD: 'quest' },
+        })
+
+        if (dropResult.error) {
+          logDebug(`Warning: Failed to drop table ${table}: ${dropResult.error.message}`)
+        } else if (dropResult.status !== 0) {
+          logDebug(`Warning: DROP TABLE ${table} exited with code ${dropResult.status}`)
+        }
+      }
+    } else {
+      logDebug('No CREATE TABLE statements found in backup')
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(psqlPath!, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, PGPASSWORD: 'quest' },
+    })
+
+    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: format.format,
+          stdout,
+          stderr,
+          code: 0,
+        })
+      } else if (stderr.includes('already exists')) {
+        // Treat "already exists" as non-fatal (table recreation during restore)
+        resolve({
+          format: format.format,
+          stdout,
+          stderr,
+          code: code ?? 1,
+        })
+      } else {
+        reject(new Error(`Restore failed: ${stderr || `exit code ${code}`}`))
+      }
+    })
+
+    proc.on('error', (err) => {
+      reject(new Error(`Failed to execute psql: ${err.message}`))
+    })
+  })
+}

package/engines/questdb/version-maps.ts

@@ -0,0 +1,37 @@
+/**
+ * QuestDB Version Maps
+ *
+ * IMPORTANT: Keep this in sync with hostdb releases.json:
+ * https://github.com/robertjbass/hostdb/blob/main/releases.json
+ *
+ * QuestDB uses standard semantic versioning (e.g., 9.2.3)
+ */
+
+export const QUESTDB_VERSION_MAP: Record<string, string> = {
+  '9': '9.2.3',
+  '9.2': '9.2.3',
+  '9.2.3': '9.2.3',
+}
+
+export const SUPPORTED_MAJOR_VERSIONS = ['9']
+export const FALLBACK_VERSION_MAP = QUESTDB_VERSION_MAP
+
+/**
+ * Normalize a version string to a full version
+ * e.g., '9' -> '9.2.3'
+ */
+export function normalizeVersion(version: string): string {
+  // If already a full version, return as-is
+  if (/^\d+\.\d+\.\d+$/.test(version)) {
+    return version
+  }
+
+  // Try to look up in version map
+  const fullVersion = QUESTDB_VERSION_MAP[version]
+  if (fullVersion) {
+    return fullVersion
+  }
+
+  // Return as-is if not found
+  return version
+}

package/engines/questdb/version-validator.ts

@@ -0,0 +1,121 @@
+/**
+ * QuestDB Version Validator
+ *
+ * Provides version parsing, validation, and comparison utilities.
+ */
+
+import { SUPPORTED_MAJOR_VERSIONS, QUESTDB_VERSION_MAP } from './version-maps'
+
+export type ParsedVersion = {
+  major: number
+  minor: number
+  patch: number
+  full: string
+}
+
+/**
+ * Parse a version string into components
+ * @param version Version string (e.g., '9.2.3', '9.2', '9')
+ * @returns Parsed version or null if invalid
+ */
+export function parseVersion(version: string): ParsedVersion | null {
+  // Match version patterns: 9.2.3, 9.2, 9
+  const match = version.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/)
+  if (!match) return null
+
+  const major = parseInt(match[1], 10)
+  const minor = match[2] ? parseInt(match[2], 10) : 0
+  const patch = match[3] ? parseInt(match[3], 10) : 0
+
+  return {
+    major,
+    minor,
+    patch,
+    full: `${major}.${minor}.${patch}`,
+  }
+}
+
+/**
+ * Check if a version is supported
+ */
+export function isVersionSupported(version: string): boolean {
+  const parsed = parseVersion(version)
+  if (!parsed) return false
+
+  const majorStr = String(parsed.major)
+  return SUPPORTED_MAJOR_VERSIONS.includes(majorStr)
+}
+
+/**
+ * Get the major version string from a version
+ */
+export function getMajorVersion(version: string): string | null {
+  const parsed = parseVersion(version)
+  if (!parsed) return null
+  return String(parsed.major)
+}
+
+/**
+ * Compare two versions
+ * @returns -1 if a < b, 0 if a == b, 1 if a > b
+ */
+export function compareVersions(a: string, b: string): number {
+  const parsedA = parseVersion(a)
+  const parsedB = parseVersion(b)
+
+  if (!parsedA || !parsedB) {
+    // Fall back to string comparison if parsing fails
+    return a.localeCompare(b)
+  }
+
+  if (parsedA.major !== parsedB.major) {
+    return parsedA.major - parsedB.major
+  }
+  if (parsedA.minor !== parsedB.minor) {
+    return parsedA.minor - parsedB.minor
+  }
+  return parsedA.patch - parsedB.patch
+}
+
+/**
+ * Check if two versions are compatible for backup/restore
+ * QuestDB allows restoring to same or newer major version
+ */
+export function isVersionCompatible(
+  sourceVersion: string,
+  targetVersion: string,
+): boolean {
+  const sourceMajor = getMajorVersion(sourceVersion)
+  const targetMajor = getMajorVersion(targetVersion)
+
+  if (!sourceMajor || !targetMajor) return false
+
+  // Same major version is always compatible
+  if (sourceMajor === targetMajor) return true
+
+  // Target major must be >= source major
+  return parseInt(targetMajor, 10) >= parseInt(sourceMajor, 10)
+}
+
+/**
+ * Resolve a version alias to full version
+ */
+export function resolveVersion(version: string): string {
+  // Check if it's already a full version in the map
+  if (QUESTDB_VERSION_MAP[version]) {
+    return QUESTDB_VERSION_MAP[version]
+  }
+
+  // If already a full version format, return as-is
+  if (/^\d+\.\d+\.\d+$/.test(version)) {
+    return version
+  }
+
+  // Try major version lookup
+  const majorVersion = getMajorVersion(version)
+  if (majorVersion && QUESTDB_VERSION_MAP[majorVersion]) {
+    return QUESTDB_VERSION_MAP[majorVersion]
+  }
+
+  return version
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spindb",
-  "version": "0.26.2",
+  "version": "0.27.3",
   "description": "Zero-config Docker-free local database containers. Create, backup, and clone a variety of popular databases.",
   "type": "module",
   "bin": {
@@ -71,6 +71,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "inquirer": "^9.3.7",
+    "inquirer-autocomplete-prompt": "^3.0.1",
     "ora": "^8.1.1",
     "string-width": "^8.1.0",
     "tsx": "^4.7.0",
@@ -79,6 +80,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/inquirer": "^9.0.7",
+    "@types/inquirer-autocomplete-prompt": "^3.0.3",
     "@types/node": "^20.10.0",
     "@types/unzipper": "^0.10.11",
     "eslint": "^9.39.1",

package/types/index.ts

@@ -36,6 +36,7 @@ export enum Engine {
   CouchDB = 'couchdb',
   CockroachDB = 'cockroachdb',
   SurrealDB = 'surrealdb',
+  QuestDB = 'questdb',
 }
 
 // Supported operating systems (matches Node.js process.platform)
@@ -71,6 +72,7 @@ export const ALL_ENGINES = [
   Engine.CouchDB,
   Engine.CockroachDB,
   Engine.SurrealDB,
+  Engine.QuestDB,
 ] as const
 
 // File-based engines (no server process, data stored in user project directories)
@@ -199,6 +201,7 @@ export type FerretDBFormat = 'sql' | 'custom'
 export type CouchDBFormat = 'json'
 export type CockroachDBFormat = 'sql'
 export type SurrealDBFormat = 'surql'
+export type QuestDBFormat = 'sql'
 
 // Union of all backup formats
 export type BackupFormatType =
@@ -217,6 +220,7 @@ export type BackupFormatType =
   | CouchDBFormat
   | CockroachDBFormat
   | SurrealDBFormat
+  | QuestDBFormat
 
 // Mapping from Engine to its corresponding backup format type
 type EngineFormatMap = {
@@ -235,6 +239,7 @@ type EngineFormatMap = {
   [Engine.CouchDB]: CouchDBFormat
   [Engine.CockroachDB]: CockroachDBFormat
   [Engine.SurrealDB]: SurrealDBFormat
+  [Engine.QuestDB]: QuestDBFormat
 }
 
 // Helper type to get format type for a specific engine
@@ -344,6 +349,8 @@ export type BinaryTool =
   | 'cockroach'
   // SurrealDB tools
   | 'surreal'
+  // QuestDB tools
+  | 'questdb'
   // Enhanced shells (optional)
   | 'pgcli'
   | 'mycli'
@@ -423,6 +430,8 @@ export type SpinDBConfig = {
     cockroach?: BinaryConfig
     // SurrealDB tools
     surreal?: BinaryConfig
+    // QuestDB tools
+    questdb?: BinaryConfig
     // Enhanced shells (optional)
     pgcli?: BinaryConfig
     mycli?: BinaryConfig