spindb 0.5.2 → 0.5.3

package/{core/postgres-binary-manager.ts → engines/postgresql/binary-manager.ts}

@@ -1,15 +1,17 @@
 import { exec } from 'child_process'
 import { promisify } from 'util'
 import chalk from 'chalk'
-import { createSpinner } from '../cli/ui/spinner'
-import { warning, error as themeError, success } from '../cli/ui/theme'
+import { createSpinner } from '../../cli/ui/spinner'
+import { warning, error as themeError, success } from '../../cli/ui/theme'
 import {
   detectPackageManager as detectPM,
   installEngineDependencies,
   getManualInstallInstructions,
   getCurrentPlatform,
-} from './dependency-manager'
-import { getEngineDependencies } from '../config/os-dependencies'
+} from '../../core/dependency-manager'
+import { getEngineDependencies } from '../../config/os-dependencies'
+import { getPostgresHomebrewPackage } from '../../config/engine-defaults'
+import { logDebug } from '../../core/error-handler'
 
 const execAsync = promisify(exec)
 
@@ -34,16 +36,17 @@ export type PackageManager = {
  * Detect which package manager is available on the system
  */
 export async function detectPackageManager(): Promise<PackageManager | null> {
+  const pgPackage = getPostgresHomebrewPackage()
   const managers: PackageManager[] = [
     {
       name: 'brew',
       checkCommand: 'brew --version',
       installCommand: () =>
-        'brew install postgresql@17 && brew link --overwrite postgresql@17',
+        `brew install ${pgPackage} && brew link --overwrite ${pgPackage}`,
       updateCommand: () =>
-        'brew link --overwrite postgresql@17 || brew install postgresql@17 && brew link --overwrite postgresql@17',
+        `brew link --overwrite ${pgPackage} || brew install ${pgPackage} && brew link --overwrite ${pgPackage}`,
       versionCheckCommand: () =>
-        'brew info postgresql@17 | grep "postgresql@17:" | head -1',
+        `brew info ${pgPackage} | grep "${pgPackage}:" | head -1`,
     },
     {
       name: 'apt',
@@ -74,8 +77,12 @@ export async function detectPackageManager(): Promise<PackageManager | null> {
     try {
       await execAsync(manager.checkCommand)
       return manager
-    } catch {
-      // Manager not available
+    } catch (error) {
+      // Manager not available - log for debugging
+      logDebug(`Package manager ${manager.name} not available`, {
+        command: manager.checkCommand,
+        error: error instanceof Error ? error.message : String(error),
+      })
     }
   }
 
@@ -92,7 +99,10 @@ export async function getPostgresVersion(
     const { stdout } = await execAsync(`${binary} --version`)
     const match = stdout.match(/(\d+\.\d+)/)
     return match ? match[1] : null
-  } catch {
+  } catch (error) {
+    logDebug(`Failed to get version for ${binary}`, {
+      error: error instanceof Error ? error.message : String(error),
+    })
     return null
   }
 }
@@ -105,7 +115,10 @@ export async function findBinaryPath(binary: string): Promise<string | null> {
     const command = process.platform === 'win32' ? 'where' : 'which'
     const { stdout } = await execAsync(`${command} ${binary}`)
     return stdout.trim().split('\n')[0] || null
-  } catch {
+  } catch (error) {
+    logDebug(`Binary ${binary} not found in PATH`, {
+      error: error instanceof Error ? error.message : String(error),
+    })
     return null
   }
 }
@@ -128,7 +141,10 @@ export async function findBinaryPathFresh(
       `${shell} -c 'source ~/.${shell.endsWith('zsh') ? 'zshrc' : 'bashrc'} && which ${binary}'`,
     )
     return stdout.trim().split('\n')[0] || null
-  } catch {
+  } catch (error) {
+    logDebug(`Binary ${binary} not found after PATH refresh`, {
+      error: error instanceof Error ? error.message : String(error),
+    })
     return null
   }
 }
@@ -185,14 +201,20 @@ export async function getDumpRequiredVersion(
             return '15.0' // Minimum version for recent dumps
           }
         }
-      } catch {
+      } catch (error) {
         // If hexdump fails, fall back to checking error patterns
+        logDebug(`hexdump failed for ${dumpPath}`, {
+          error: error instanceof Error ? error.message : String(error),
+        })
       }
     }
 
     // Fallback: if we can't determine, assume it needs a recent version
     return '15.0'
