spindb 0.1.0

package/src/engines/base-engine.ts

@@ -0,0 +1,103 @@
+import type {
+  ContainerConfig,
+  ProgressCallback,
+  BackupFormat,
+  RestoreResult,
+  StatusResult,
+} from '@/types'
+
+/**
+ * Base class for database engines
+ * All engines (PostgreSQL, MySQL, SQLite) should extend this class
+ */
+export abstract class BaseEngine {
+  abstract name: string
+  abstract displayName: string
+  abstract defaultPort: number
+  abstract supportedVersions: string[]
+
+  /**
+   * Get the download URL for binaries
+   */
+  abstract getBinaryUrl(version: string, platform: string, arch: string): string
+
+  /**
+   * Verify that the binaries are working correctly
+   */
+  abstract verifyBinary(binPath: string): Promise<boolean>
+
+  /**
+   * Initialize a new data directory
+   */
+  abstract initDataDir(
+    containerName: string,
+    version: string,
+    options?: Record<string, unknown>,
+  ): Promise<string>
+
+  /**
+   * Start the database server
+   */
+  abstract start(
+    container: ContainerConfig,
+    onProgress?: ProgressCallback,
+  ): Promise<{ port: number; connectionString: string }>
+
+  /**
+   * Stop the database server
+   */
+  abstract stop(container: ContainerConfig): Promise<void>
+
+  /**
+   * Get the status of the database server
+   */
+  abstract status(container: ContainerConfig): Promise<StatusResult>
+
+  /**
+   * Detect the format of a backup file
+   */
+  abstract detectBackupFormat(filePath: string): Promise<BackupFormat>
+
+  /**
+   * Restore a backup to the database
+   */
+  abstract restore(
+    container: ContainerConfig,
+    backupPath: string,
+    options?: Record<string, unknown>,
+  ): Promise<RestoreResult>
+
+  /**
+   * Get the connection string for a container
+   */
+  abstract getConnectionString(
+    container: ContainerConfig,
+    database?: string,
+  ): string
+
+  /**
+   * Open an interactive shell/CLI connection
+   */
+  abstract connect(container: ContainerConfig, database?: string): Promise<void>
+
+  /**
+   * Create a new database within the container
+   */
+  abstract createDatabase(
+    container: ContainerConfig,
+    database: string,
+  ): Promise<void>
+
+  /**
+   * Check if binaries are installed
+   */
+  abstract isBinaryInstalled(version: string): Promise<boolean>
+
+  /**
+   * Ensure binaries are available, downloading if necessary
+   */
+  abstract ensureBinaries(
+    version: string,
+    onProgress?: ProgressCallback,
+  ): Promise<string>
+}

package/src/engines/index.ts

@@ -0,0 +1,46 @@
+import { postgresqlEngine } from '@/engines/postgresql'
+import type { BaseEngine } from '@/engines/base-engine'
+import type { EngineInfo } from '@/types'
+
+/**
+ * Registry of available database engines
+ */
+export const engines: Record<string, BaseEngine> = {
+  postgresql: postgresqlEngine,
+  postgres: postgresqlEngine, // Alias
+  pg: postgresqlEngine, // Alias
+}
+
+/**
+ * Get an engine by name
+ */
+export function getEngine(name: string): BaseEngine {
+  const engine = engines[name.toLowerCase()]
+  if (!engine) {
+    const available = [...new Set(Object.values(engines))].map((e) => e.name)
+    throw new Error(
+      `Unknown engine "${name}". Available: ${available.join(', ')}`,
+    )
+  }
+  return engine
+}
+
+/**
+ * List all available engines
+ */
+export function listEngines(): EngineInfo[] {
+  // Return unique engines (filter out aliases)
+  const seen = new Set<BaseEngine>()
+  return Object.entries(engines)
+    .filter(([, engine]) => {
+      if (seen.has(engine)) return false
+      seen.add(engine)
+      return true
+    })
+    .map(([, engine]) => ({
+      name: engine.name,
+      displayName: engine.displayName,
+      defaultPort: engine.defaultPort,
+      supportedVersions: engine.supportedVersions,
+    }))
+}

