spindb 0.37.2 → 0.38.0

package/engines/mysql/version-validator.ts

@@ -1,369 +0,0 @@
-/**
- * MySQL/MariaDB Version Validator
- *
- * Validates compatibility between mysql client version and dump file version.
- * MySQL is generally more lenient than PostgreSQL, but we still warn about:
- * - MariaDB dumps being restored to MySQL (and vice versa)
- * - Newer dumps being restored to older clients
- */
-
-import { exec } from 'child_process'
-import { promisify } from 'util'
-import { createReadStream } from 'fs'
-import { createInterface } from 'readline'
-import {
-  SpinDBError,
-  ErrorCodes,
-  logWarning,
-  logDebug,
-} from '../../core/error-handler'
-import { getMysqlClientPath } from './binary-detection'
-
-const execAsync = promisify(exec)
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export type VersionInfo = {
-  major: number
-  minor: number
-  patch: number
-  full: string
-}
-
-export type MySQLVariant = 'mysql' | 'mariadb' | 'unknown'
-
-export type DumpInfo = {
-  version: VersionInfo | null
-  variant: MySQLVariant
-  serverVersion?: string
-}
-
-export type CompatibilityResult = {
-  compatible: boolean
-  dumpInfo: DumpInfo
-  toolVersion: VersionInfo
-  toolVariant: MySQLVariant
-  warning?: string
-  error?: string
-}
-
-// =============================================================================
-// Version Parsing
-// =============================================================================
-
-/**
- * Parse version from mysql --version output
- * Examples:
- *   "mysql  Ver 8.0.35 for macos14.0 on arm64 (Homebrew)"
- *   "mysql  Ver 14.14 Distrib 5.7.44, for Linux (x86_64)" (MySQL 5.7)
- *   "mysql  Ver 15.1 Distrib 10.11.6-MariaDB, for osx10.19 (arm64)"
- *   "mysql from 11.4.3-MariaDB, client 15.2 for osx10.20 (arm64)"
- */
-export function parseToolVersion(output: string): {
-  version: VersionInfo
-  variant: MySQLVariant
-} {
-  // Check for MariaDB - must explicitly contain "mariadb" in the string
-  // Note: Both MySQL 5.7 and MariaDB use "Distrib", but only MariaDB includes "-MariaDB"
-  const isMariaDB = output.toLowerCase().includes('mariadb')
-
-  let match: RegExpMatchArray | null = null
-
-  if (isMariaDB) {
-    // MariaDB: "Distrib 10.11.6-MariaDB" or "from 11.4.3-MariaDB"
-    match = output.match(/(?:Distrib|from)\s+(\d+)\.(\d+)\.(\d+)/)
-  }
-
-  if (!match) {
-    // MySQL with Distrib: "Distrib 5.7.44" (MySQL 5.7 style)
-    match = output.match(/Distrib\s+(\d+)\.(\d+)\.(\d+)/)
-  }
-
-  if (!match) {
-    // MySQL: "Ver 8.0.35"
-    match = output.match(/Ver\s+(\d+)\.(\d+)(?:\.(\d+))?/)
-  }
-
-  if (!match) {
-    // Generic fallback
-    match = output.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
-  }
-
-  if (!match) {
-    throw new Error(`Cannot parse version from: ${output}`)
-  }
-
-  return {
-    version: {
-      major: parseInt(match[1], 10),
-      minor: parseInt(match[2], 10),
-      patch: parseInt(match[3] || '0', 10),
-      full: match[0].replace(/^(Ver|Distrib|from)\s+/, ''),
-    },
-    variant: isMariaDB ? 'mariadb' : 'mysql',
-  }
-}
-
-// Read the first N lines of a file
-async function readFirstLines(
-  filePath: string,
-  lineCount: number,
-): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const lines: string[] = []
-    const stream = createReadStream(filePath, { encoding: 'utf8' })
-    const rl = createInterface({ input: stream })
-
-    rl.on('line', (line) => {
-      lines.push(line)
-      if (lines.length >= lineCount) {
-        rl.close()
-        stream.destroy()
-      }
-    })
-
-    rl.on('close', () => {
-      resolve(lines.join('\n'))
-    })
-
-    rl.on('error', reject)
-    stream.on('error', reject)
-  })
-}
-
-/**
- * Parse version from dump file header
- *
- * MySQL dump header:
- *   -- MySQL dump 10.13  Distrib 8.0.35, for macos14.0 (arm64)
- *   -- Server version   8.0.35
- *
- * MariaDB dump header:
- *   -- MariaDB dump 10.19-11.4.3-MariaDB, for osx10.20 (arm64)
- *   -- Server version   11.4.3-MariaDB
- */
-export async function parseDumpVersion(dumpPath: string): Promise<DumpInfo> {
-  try {
-    const header = await readFirstLines(dumpPath, 30)
-
-    // Detect variant
-    let variant: MySQLVariant = 'unknown'
-    if (header.includes('MariaDB dump') || header.includes('-MariaDB')) {
-      variant = 'mariadb'
-    } else if (header.includes('MySQL dump')) {
-      variant = 'mysql'
-    }
-
-    // Try to get server version (more accurate than dump tool version)
-    // "-- Server version   8.0.35" or "-- Server version   11.4.3-MariaDB"
-    const serverMatch = header.match(
-      /--\s*Server version\s+(\d+)\.(\d+)(?:\.(\d+))?/,
-    )
-    if (serverMatch) {
-      return {
-        version: {
-          major: parseInt(serverMatch[1], 10),
-          minor: parseInt(serverMatch[2], 10),
-          patch: parseInt(serverMatch[3] || '0', 10),
-          full: `${serverMatch[1]}.${serverMatch[2]}${serverMatch[3] ? `.${serverMatch[3]}` : ''}`,
-        },
-        variant,
-        serverVersion: header.match(/--\s*Server version\s+([^\n]+)/)?.[1],
-      }
-    }
-
-    // Fall back to Distrib version in header
-    // "Distrib 8.0.35" or "10.19-11.4.3-MariaDB"
-    let distribMatch = header.match(/Distrib\s+(\d+)\.(\d+)(?:\.(\d+))?/)
-    if (!distribMatch && variant === 'mariadb') {
-      // MariaDB format: "dump 10.19-11.4.3-MariaDB"
-      distribMatch = header.match(/dump\s+[\d.]+-(\d+)\.(\d+)\.(\d+)/)
-    }
-
-    if (distribMatch) {
-      return {
-        version: {
-          major: parseInt(distribMatch[1], 10),
-          minor: parseInt(distribMatch[2], 10),
-          patch: parseInt(distribMatch[3] || '0', 10),
-          full: `${distribMatch[1]}.${distribMatch[2]}${distribMatch[3] ? `.${distribMatch[3]}` : ''}`,
-        },
-        variant,
-      }
-    }
-
-    return { version: null, variant }
-  } catch (error) {
-    logDebug('Failed to parse dump version', {
-      dumpPath,
-      error: error instanceof Error ? error.message : String(error),
-    })
-    return { version: null, variant: 'unknown' }
-  }
-}
-
-// Get the version of the mysql client
-export async function getMysqlClientVersion(): Promise<{
-  version: VersionInfo
-  variant: MySQLVariant
-}> {
-  const mysqlPath = await getMysqlClientPath()
-  if (!mysqlPath) {
-    throw new Error('mysql client not found')
-  }
-
-  const { stdout } = await execAsync(`"${mysqlPath}" --version`)
-  return parseToolVersion(stdout)
-}
-
-// =============================================================================
-// Compatibility Checking
-// =============================================================================
-
-/**
- * Check version compatibility
- *
- * MySQL/MariaDB compatibility matrix:
- * | Scenario | Result |
- * |----------|--------|
- * | MySQL 8 client + MySQL 8 dump | ✅ Works |
- * | MySQL 8 client + MySQL 5.7 dump | ✅ Works (backwards compatible) |
- * | MySQL 5.7 client + MySQL 8 dump | ⚠️ May have issues |
- * | MariaDB client + MySQL dump | ⚠️ Warning (mostly compatible) |
- * | MySQL client + MariaDB dump | ⚠️ Warning (mostly compatible) |
- */
-export function checkVersionCompatibility(
-  dumpInfo: DumpInfo,
-  toolVersion: VersionInfo,
-  toolVariant: MySQLVariant,
-): CompatibilityResult {
-  const result: CompatibilityResult = {
-    compatible: true,
-    dumpInfo,
-    toolVersion,
-    toolVariant,
-  }
-
-  // If we couldn't parse dump version, proceed with warning
-  if (!dumpInfo.version) {
-    result.warning = 'Could not detect dump version. Proceeding anyway.'
-    return result
-  }
-
-  // Check for variant mismatch (MySQL vs MariaDB)
-  if (
-    dumpInfo.variant !== 'unknown' &&
-    toolVariant !== 'unknown' &&
-    dumpInfo.variant !== toolVariant
-  ) {
-    result.warning =
-      `Dump was created with ${dumpInfo.variant === 'mariadb' ? 'MariaDB' : 'MySQL'}, ` +
-      `but restoring with ${toolVariant === 'mariadb' ? 'MariaDB' : 'MySQL'}. ` +
-      `This usually works, but some features may not be compatible.`
-    return result
-  }
-
-  // MySQL 8 introduced significant changes
-  // Restoring MySQL 8+ dump with MySQL 5.x client may fail
-  if (dumpInfo.version.major >= 8 && toolVersion.major < 8) {
-    result.compatible = false
-    result.error =
-      `Dump was created with MySQL ${dumpInfo.version.major}, ` +
-      `but your mysql client is version ${toolVersion.major}. ` +
-      `MySQL 8 dumps may contain syntax not supported by older clients.`
-    return result
-  }
-
-  // MariaDB 10.x to MySQL may have issues with specific features
-  if (
-    dumpInfo.variant === 'mariadb' &&
-    toolVariant === 'mysql' &&
-    dumpInfo.version.major >= 10
-  ) {
-    result.warning =
-      `Dump was created with MariaDB ${dumpInfo.version.full}. ` +
-      `Some MariaDB-specific features may not restore correctly to MySQL.`
-    return result
-  }
-
-  // Warn if dump is newer than tool (any variant)
-  if (dumpInfo.version.major > toolVersion.major) {
-    result.warning =
-      `Dump was created with version ${dumpInfo.version.full}, ` +
-      `but your client is version ${toolVersion.full}. ` +
-      `Some features may not restore correctly.`
-    return result
-  }
-
-  // Warn if dump is very old (5+ years)
-  if (
-    dumpInfo.version.major < 5 ||
-    (dumpInfo.version.major === 5 && dumpInfo.version.minor < 7)
-  ) {
-    result.warning =
-      `Dump was created with MySQL ${dumpInfo.version.full}. ` +
-      `This is a very old version; some data types may not import correctly.`
-    return result
-  }
-
-  return result
-}
-
-// =============================================================================
-// Main Validation Function
-// =============================================================================
-
-/**
- * Validate that a dump file can be restored with the available mysql client
- *
- * @throws SpinDBError if versions are incompatible
- */
-export async function validateRestoreCompatibility(options: {
-  dumpPath: string
-}): Promise<{
-  dumpInfo: DumpInfo
-  toolVersion: VersionInfo
-  toolVariant: MySQLVariant
-}> {
-  const { dumpPath } = options
-
-  // Get tool version
-  const { version: toolVersion, variant: toolVariant } =
-    await getMysqlClientVersion()
-  logDebug('mysql client version detected', {
-    version: toolVersion.full,
-    variant: toolVariant,
-  })
-
-  // Get dump version
-  const dumpInfo = await parseDumpVersion(dumpPath)
-  if (dumpInfo.version) {
-    logDebug('Dump version detected', {
-      version: dumpInfo.version.full,
-      variant: dumpInfo.variant,
-    })
-  } else {
-    logDebug('Could not detect dump version')
-  }
-
-  // Check compatibility
-  const result = checkVersionCompatibility(dumpInfo, toolVersion, toolVariant)
-
-  if (!result.compatible) {
-    throw new SpinDBError(
-      ErrorCodes.VERSION_MISMATCH,
-      result.error!,
-      'fatal',
-      'Install a newer version of MySQL client tools',
-      { dumpInfo, toolVersion, toolVariant },
-    )
-  }
-
-  if (result.warning) {
-    logWarning(result.warning)
-  }
-
-  return { dumpInfo, toolVersion, toolVariant }
-}