-  } catch {
+  } catch (error) {
+    logDebug(`Failed to determine dump version for ${dumpPath}`, {
+      error: error instanceof Error ? error.message : String(error),
+    })
     return null
   }
 }
@@ -309,12 +331,19 @@ export async function installPostgresBinaries(): Promise<boolean> {
   spinner.succeed(`Found package manager: ${packageManager.name}`)
 
   // Don't use a spinner during installation - it blocks TTY access for sudo password prompts
-  console.log(chalk.cyan(`  Installing PostgreSQL client tools with ${packageManager.name}...`))
+  console.log(
+    chalk.cyan(
+      `  Installing PostgreSQL client tools with ${packageManager.name}...`,
+    ),
+  )
   console.log(chalk.gray('  You may be prompted for your password.'))
   console.log()
 
   try {
-    const results = await installEngineDependencies('postgresql', packageManager)
+    const results = await installEngineDependencies(
+      'postgresql',
+      packageManager,
+    )
     const allSuccess = results.every((r) => r.success)
 
     if (allSuccess) {
@@ -356,14 +385,20 @@ export async function updatePostgresClientTools(): Promise<boolean> {
 
   spinner.succeed(`Found package manager: ${packageManager.name}`)
 
+  const pgPackage = getPostgresHomebrewPackage()
+  const latestMajor = pgPackage.split('@')[1] // e.g., '17' from 'postgresql@17'
+
   try {
     if (packageManager.name === 'brew') {
       // Handle brew conflicts and dependency issues
+      // Unlink all older PostgreSQL versions before linking the latest
+      const olderVersions = ['14', '15', '16'].filter((v) => v !== latestMajor)
+      const unlinkCommands = olderVersions.map(
+        (v) => `brew unlink postgresql@${v} 2>/dev/null || true`,
+      )
       const commands = [
-        'brew unlink postgresql@14 2>/dev/null || true', // Unlink old version if exists
-        'brew unlink postgresql@15 2>/dev/null || true', // Unlink other old versions
-        'brew unlink postgresql@16 2>/dev/null || true',
-        'brew link --overwrite postgresql@17', // Link postgresql@17 with overwrite
+        ...unlinkCommands,
+        `brew link --overwrite ${pgPackage}`, // Link latest version with overwrite
         'brew upgrade icu4c 2>/dev/null || true', // Fix ICU dependency issues
       ]
 
@@ -372,7 +407,11 @@ export async function updatePostgresClientTools(): Promise<boolean> {
       }
 
       spinner.succeed('PostgreSQL client tools updated')
-      console.log(success('Client tools successfully linked to PostgreSQL 17'))
+      console.log(
+        success(
+          `Client tools successfully linked to PostgreSQL ${latestMajor}`,
+        ),
+      )
       console.log(chalk.gray('ICU dependencies have been updated'))
       return true
     } else {
@@ -388,13 +427,14 @@ export async function updatePostgresClientTools(): Promise<boolean> {
     console.log(warning('Please update manually:'))
 
     if (packageManager.name === 'brew') {
+      const olderVersions = ['14', '15', '16'].filter((v) => v !== latestMajor)
       console.log(chalk.yellow('  macOS:'))
       console.log(
         chalk.yellow(
-          '    brew unlink postgresql@14 postgresql@15 postgresql@16',
+          `    brew unlink ${olderVersions.map((v) => `postgresql@${v}`).join(' ')}`,
         ),
       )
-      console.log(chalk.yellow('    brew link --overwrite postgresql@17'))
+      console.log(chalk.yellow(`    brew link --overwrite ${pgPackage}`))
       console.log(
         chalk.yellow('    brew upgrade icu4c  # Fix ICU dependency issues'),
       )

package/engines/postgresql/binary-urls.ts

@@ -1,4 +1,4 @@
-import { platform, arch } from 'os'
+import { platformService } from '../../core/platform-service'
 import { defaults } from '../../config/defaults'
 
 /**
@@ -33,9 +33,10 @@ export async function fetchAvailableVersions(): Promise<
     return cachedVersions
   }
 
-  const zonkyPlatform = getZonkyPlatform(platform(), arch())
+  const zonkyPlatform = platformService.getZonkyPlatform()
   if (!zonkyPlatform) {
-    throw new Error(`Unsupported platform: ${platform()}-${arch()}`)
+    const { platform, arch } = platformService.getPlatformInfo()
+    throw new Error(`Unsupported platform: ${platform}-${arch}`)
   }
 
   const url = `https://repo1.maven.org/maven2/io/zonky/test/postgres/embedded-postgres-binaries-${zonkyPlatform}/`
@@ -123,6 +124,7 @@ export const VERSION_MAP = FALLBACK_VERSION_MAP
 
 /**
  * Get the zonky.io platform identifier
+ * @deprecated Use platformService.getZonkyPlatform() instead
  */
 export function getZonkyPlatform(
   platform: string,

package/engines/postgresql/index.ts

@@ -1,4 +1,3 @@
-import { platform, arch } from 'os'
 import { join } from 'path'
 import { spawn, exec } from 'child_process'
 import { promisify } from 'util'
@@ -6,6 +5,7 @@ import { BaseEngine } from '../base-engine'
 import { binaryManager } from '../../core/binary-manager'
 import { processManager } from '../../core/process-manager'
 import { configManager } from '../../core/config-manager'
+import { platformService } from '../../core/platform-service'
 import { paths } from '../../config/paths'
 import { defaults } from '../../config/defaults'
 import {
@@ -43,9 +43,10 @@ export class PostgreSQLEngine extends BaseEngine {
    * Get current platform info
    */
   getPlatformInfo(): { platform: string; arch: string } {
+    const info = platformService.getPlatformInfo()
     return {
-      platform: platform(),
-      arch: arch(),
+      platform: info.platform,
+      arch: info.arch,
     }
   }
 

package/engines/postgresql/restore.ts

@@ -2,23 +2,37 @@ import { readFile } from 'fs/promises'
 import { exec } from 'child_process'
 import { promisify } from 'util'
 import { configManager } from '../../core/config-manager'
-import { findBinaryPathFresh } from '../../core/postgres-binary-manager'
+import { findBinaryPathFresh } from './binary-manager'
+import { validateRestoreCompatibility } from './version-validator'
+import { SpinDBError, ErrorCodes } from '../../core/error-handler'
 import type { BackupFormat, RestoreResult } from '../../types'
 
 const execAsync = promisify(exec)
 
 /**
  * Detect the format of a PostgreSQL backup file
+ *
+ * Also detects MySQL/MariaDB dumps to provide helpful error messages.
  */
 export async function detectBackupFormat(
   filePath: string,
 ): Promise<BackupFormat> {
-  // Read the first few bytes to detect format
+  // Read the first 128 bytes to detect format
   const file = await readFile(filePath)
-  const buffer = Buffer.alloc(16)
+  const buffer = Buffer.alloc(128)
 
   // Copy first bytes
-  file.copy(buffer, 0, 0, Math.min(16, file.length))
+  file.copy(buffer, 0, 0, Math.min(128, file.length))
+  const header = buffer.toString('utf8')
+
+  // Check for MySQL/MariaDB dump markers (before PostgreSQL checks)
+  if (header.includes('-- MySQL dump') || header.includes('-- MariaDB dump')) {
+    return {
+      format: 'mysql_sql',
+      description: 'MySQL/MariaDB SQL dump (incompatible with PostgreSQL)',
+      restoreCommand: 'mysql',
+    }
+  }
 
   // Check for PostgreSQL custom format magic number
   // Custom format starts with "PGDMP"
@@ -78,6 +92,25 @@ export async function detectBackupFormat(
   }
 }
 
+/**
+ * Check if the backup file is from the wrong engine and throw helpful error
+ */
+export function assertCompatibleFormat(format: BackupFormat): void {
+  if (format.format === 'mysql_sql') {
+    throw new SpinDBError(
+      ErrorCodes.WRONG_ENGINE_DUMP,
+      `This appears to be a MySQL/MariaDB dump file, but you're trying to restore it to PostgreSQL.`,
+      'fatal',
+      `Create a MySQL container instead:\n  spindb create mydb --engine mysql --from <dump-file>`,
+      {
+        detectedFormat: format.format,
+        expectedEngine: 'postgresql',
+        detectedEngine: 'mysql',
+      },
+    )
+  }
+}
+
 export type RestoreOptions = {
   port: number
   database: string
@@ -136,7 +169,23 @@ export async function restoreBackup(
 ): Promise<RestoreResult> {
   const { port, database, user = 'postgres', format, pgRestorePath } = options
 
-  const detectedFormat = format || (await detectBackupFormat(backupPath)).format
+  // Detect format and check for wrong engine
+  const detectedBackupFormat = await detectBackupFormat(backupPath)
+  assertCompatibleFormat(detectedBackupFormat)
+
+  const detectedFormat = format || detectedBackupFormat.format
+
+  // For pg_restore formats, validate version compatibility
+  if (detectedFormat !== 'sql') {
+    const restorePath = pgRestorePath || (await getPgRestorePath())
+
+    // This will throw SpinDBError if versions are incompatible
+    await validateRestoreCompatibility({
+      dumpPath: backupPath,
+      format: detectedFormat,
+      pgRestorePath: restorePath,
+    })
+  }
 
   if (detectedFormat === 'sql') {
     const psqlPath = await getPsqlPath()

package/engines/postgresql/version-validator.ts

@@ -0,0 +1,262 @@
+/**
+ * PostgreSQL Version Validator
+ *
+ * Validates compatibility between pg_restore tool version and dump file version.
+ * PostgreSQL is backwards compatible - we only fail when dump_version > tool_version.
+ */
+
+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'
+
+const execAsync = promisify(exec)
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type VersionInfo = {
+  major: number
+  minor: number
+  patch: number
+  full: string
+}
+
+export type CompatibilityResult = {
+  compatible: boolean
+  dumpVersion: VersionInfo | null
+  toolVersion: VersionInfo
+  warning?: string
+  error?: string
+}
+
+// =============================================================================
+// Version Parsing
+// =============================================================================
+
+/**
+ * Parse version from pg_dump/pg_restore --version output
+ * Examples:
+ *   "pg_restore (PostgreSQL) 16.1"
+ *   "pg_restore (PostgreSQL) 14.9 (Homebrew)"
+ *   "pg_dump (PostgreSQL) 17.0"
+ */
+export function parseToolVersion(output: string): VersionInfo {
+  const match = output.match(/(\d+)\.(\d+)(?:\.(\d+))?/)
+  if (!match) {
+    throw new Error(`Cannot parse version from: ${output}`)
+  }
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3] || '0', 10),
+    full: match[0],
+  }
+}
+
+/**
+ * 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
+ *
+ * Plain SQL format: "-- Dumped from database version 16.1"
+ * Archive format: Uses `pg_restore -l` to read TOC header
+ */
+export async function parseDumpVersion(
+  dumpPath: string,
+  format: string,
+  pgRestorePath?: string,
+): Promise<VersionInfo | null> {
+  try {
+    if (format === 'custom' || format === 'directory') {
+      // Use pg_restore -l to get archive info
+      const restorePath = pgRestorePath || 'pg_restore'
+      const { stdout } = await execAsync(
+        `"${restorePath}" -l "${dumpPath}" 2>&1 | head -20`,
+      )
+      // Look for: "; Dumped from database version 16.1"
+      const match = stdout.match(
+        /Dumped from database version (\d+)\.(\d+)(?:\.(\d+))?/,
+      )
+      if (match) {
+        return {
+          major: parseInt(match[1], 10),
+          minor: parseInt(match[2], 10),
+          patch: parseInt(match[3] || '0', 10),
+          full: `${match[1]}.${match[2]}${match[3] ? `.${match[3]}` : ''}`,
+        }
+      }
+    } else {
+      // Plain SQL format - read first 50 lines
+      const header = await readFirstLines(dumpPath, 50)
+      const match = header.match(
+        /Dumped from database version (\d+)\.(\d+)(?:\.(\d+))?/,
+      )
+      if (match) {
+        return {
+          major: parseInt(match[1], 10),
+          minor: parseInt(match[2], 10),
+          patch: parseInt(match[3] || '0', 10),
+          full: `${match[1]}.${match[2]}${match[3] ? `.${match[3]}` : ''}`,
+        }
+      }
+    }
+  } catch (err) {
+    logDebug('Failed to parse dump version', {
+      dumpPath,
+      format,
+      error: err instanceof Error ? err.message : String(err),
+    })
+  }
+
+  return null // Version not found in dump
+}
+
+/**
+ * Get the version of pg_restore
+ */
+export async function getPgRestoreVersion(
+  pgRestorePath: string,
+): Promise<VersionInfo> {
+  const { stdout } = await execAsync(`"${pgRestorePath}" --version`)
+  return parseToolVersion(stdout)
+}
+
+// =============================================================================
+// Compatibility Checking
+// =============================================================================
+
+/**
+ * Check version compatibility - ONLY fails when dump is NEWER than tool
+ *
+ * | Scenario | Result |
+ * |----------|--------|
+ * | pg_restore v16 + dump from v14 | ✅ Works (backwards compatible) |
+ * | pg_restore v16 + dump from v16 | ✅ Works (same version) |
+ * | pg_restore v14 + dump from v16 | ❌ Fails (dump newer than tool) |
+ * | pg_restore v16 + dump from v10 | ⚠️ Works with warning (very old) |
+ */
+export function checkVersionCompatibility(
+  dumpVersion: VersionInfo | null,
+  toolVersion: VersionInfo,
+): CompatibilityResult {
+  // If we couldn't parse dump version, proceed with warning
+  if (!dumpVersion) {
+    return {
+      compatible: true,
+      dumpVersion: null,
+      toolVersion,
+      warning: 'Could not detect dump version. Proceeding anyway.',
+    }
+  }
+
+  // FAIL: Dump is newer than tool (e.g., pg_restore 14 + dump from 16)
+  if (dumpVersion.major > toolVersion.major) {
+    return {
+      compatible: false,
+      dumpVersion,
+      toolVersion,
+      error:
+        `Backup was created with PostgreSQL ${dumpVersion.major}, ` +
+        `but your pg_restore is version ${toolVersion.major}. ` +
+        `Install PostgreSQL ${dumpVersion.major} client tools to restore this backup.`,
+    }
+  }
+
+  // WARN: Dump is very old (3+ major versions behind)
+  if (dumpVersion.major < toolVersion.major - 2) {
+    return {
+      compatible: true,
+      dumpVersion,
+      toolVersion,
+      warning:
+        `Backup was created with PostgreSQL ${dumpVersion.major}. ` +
+        `Some features may not restore correctly.`,
+    }
+  }
+
+  // OK: Same version or dump is older (backwards compatible)
+  return { compatible: true, dumpVersion, toolVersion }
+}
+
+// =============================================================================
+// Main Validation Function
+// =============================================================================
+
+/**
+ * Validate that a dump file can be restored with the available pg_restore
+ *
+ * @throws SpinDBError if versions are incompatible
+ */
+export async function validateRestoreCompatibility(options: {
+  dumpPath: string
+  format: string
+  pgRestorePath: string
+}): Promise<{ dumpVersion: VersionInfo | null; toolVersion: VersionInfo }> {
+  const { dumpPath, format, pgRestorePath } = options
+
+  // Get tool version
+  const toolVersion = await getPgRestoreVersion(pgRestorePath)
+  logDebug('pg_restore version detected', { version: toolVersion.full })
+
+  // Get dump version
+  const dumpVersion = await parseDumpVersion(dumpPath, format, pgRestorePath)
+  if (dumpVersion) {
+    logDebug('Dump version detected', { version: dumpVersion.full })
+  } else {
+    logDebug('Could not detect dump version')
+  }
+
+  // Check compatibility
+  const result = checkVersionCompatibility(dumpVersion, toolVersion)
+
+  if (!result.compatible) {
+    throw new SpinDBError(
+      ErrorCodes.VERSION_MISMATCH,
+      result.error!,
+      'fatal',
+      `Install PostgreSQL ${dumpVersion!.major} client tools: brew install postgresql@${dumpVersion!.major}`,
+      { dumpVersion, toolVersion },
+    )
+  }
+
+  if (result.warning) {
+    logWarning(result.warning)
+  }
+
+  return { dumpVersion, toolVersion }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spindb",
-  "version": "0.5.2",
-  "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL.",
+  "version": "0.5.3",
+  "description": "Spin up local database containers without Docker. A DBngin-like CLI for PostgreSQL and MySQL.",
   "type": "module",
   "bin": {
     "spindb": "./bin/cli.js"
@@ -12,12 +12,16 @@
     "test": "pnpm test:pg && pnpm test:mysql",
     "test:pg": "node --import tsx --test tests/integration/postgresql.test.ts",
     "test:mysql": "node --import tsx --test tests/integration/mysql.test.ts",
+    "test:unit": "node --import tsx --test tests/unit/*.test.ts",
+    "test:integration": "pnpm test:pg && pnpm test:mysql",
+    "test:all": "pnpm test:unit && pnpm test:integration",
     "format": "prettier --write .",
     "lint": "tsc --noEmit && eslint ."
   },
   "keywords": [
     "postgres",
     "postgresql",
+    "mysql",
     "database",
     "local",
     "development",