package/src/engines/postgresql/binary-urls.ts

@@ -0,0 +1,52 @@
+import { defaults } from '@/config/defaults'
+
+/**
+ * Map major versions to latest stable patch versions
+ */
+export const VERSION_MAP: Record<string, string> = {
+  '14': '14.15.0',
+  '15': '15.10.0',
+  '16': '16.6.0',
+  '17': '17.2.0',
+}
+
+/**
+ * Get the zonky.io platform identifier
+ */
+export function getZonkyPlatform(
+  platform: string,
+  arch: string,
+): string | undefined {
+  const key = `${platform}-${arch}`
+  return defaults.platformMappings[key]
+}
+
+/**
+ * Build the download URL for PostgreSQL binaries from zonky.io
+ */
+export function getBinaryUrl(
+  version: string,
+  platform: string,
+  arch: string,
+): string {
+  const zonkyPlatform = getZonkyPlatform(platform, arch)
+  if (!zonkyPlatform) {
+    throw new Error(`Unsupported platform: ${platform}-${arch}`)
+  }
+
+  const fullVersion = VERSION_MAP[version]
+  if (!fullVersion) {
+    throw new Error(
+      `Unsupported PostgreSQL version: ${version}. Supported: ${Object.keys(VERSION_MAP).join(', ')}`,
+    )
+  }
+
+  return `https://repo1.maven.org/maven2/io/zonky/test/postgres/embedded-postgres-binaries-${zonkyPlatform}/${fullVersion}/embedded-postgres-binaries-${zonkyPlatform}-${fullVersion}.jar`
+}
+
+/**
+ * Get the full version string for a major version
+ */
+export function getFullVersion(majorVersion: string): string | null {
+  return VERSION_MAP[majorVersion] || null
+}

package/src/engines/postgresql/index.ts