package/engines/postgresql/README.md

@@ -1,158 +0,0 @@
-# PostgreSQL Engine Implementation
-
-## Overview
-
-PostgreSQL is a traditional SQL database with full server-based lifecycle management. SpinDB downloads PostgreSQL binaries from hostdb and manages them locally.
-
-## 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 EDB binaries (uploaded to hostdb) |
-
-### Windows Binary Source
-
-PostgreSQL on Windows uses [EnterpriseDB (EDB)](https://www.enterprisedb.com/download-postgresql-binaries) binaries. These are downloaded from EDB's CDN and uploaded to hostdb for consistency. File IDs are maintained in `edb-binary-urls.ts`.
-
-## Binary Packaging
-
-### Archive Format
-- **Unix (macOS/Linux)**: `tar.gz`
-- **Windows**: `zip`
-
-### Archive Structure
-```
-postgresql/
-├── bin/
-│   ├── postgres         # Main server binary
-│   ├── pg_ctl           # Server control utility
-│   ├── initdb           # Database cluster initialization
-│   ├── psql             # Interactive terminal
-│   ├── pg_dump          # Backup utility
-│   ├── pg_restore       # Restore utility
-│   └── pg_basebackup    # Streaming backup
-└── lib/                 # Shared libraries
-```
-
-### Version Map Sync
-
-The `version-maps.ts` file must stay synchronized with hostdb's `releases.json`:
-
-```typescript
-export const POSTGRESQL_VERSION_MAP: Record<string, string> = {
-  '15': '15.x.x',
-  '16': '16.x.x',
-  '17': '17.x.x',
-  '18': '18.x.x',
-}
-```
-
-## Implementation Details
-
-### Binary Manager
-
-PostgreSQL uses `BaseServerBinaryManager` with a custom `verify()` override for version parsing. This is necessary because:
-
-1. PostgreSQL's version output differs between EDB and standard builds
-2. Version format: `postgres (PostgreSQL) X.Y` or `postgres (PostgreSQL) X.Y - Percona Server for PostgreSQL X.Y.Z`
-
-### Version Parsing Quirks
-
-- **Strip trailing .0**: Versions like `17.0` are normalized to match `17`
-- **Accept major.minor matches**: `18.1.0` matches requested version `18.1`
-- **EDB format handling**: EDB binaries may include additional branding in version output
-
-### Default Configuration
-
-- **Default Port**: 5432 (auto-increments on conflict)
-- **Default Database**: Name derived from container name
-- **PID File**: `postmaster.pid` in container directory
-
-### initdb and pg_ctl
-
-PostgreSQL uses a two-step initialization:
-1. `initdb` creates the data directory structure
-2. `pg_ctl start` launches the server in background mode
-
-### Connection String Format
-
-```
-postgresql://127.0.0.1:{port}/{database}
-```
-
-## Backup & Restore
-
-### Backup Formats
-
-| Format | Extension | Tool | Notes |
-|--------|-----------|------|-------|
-| sql | `.sql` | pg_dump | Plain text SQL, portable |
-| custom | `.dump` | pg_dump -Fc | Binary, supports parallel restore |
-
-### Restore Methods
-
-- **SQL format**: Restored via `psql -f`
-- **Custom format**: Restored via `pg_restore`
-
-## Integration Test Notes
-
-### Reserved Ports
-
-Integration tests use reserved ports to avoid conflicts:
-- **Test Ports**: 5454-5456 (NOT 5432)
-
-### Test Fixtures
-
-Located in `tests/fixtures/postgresql/seeds/`:
-- `sample-db.sql`: Contains 5 test_user records
-
-## Docker E2E Test Notes
-
-PostgreSQL is tested in Docker E2E with full lifecycle verification:
-- Container creation with `initdb`
-- Server start/stop
-- Database operations
-- Backup and restore
-- Multi-database support
-
-## Known Issues & Gotchas
-
-### 1. Windows Binary Differences
-
-Windows uses EDB binaries which have slightly different behavior:
-- File paths use Windows conventions internally
-- Some environment variables differ
-
-### 2. Port Conflicts
-
-When the default port is in use, SpinDB auto-increments (5432 -> 5433 -> etc.).
-
-### 3. Connection Termination
-
-Before dropping a database, active connections must be terminated. The engine uses:
-```sql
-SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'dbname';
-```
-
-Special handling for single quotes in shell commands on different platforms.
-
-### 4. Orphaned Container Support
-
-If PostgreSQL binaries are deleted while containers exist, starting those containers prompts the user to re-download the binaries.
-
-## CI/CD Notes
-
-### GitHub Actions Cache Step
-
-PostgreSQL binaries are cached in CI to speed up test runs:
-```yaml
-- name: Cache PostgreSQL binaries
-  uses: actions/cache@v4
-  with:
-    path: ~/.spindb/bin/postgresql-*
-    key: postgresql-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('engines/postgresql/version-maps.ts') }}
-```

package/engines/postgresql/backup.ts

@@ -1,151 +0,0 @@
-/**
- * PostgreSQL Backup
- *
- * Creates database backups in SQL or custom (.dump) format using pg_dump.
- */
-
-import { spawn, type SpawnOptions } from 'child_process'
-import { stat } from 'fs/promises'
-import { existsSync } from 'fs'
-import { join } from 'path'
-import { configManager } from '../../core/config-manager'
-import {
-  getWindowsSpawnOptions,
-  platformService,
-} from '../../core/platform-service'
-import { defaults } from '../../config/defaults'
-import { paths } from '../../config/paths'
-import { normalizeVersion } from './version-maps'
-import type { ContainerConfig, BackupOptions, BackupResult } from '../../types'
-
-/**
- * Get pg_dump path for a specific PostgreSQL version.
- *
- * Prioritizes SpinDB-managed binaries that match the container's version,
- * falling back to system pg_dump only if no matching version is found.
- *
- * @param containerVersion - The container's PostgreSQL version (e.g., "18" or "18.1.0")
- * @returns Path to the version-matched pg_dump binary
- */
-async function getPgDumpPath(containerVersion: string): Promise<string> {
-  // Normalize to full version (e.g., "18" -> "18.1.0")
-  const fullVersion = normalizeVersion(containerVersion)
-
-  // Get platform info for building the binary path
-  const platformInfo = platformService.getPlatformInfo()
-  const ext = platformInfo.platform === 'win32' ? '.exe' : ''
-
-  // Try to find SpinDB-managed pg_dump for the matching version
-  const versionedBinPath = paths.getBinaryPath({
-    engine: 'postgresql',
-    version: fullVersion,
-    platform: platformInfo.platform,
-    arch: platformInfo.arch,
-  })
-
-  const versionedPgDump = join(versionedBinPath, 'bin', `pg_dump${ext}`)
-
-  if (existsSync(versionedPgDump)) {
-    return versionedPgDump
-  }
-
-  // Try to find any installed version for this major version
-  const majorVersion = containerVersion.split('.')[0]
-  const installed = paths.findInstalledBinaryForMajor(
-    'postgresql',
-    majorVersion,
-    platformInfo.platform,
-    platformInfo.arch,
-  )
-
-  if (installed) {
-    const installedPgDump = join(installed.path, 'bin', `pg_dump${ext}`)
-    if (existsSync(installedPgDump)) {
-      return installedPgDump
-    }
-  }
-
-  // Fall back to globally registered pg_dump (system binary)
-  const systemPgDump = await configManager.getBinaryPath('pg_dump')
-  if (systemPgDump) {
-    return systemPgDump
-  }
-
-  throw new Error(
-    `pg_dump not found for PostgreSQL ${containerVersion}. ` +
-      `Either download PostgreSQL binaries with 'spindb create --engine postgresql --version ${majorVersion}' ` +
-      'or install PostgreSQL client tools:\n' +
-      '  macOS: brew install libpq && brew link --force libpq\n' +
-      '  Ubuntu/Debian: apt install postgresql-client\n\n' +
-      'Or configure manually: spindb config set pg_dump /path/to/pg_dump',
-  )
-}
-
-/**
- * Create a backup of a PostgreSQL database
- *
- * CLI equivalent:
- * - SQL format: pg_dump -Fp -h 127.0.0.1 -p {port} -U postgres -d {database} -f {outputPath}
- * - Dump format: pg_dump -Fc -h 127.0.0.1 -p {port} -U postgres -d {database} -f {outputPath}
- */
-export async function createBackup(
-  container: ContainerConfig,
-  outputPath: string,
-  options: BackupOptions,
-): Promise<BackupResult> {
-  const { port, version } = container
-  const { database, format } = options
-
-  const pgDumpPath = await getPgDumpPath(version)
-
-  // -Fp = plain SQL format, -Fc = custom format
-  const formatFlag = format === 'sql' ? '-Fp' : '-Fc'
-
-  return new Promise((resolve, reject) => {
-    const args = [
-      '-h',
-      '127.0.0.1',
-      '-p',
-      String(port),
-      '-U',
-      defaults.superuser,
-      '-d',
-      database,
-      formatFlag,
-      '-f',
-      outputPath,
-    ]
-
-    const spawnOptions: SpawnOptions = {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      ...getWindowsSpawnOptions(),
-    }
-
-    const proc = spawn(pgDumpPath, args, spawnOptions)
-
-    let stderr = ''
-
-    proc.stderr?.on('data', (data: Buffer) => {
-      stderr += data.toString()
-    })
-
-    proc.on('error', (err: NodeJS.ErrnoException) => {
-      reject(err)
-    })
-
-    proc.on('close', async (code) => {
-      if (code === 0) {
-        // Get file size
-        const stats = await stat(outputPath)
-        resolve({
-          path: outputPath,
-          format: format === 'sql' ? 'sql' : 'custom',
-          size: stats.size,
-        })
-      } else {
-        const errorMessage = stderr || `pg_dump exited with code ${code}`
-        reject(new Error(errorMessage))
-      }
-    })
-  })
-}