spindb 0.37.2 → 0.38.0

package/engines/questdb/restore.ts

@@ -1,260 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-/**
- * QuestDB Version Maps
- *
- * IMPORTANT: Keep this in sync with hostdb databases.json:
- * https://github.com/robertjbass/hostdb/blob/main/databases.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

@@ -1,121 +0,0 @@
-/**
- * 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/engines/redis/README.md

@@ -1,173 +0,0 @@
-# Redis Engine Implementation
-
-## Overview
-
-Redis is an in-memory key-value store with persistence. SpinDB downloads Redis binaries from hostdb and manages them with `redis-server` and `redis-cli`.
-
-## Platform Support
-
-| Platform | Architecture | Status | Notes |
-|----------|--------------|--------|-------|
-| darwin | x64 | Supported | Uses hostdb binaries |
-| darwin | arm64 | Supported | Uses hostdb binaries (Apple Silicon) |
-| linux | x64 | Supported | Uses hostdb binaries |
-| linux | arm64 | Supported | Uses hostdb binaries |
-| win32 | x64 | Supported | Uses hostdb binaries |
-
-## Binary Packaging
-
-### Archive Format
-- **Unix (macOS/Linux)**: `tar.gz`
-- **Windows**: `zip`
-
-### Archive Structure
-```text
-redis/
-└── bin/
-    ├── redis-server     # Server binary
-    ├── redis-cli        # Client CLI
-    ├── redis-benchmark  # Benchmarking tool
-    └── redis-check-*    # Diagnostic tools
-```
-
-### Version Map Sync
-
-```typescript
-export const REDIS_VERSION_MAP: Record<string, string> = {
-  '7': '7.4.7',
-  '8': '8.4.0',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-Redis uses `BaseBinaryManager` with standard key-value store configuration.
-
-### Version Parsing
-
-- **Version output format**: `Redis server v=7.4.7 sha=00000000:0 malloc=jemalloc-5.3.0...`
-- **Parse pattern**: `/v=(\d+\.\d+\.\d+)/` then fallback to `/(\d+\.\d+\.\d+)/`
-
-### Default Configuration
-
-- **Default Port**: 6379 (auto-increments on conflict)
-- **Databases**: 16 numbered databases (0-15)
-- **PID File**: `redis.pid` in container directory
-- **Persistence**: RDB snapshots enabled by default
-
-### Generated Configuration
-
-SpinDB generates `redis.conf` with:
-```
-port {port}
-bind 127.0.0.1
-dir {dataDir}
-daemonize yes     # Unix: uses native daemonization
-logfile {logFile}
-pidfile {pidFile}
-
-# Persistence - RDB snapshots
-save 900 1
-save 300 10
-save 60 10000
-dbfilename dump.rdb
-
-# AOF disabled for local dev
-appendonly no
-```
-
-### Windows Daemonize Workaround
-
-Redis on Windows doesn't support `daemonize yes`. SpinDB uses:
-- `detached: true` spawn option
-- `windowsHide: true` to hide console window
-- Manual PID file management
-
-### Connection String Format
-
-```text
-redis://127.0.0.1:{port}/{database}
-```
-
-Where `{database}` is 0-15.
-
-## Backup & Restore
-
-### Backup Formats
-
-| Format | Extension | Tool | Notes |
-|--------|-----------|------|-------|
-| text | `.redis` | Custom RESP | Human-readable commands |
-| rdb | `.rdb` | Native RDB | Binary snapshot |
-
-### Text Format (Merge vs Replace)
-
-The text backup format supports two restore modes:
-- **Merge**: Adds keys without clearing existing data
-- **Replace (flush)**: Clears database before restoring
-
-### RDB Format
-
-RDB backups are native Redis snapshots. Restore requires stopping Redis, replacing `dump.rdb`, and restarting.
-
-## Database Model
-
-Redis uses numbered databases (0-15) instead of named databases:
-- `createDatabase()` is effectively a no-op (databases always exist)
-- `dropDatabase()` uses `FLUSHDB` to clear all keys in that database
-
-## Integration Test Notes
-
-### Reserved Ports
-
-Integration tests use reserved ports:
-- **Test Ports**: 6399-6401 (NOT 6379)
-
-### Test Fixtures
-
-Located in `tests/fixtures/redis/seeds/`:
-- Key-value pairs for testing
-
-## Docker E2E Test Notes
-
-Redis Docker E2E tests verify:
-- Server lifecycle
-- Key-value operations
-- RDB and text backup/restore
-- Database switching (SELECT)
-
-## Known Issues & Gotchas
-
-### 1. Windows Daemonization
-
-Redis doesn't natively support `daemonize yes` on Windows. SpinDB spawns a detached process instead and manages the PID file manually.
-
-### 2. Database Numbers
-
-Redis databases are always 0-15. Attempting to use a number outside this range throws an error.
-
-### 3. Memory-First Storage
-
-Redis is primarily in-memory. Large datasets may consume significant RAM. RDB snapshots persist to disk.
-
-### 4. AOF Disabled
-
-Append-Only File (AOF) is disabled by default in SpinDB for simpler local development. Enable it manually in `redis.conf` for durability.
-
-### 5. Graceful Shutdown
-
-Redis uses `SHUTDOWN SAVE` command for graceful shutdown with data persistence. Falls back to SIGTERM if CLI fails.
-
-## CI/CD Notes
-
-### GitHub Actions Cache Step
-
-```yaml
-- name: Cache Redis binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/redis-*
-    key: redis-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/redis/version-maps.ts') }}
-```