@@ -0,0 +1,298 @@
+import { platform, arch } from 'os'
+import { join } from 'path'
+import { spawn, exec } from 'child_process'
+import { promisify } from 'util'
+import { BaseEngine } from '@/engines/base-engine'
+import { binaryManager } from '@/core/binary-manager'
+import { processManager } from '@/core/process-manager'
+import { configManager } from '@/core/config-manager'
+import { paths } from '@/config/paths'
+import { defaults } from '@/config/defaults'
+import { getBinaryUrl, VERSION_MAP } from './binary-urls'
+import { detectBackupFormat, restoreBackup } from './restore'
+import type {
+  ContainerConfig,
+  ProgressCallback,
+  BackupFormat,
+  RestoreResult,
+  StatusResult,
+} from '@/types'
+
+const execAsync = promisify(exec)
+
+export class PostgreSQLEngine extends BaseEngine {
+  name = 'postgresql'
+  displayName = 'PostgreSQL'
+  defaultPort = 5432
+  supportedVersions = Object.keys(VERSION_MAP)
+
+  /**
+   * Get current platform info
+   */
+  getPlatformInfo(): { platform: string; arch: string } {
+    return {
+      platform: platform(),
+      arch: arch(),
+    }
+  }
+
+  /**
+   * Get binary path for current platform
+   */
+  getBinaryPath(version: string): string {
+    const { platform: p, arch: a } = this.getPlatformInfo()
+    return paths.getBinaryPath('postgresql', version, p, a)
+  }
+
+  /**
+   * Get binary download URL
+   */
+  getBinaryUrl(version: string, plat: string, arc: string): string {
+    return getBinaryUrl(version, plat, arc)
+  }
+
+  /**
+   * Verify binary installation
+   */
+  async verifyBinary(binPath: string): Promise<boolean> {
+    const { platform: p, arch: a } = this.getPlatformInfo()
+    // Extract version from path
+    const parts = binPath.split('-')
+    const version = parts[1]
+    return binaryManager.verify(version, p, a)
+  }
+
+  /**
+   * Ensure PostgreSQL binaries are available
+   */
+  async ensureBinaries(
+    version: string,
+    onProgress?: ProgressCallback,
+  ): Promise<string> {
+    const { platform: p, arch: a } = this.getPlatformInfo()
+    return binaryManager.ensureInstalled(version, p, a, onProgress)
+  }
+
+  /**
+   * Check if binaries are installed
+   */
+  async isBinaryInstalled(version: string): Promise<boolean> {
+    const { platform: p, arch: a } = this.getPlatformInfo()
+    return binaryManager.isInstalled(version, p, a)
+  }
+
+  /**
+   * Initialize a new PostgreSQL data directory
+   */
+  async initDataDir(
+    containerName: string,
+    version: string,
+    options: Record<string, unknown> = {},
+  ): Promise<string> {
+    const binPath = this.getBinaryPath(version)
+    const initdbPath = join(binPath, 'bin', 'initdb')
+    const dataDir = paths.getContainerDataPath(containerName)
+
+    await processManager.initdb(initdbPath, dataDir, {
+      superuser: (options.superuser as string) || defaults.superuser,
+    })
+
+    return dataDir
+  }
+
+  /**
+   * Start PostgreSQL server
+   */
+  async start(
+    container: ContainerConfig,
+    onProgress?: ProgressCallback,
+  ): Promise<{ port: number; connectionString: string }> {
+    const { name, version, port } = container
+    const binPath = this.getBinaryPath(version)
+    const pgCtlPath = join(binPath, 'bin', 'pg_ctl')
+    const dataDir = paths.getContainerDataPath(name)
+    const logFile = paths.getContainerLogPath(name)
+
+    onProgress?.({ stage: 'starting', message: 'Starting PostgreSQL...' })
+
+    await processManager.start(pgCtlPath, dataDir, {
+      port,
+      logFile,
+    })
+
+    return {
+      port,
+      connectionString: this.getConnectionString(container),
+    }
+  }
+
+  /**
+   * Stop PostgreSQL server
+   */
+  async stop(container: ContainerConfig): Promise<void> {
+    const { name, version } = container
+    const binPath = this.getBinaryPath(version)
+    const pgCtlPath = join(binPath, 'bin', 'pg_ctl')
+    const dataDir = paths.getContainerDataPath(name)
+
+    await processManager.stop(pgCtlPath, dataDir)
+  }
+
+  /**
+   * Get PostgreSQL server status
+   */
+  async status(container: ContainerConfig): Promise<StatusResult> {
+    const { name, version } = container
+    const binPath = this.getBinaryPath(version)
+    const pgCtlPath = join(binPath, 'bin', 'pg_ctl')
+    const dataDir = paths.getContainerDataPath(name)
+
+    return processManager.status(pgCtlPath, dataDir)
+  }
+
+  /**
+   * Detect backup format
+   */
+  async detectBackupFormat(filePath: string): Promise<BackupFormat> {
+    return detectBackupFormat(filePath)
+  }
+
+  /**
+   * Restore a backup
+   */
+  async restore(
+    container: ContainerConfig,
+    backupPath: string,
+    options: Record<string, unknown> = {},
+  ): Promise<RestoreResult> {
+    const { version, port } = container
+    const binPath = this.getBinaryPath(version)
+    const database = (options.database as string) || container.name
+
+    // First create the database if it doesn't exist
+    if (options.createDatabase !== false) {
+      await this.createDatabase(container, database)
+    }
+
+    return restoreBackup(binPath, backupPath, {
+      port,
+      database,
+      user: defaults.superuser,
+      ...(options as { format?: string }),
+    })
+  }
+
+  /**
+   * Get connection string
+   */
+  getConnectionString(container: ContainerConfig, database?: string): string {
+    const { port } = container
+    const db = database || 'postgres'
+    return `postgresql://${defaults.superuser}@localhost:${port}/${db}`
+  }
+
+  /**
+   * Get path to psql, using config manager to find it
+   */
+  async getPsqlPath(): Promise<string> {
+    const psqlPath = await configManager.getBinaryPath('psql')
+    if (!psqlPath) {
+      throw new Error(
+        'psql not found. 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 psql /path/to/psql',
+      )
+    }
+    return psqlPath
+  }
+
+  /**
+   * Get path to pg_restore, using config manager to find it
+   */
+  async getPgRestorePath(): Promise<string> {
+    const pgRestorePath = await configManager.getBinaryPath('pg_restore')
+    if (!pgRestorePath) {
+      throw new Error(
+        'pg_restore not found. 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_restore /path/to/pg_restore',
+      )
+    }
+    return pgRestorePath
+  }
+
+  /**
+   * Get path to pg_dump, using config manager to find it
+   */
+  async getPgDumpPath(): Promise<string> {
+    const pgDumpPath = await configManager.getBinaryPath('pg_dump')
+    if (!pgDumpPath) {
+      throw new Error(
+        'pg_dump not found. 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',
+      )
+    }
+    return pgDumpPath
+  }
+
+  /**
+   * Open psql interactive shell
+   */
+  async connect(container: ContainerConfig, database?: string): Promise<void> {
+    const { port } = container
+    const db = database || 'postgres'
+    const psqlPath = await this.getPsqlPath()
+
+    return new Promise((resolve, reject) => {
+      const proc = spawn(
+        psqlPath,
+        [
+          '-h',
+          '127.0.0.1',
+          '-p',
+          String(port),
+          '-U',
+          defaults.superuser,
+          '-d',
+          db,
+        ],
+        { stdio: 'inherit' },
+      )
+
+      proc.on('error', (err: NodeJS.ErrnoException) => {
+        reject(err)
+      })
+
+      proc.on('close', () => resolve())
+    })
+  }
+
+  /**
+   * Create a new database
+   */
+  async createDatabase(
+    container: ContainerConfig,
+    database: string,
+  ): Promise<void> {
+    const { port } = container
+    const psqlPath = await this.getPsqlPath()
+
+    try {
+      await execAsync(
+        `"${psqlPath}" -h 127.0.0.1 -p ${port} -U ${defaults.superuser} -d postgres -c 'CREATE DATABASE "${database}"'`,
+      )
+    } catch (error) {
+      const err = error as Error
+      // Ignore "database already exists" error
+      if (!err.message.includes('already exists')) {
+        throw error
+      }
+    }
+  }
+}
+
+export const postgresqlEngine = new PostgreSQLEngine()

package/src/engines/postgresql/restore.ts

@@ -0,0 +1,173 @@
+import { readFile } from 'fs/promises'
+import { exec } from 'child_process'
+import { promisify } from 'util'
+import { configManager } from '@/core/config-manager'
+import type { BackupFormat, RestoreResult } from '@/types'
+
+const execAsync = promisify(exec)
+
+/**
+ * Detect the format of a PostgreSQL backup file
+ */
+export async function detectBackupFormat(
+  filePath: string,
+): Promise<BackupFormat> {
+  // Read the first few bytes to detect format
+  const file = await readFile(filePath)
+  const buffer = Buffer.alloc(16)
+
+  // Copy first bytes
+  file.copy(buffer, 0, 0, Math.min(16, file.length))
+
+  // Check for PostgreSQL custom format magic number
+  // Custom format starts with "PGDMP"
+  if (buffer.toString('ascii', 0, 5) === 'PGDMP') {
+    return {
+      format: 'custom',
+      description: 'PostgreSQL custom format (pg_dump -Fc)',
+      restoreCommand: 'pg_restore',
+    }
+  }
+
+  // Check for tar format (directory dumps are usually tar)
+  // Tar files have "ustar" at offset 257
+  if (file.length > 262) {
+    const tarMagic = file.toString('ascii', 257, 262)
+    if (tarMagic === 'ustar') {
+      return {
+        format: 'tar',
+        description: 'PostgreSQL tar format (pg_dump -Ft)',
+        restoreCommand: 'pg_restore',
+      }
+    }
+  }
+
+  // Check for gzip compression
+  if (buffer[0] === 0x1f && buffer[1] === 0x8b) {
+    return {
+      format: 'compressed',
+      description: 'Gzip compressed (likely SQL or custom format)',
+      restoreCommand: 'auto',
+    }
+  }
+
+  // Check if it looks like SQL (starts with common SQL statements)
+  const textStart = buffer.toString('utf8', 0, 16).toLowerCase()
+  if (
+    textStart.startsWith('--') ||
+    textStart.startsWith('/*') ||
+    textStart.startsWith('set ') ||
+    textStart.startsWith('create') ||
+    textStart.startsWith('drop') ||
+    textStart.startsWith('begin') ||
+    textStart.startsWith('pg_dump')
+  ) {
+    return {
+      format: 'sql',
+      description: 'Plain SQL format (pg_dump -Fp)',
+      restoreCommand: 'psql',
+    }
+  }
+
+  // Default to trying custom format
+  return {
+    format: 'unknown',
+    description: 'Unknown format - will attempt custom format restore',
+    restoreCommand: 'pg_restore',
+  }
+}
+
+export interface RestoreOptions {
+  port: number
+  database: string
+  user?: string
+  format?: string
+}
+
+/**
+ * Get psql path from config, with helpful error message
+ */
+async function getPsqlPath(): Promise<string> {
+  const psqlPath = await configManager.getBinaryPath('psql')
+  if (!psqlPath) {
+    throw new Error(
+      'psql not found. 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 psql /path/to/psql',
+    )
+  }
+  return psqlPath
+}
+
+/**
+ * Get pg_restore path from config, with helpful error message
+ */
+async function getPgRestorePath(): Promise<string> {
+  const pgRestorePath = await configManager.getBinaryPath('pg_restore')
+  if (!pgRestorePath) {
+    throw new Error(
+      'pg_restore not found. 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_restore /path/to/pg_restore',
+    )
+  }
+  return pgRestorePath
+}
+
+/**
+ * Restore a backup to a PostgreSQL database
+ */
+export async function restoreBackup(
+  _binPath: string, // Not used - using config manager instead
+  backupPath: string,
+  options: RestoreOptions,
+): Promise<RestoreResult> {
+  const { port, database, user = 'postgres', format } = options
+
+  const detectedFormat = format || (await detectBackupFormat(backupPath)).format
+
+  if (detectedFormat === 'sql') {
+    const psqlPath = await getPsqlPath()
+
+    const result = await execAsync(
+      `"${psqlPath}" -h 127.0.0.1 -p ${port} -U ${user} -d ${database} -f "${backupPath}"`,
+      { maxBuffer: 50 * 1024 * 1024 }, // 50MB buffer for large dumps
+    )
+
+    return {
+      format: 'sql',
+      ...result,
+    }
+  } else {
+    const pgRestorePath = await getPgRestorePath()
+
+    try {
+      const formatFlag =
+        detectedFormat === 'custom'
+          ? '-Fc'
+          : detectedFormat === 'tar'
+            ? '-Ft'
+            : ''
+      const result = await execAsync(
+        `"${pgRestorePath}" -h 127.0.0.1 -p ${port} -U ${user} -d ${database} --no-owner --no-privileges ${formatFlag} "${backupPath}"`,
+        { maxBuffer: 50 * 1024 * 1024 },
+      )
+
+      return {
+        format: detectedFormat,
+        ...result,
+      }
+    } catch (err) {
+      const e = err as Error & { stdout?: string; stderr?: string }
+      // pg_restore often returns non-zero even on partial success
+      return {
+        format: detectedFormat,
+        stdout: e.stdout || '',
+        stderr: e.stderr || e.message,
+        code: 1,
+      }
+    }
+  }
+}