spindb 0.37.2 → 0.38.0

package/engines/cockroachdb/index.ts

@@ -1,1276 +0,0 @@
-/**
- * CockroachDB Engine Implementation
- *
- * CockroachDB is a distributed SQL database with PostgreSQL wire protocol compatibility.
- * It provides horizontal scaling, strong consistency, and built-in survivability.
- *
- * Key characteristics:
- * - Default SQL port: 26257
- * - HTTP UI port: SQL port + 1 (default 26258)
- * - Uses PostgreSQL wire protocol for client connections
- * - Single binary: `cockroach` (handles server, sql client, and admin tasks)
- * - Default database: `defaultdb`
- * - Default user: `root` (no password in insecure mode)
- */
-
-import { spawn, type SpawnOptions } from 'child_process'
-import { existsSync } from 'fs'
-import { mkdir, writeFile, readFile, unlink } from 'fs/promises'
-import { join } from 'path'
-import { BaseEngine } from '../base-engine'
-import { paths } from '../../config/paths'
-import { getEngineDefaults } from '../../config/defaults'
-import { platformService } from '../../core/platform-service'
-import { configManager } from '../../core/config-manager'
-import {
-  logDebug,
-  logWarning,
-  assertValidUsername,
-} from '../../core/error-handler'
-import { findBinary } from '../../core/dependency-manager'
-import { processManager } from '../../core/process-manager'
-import { cockroachdbBinaryManager } from './binary-manager'
-import { getBinaryUrl } from './binary-urls'
-import {
-  normalizeVersion,
-  SUPPORTED_MAJOR_VERSIONS,
-  COCKROACHDB_VERSION_MAP,
-} from './version-maps'
-import { fetchAvailableVersions as fetchHostdbVersions } from './hostdb-releases'
-import {
-  detectBackupFormat as detectBackupFormatImpl,
-  restoreBackup,
-} from './restore'
-import { createBackup } from './backup'
-import {
-  validateCockroachIdentifier,
-  escapeCockroachIdentifier,
-  escapeSqlValue,
-  parseCsvLine,
-  parseCsvRecords,
-  isInsecureConnection,
-} from './cli-utils'
-import {
-  type Platform,
-  type Arch,
-  type ContainerConfig,
-  type ProgressCallback,
-  type BackupFormat,
-  type BackupOptions,
-  type BackupResult,
-  type RestoreResult,
-  type DumpResult,
-  type StatusResult,
-  type QueryResult,
-  type QueryOptions,
-  type CreateUserOptions,
-  type UserCredentials,
-} from '../../types'
-import { parseCSVToQueryResult } from '../../core/query-parser'
-
-const ENGINE = 'cockroachdb'
-const engineDef = getEngineDefaults(ENGINE)
-
-export class CockroachDBEngine extends BaseEngine {
-  name = ENGINE
-  displayName = 'CockroachDB'
-  defaultPort = engineDef.defaultPort
-  supportedVersions = SUPPORTED_MAJOR_VERSIONS
-
-  // Get platform info for binary operations
-  getPlatformInfo(): { platform: Platform; arch: Arch } {
-    return platformService.getPlatformInfo()
-  }
-
-  // Fetch available versions from hostdb (dynamically or from cache/fallback)
-  async fetchAvailableVersions(): Promise<Record<string, string[]>> {
-    return fetchHostdbVersions()
-  }
-
-  // Get binary download URL from hostdb
-  getBinaryUrl(version: string, platform: Platform, arch: Arch): string {
-    return getBinaryUrl(version, platform, arch)
-  }
-
-  // Resolves version string to full version (e.g., '25' -> '25.4.2')
-  resolveFullVersion(version: string): string {
-    if (/^\d+\.\d+\.\d+$/.test(version)) {
-      return version
-    }
-    return COCKROACHDB_VERSION_MAP[version] || version
-  }
-
-  // Get the path where binaries for a version would be installed
-  getBinaryPath(version: string): string {
-    const fullVersion = this.resolveFullVersion(version)
-    const { platform: p, arch: a } = this.getPlatformInfo()
-    return paths.getBinaryPath({
-      engine: 'cockroachdb',
-      version: fullVersion,
-      platform: p,
-      arch: a,
-    })
-  }
-
-  // Verify that CockroachDB binaries are available
-  async verifyBinary(binPath: string): Promise<boolean> {
-    const ext = platformService.getExecutableExtension()
-    const cockroachPath = join(binPath, 'bin', `cockroach${ext}`)
-    return existsSync(cockroachPath)
-  }
-
-  // Check if a specific CockroachDB version is installed (downloaded)
-  async isBinaryInstalled(version: string): Promise<boolean> {
-    const { platform, arch } = this.getPlatformInfo()
-    return cockroachdbBinaryManager.isInstalled(version, platform, arch)
-  }
-
-  /**
-   * Ensure CockroachDB binaries are available for a specific version
-   * Downloads from hostdb if not already installed
-   * Returns the path to the bin directory
-   */
-  async ensureBinaries(
-    version: string,
-    onProgress?: ProgressCallback,
-  ): Promise<string> {
-    const { platform, arch } = this.getPlatformInfo()
-
-    const binPath = await cockroachdbBinaryManager.ensureInstalled(
-      version,
-      platform,
-      arch,
-      onProgress,
-    )
-
-    // Register binary in config
-    const ext = platformService.getExecutableExtension()
-    const cockroachPath = join(binPath, 'bin', `cockroach${ext}`)
-    if (existsSync(cockroachPath)) {
-      await configManager.setBinaryPath('cockroach', cockroachPath, 'bundled')
-    }
-
-    return binPath
-  }
-
-  /**
-   * Initialize a new CockroachDB data directory
-   * Creates the directory structure for CockroachDB's storage
-   */
-  async initDataDir(
-    containerName: string,
-    _version: string,
-    _options: Record<string, unknown> = {},
-  ): Promise<string> {
-    const dataDir = paths.getContainerDataPath(containerName, {
-      engine: ENGINE,
-    })
-
-    // Create data directory
-    await mkdir(dataDir, { recursive: true })
-
-    logDebug(`Created CockroachDB data directory: ${dataDir}`)
-
-    return dataDir
-  }
-
-  // Get the path to cockroach binary for a version
-  async getCockroachPath(version: string): Promise<string> {
-    const { platform, arch } = this.getPlatformInfo()
-    const fullVersion = normalizeVersion(version)
-    const ext = platformService.getExecutableExtension()
-
-    const binPath = paths.getBinaryPath({
-      engine: 'cockroachdb',
-      version: fullVersion,
-      platform,
-      arch,
-    })
-    const cockroachPath = join(binPath, 'bin', `cockroach${ext}`)
-
-    if (existsSync(cockroachPath)) {
-      return cockroachPath
-    }
-
-    throw new Error(
-      `CockroachDB ${version} is not installed. Run: spindb engines download cockroachdb ${version}`,
-    )
-  }
-
-  /**
-   * Start CockroachDB server
-   */
-  async start(
-    container: ContainerConfig,
-    onProgress?: ProgressCallback,
-  ): Promise<{ port: number; connectionString: string }> {
-    const { name, port, version, binaryPath } = container
-
-    // Check if already running
-    const alreadyRunning = await processManager.isRunning(name, {
-      engine: ENGINE,
-    })
-    if (alreadyRunning) {
-      return {
-        port,
-        connectionString: this.getConnectionString(container),
-      }
-    }
-
-    // Get CockroachDB binary path
-    let cockroachBinary: string | null = null
-    const ext = platformService.getExecutableExtension()
-
-    if (binaryPath && existsSync(binaryPath)) {
-      const serverPath = join(binaryPath, 'bin', `cockroach${ext}`)
-      if (existsSync(serverPath)) {
-        cockroachBinary = serverPath
-        logDebug(`Using stored binary path: ${cockroachBinary}`)
-      }
-    }
-
-    if (!cockroachBinary) {
-      try {
-        cockroachBinary = await this.getCockroachPath(version)
-      } catch (error) {
-        const originalMessage =
-          error instanceof Error ? error.message : String(error)
-        throw new Error(
-          `CockroachDB ${version} is not installed. Run: spindb engines download cockroachdb ${version}\n` +
-            `  Original error: ${originalMessage}`,
-        )
-      }
-    }
-
-    const containerDir = paths.getContainerPath(name, { engine: ENGINE })
-    const dataDir = paths.getContainerDataPath(name, { engine: ENGINE })
-    const logFile = join(containerDir, 'cockroach.log')
-    const pidFile = join(containerDir, 'cockroach.pid')
-    const httpPort = port + 1 // HTTP admin UI port
-
-    onProgress?.({ stage: 'starting', message: 'Starting CockroachDB...' })
-
-    logDebug(`Starting CockroachDB with data dir: ${dataDir}`)
-
-    // CockroachDB start command
-    // Using --insecure for local development (no TLS)
-    const args = [
-      'start-single-node',
-      '--insecure',
-      '--store',
-      dataDir,
-      '--listen-addr',
-      `127.0.0.1:${port}`,
-      '--http-addr',
-      `127.0.0.1:${httpPort}`,
-      '--pid-file',
-      pidFile,
-      '--log-dir',
-      containerDir,
-    ]
-
-    // On Unix, use --background flag which forks a daemon process
-    // On Windows, don't use --background - Windows doesn't have the same fork model
-    // and CockroachDB's background mode can fail silently. Instead, we detach manually.
-    const isWindows = process.platform === 'win32'
-    if (!isWindows) {
-      args.push('--background')
-    }
-
-    // IMPORTANT: Use 'ignore' for all stdio on all platforms.
-    // Using 'pipe' keeps file descriptors open which prevents proc.unref() from
-    // allowing Node.js to exit, causing spawn timeouts even when the process starts successfully.
-    const proc = spawn(cockroachBinary!, args, {
-      stdio: ['ignore', 'ignore', 'ignore'],
-      detached: true,
-      // On Windows, set cwd to container directory to ensure proper file handle behavior
-      cwd: isWindows ? containerDir : undefined,
-      // On Windows, hide the console window to prevent it from blocking
-      windowsHide: true,
-    })
-
-    // On Windows without --background, write PID file ourselves
-    // (On Unix, --background makes CockroachDB write the daemon PID)
-    if (isWindows && proc.pid) {
-      try {
-        await writeFile(pidFile, proc.pid.toString(), 'utf-8')
-        logDebug(`Wrote PID file: ${pidFile} (pid: ${proc.pid})`)
-      } catch (err) {
-        // PID file write failed - kill the process and fail fast
-        // Without the PID file, we can't stop the container later
-        const errMsg = `Failed to write PID file: ${err instanceof Error ? err.message : String(err)}`
-        logDebug(errMsg)
-        try {
-          process.kill(proc.pid, 'SIGTERM')
-        } catch {
-          // Process may have already exited
-        }
-        throw new Error(errMsg)
-      }
-    }
-
-    // Wait for the process to spawn
-    // On Windows, the 'spawn' event doesn't fire reliably with detached processes,
-    // so we use a simple delay and let waitForReady() handle detection.
-    // On Unix with --background, we wait for the spawn event.
-    if (isWindows) {
-      // Add error handler to catch spawn failures on Windows
-      await new Promise<void>((resolve, reject) => {
-        proc.on('error', (err) => {
-          logDebug(`CockroachDB spawn error on Windows: ${err}`)
-          reject(err)
-        })
-        proc.unref()
-        logDebug(
-          `Windows: waiting fixed delay for CockroachDB to start (pid: ${proc.pid})`,
-        )
-        setTimeout(resolve, 3000)
-      })
-    } else {
-      const spawnTimeout = 30000 // 30 seconds to spawn
-      await new Promise<void>((resolve, reject) => {
-        const timeoutId = setTimeout(() => {
-          reject(
-            new Error(
-              `CockroachDB process failed to spawn within ${spawnTimeout}ms`,
-            ),
-          )
-        }, spawnTimeout)
-
-        proc.on('error', (err) => {
-          clearTimeout(timeoutId)
-          logDebug(`CockroachDB spawn error: ${err}`)
-          reject(err)
-        })
-        proc.on('spawn', () => {
-          clearTimeout(timeoutId)
-          logDebug(`CockroachDB process spawned (pid: ${proc.pid})`)
-          proc.unref()
-          setTimeout(resolve, 500)
-        })
-      })
-    }
-
-    // Wait for server to be ready
-    // Windows needs a longer timeout since CockroachDB initialization takes more time
-    const timeout = isWindows ? 120000 : 60000
-    logDebug(
-      `Waiting for CockroachDB server to be ready on port ${port}... (timeout: ${timeout}ms)`,
-    )
-    const ready = await this.waitForReady(port, version, timeout)
-    logDebug(`waitForReady returned: ${ready}`)
-
-    if (!ready) {
-      // Clean up the spawned process and PID file before throwing
-      try {
-        const pidStr = await readFile(pidFile, 'utf-8').catch(() => null)
-        if (pidStr) {
-          const pid = parseInt(pidStr.trim(), 10)
-          if (!isNaN(pid)) {
-            logDebug(`Cleaning up failed CockroachDB process (pid: ${pid})`)
-            await platformService.terminateProcess(pid, true)
-          }
-        }
-        await unlink(pidFile).catch(() => {})
-      } catch {
-        // Ignore cleanup errors
-      }
-      throw new Error(
-        `CockroachDB failed to start within timeout. Check logs at: ${logFile}`,
-      )
-    }
-
-    return {
-      port,
-      connectionString: this.getConnectionString(container),
-    }
-  }
-
-  // Wait for CockroachDB to be ready
-  private async waitForReady(
-    port: number,
-    version: string,
-    timeoutMs = 60000,
-  ): Promise<boolean> {
-    logDebug(`waitForReady called for port ${port}, version ${version}`)
-    const startTime = Date.now()
-    const checkInterval = 500
-
-    let cockroach: string
-    try {
-      logDebug('Getting cockroach binary path...')
-      cockroach = await this.getCockroachPath(version)
-      logDebug(`Got cockroach binary path: ${cockroach}`)
-    } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : String(err)
-      logDebug(`Error getting cockroach binary path: ${errorMessage}`)
-      logWarning(
-        `CockroachDB binary not found, cannot verify server is ready: ${errorMessage}`,
-      )
-      return false
-    }
-
-    logDebug(`Starting connection loop, timeout: ${timeoutMs}ms`)
-    let attempt = 0
-    while (Date.now() - startTime < timeoutMs) {
-      attempt++
-      logDebug(`Connection attempt ${attempt}...`)
-      try {
-        const args = [
-          'sql',
-          '--insecure',
-          '--host',
-          `127.0.0.1:${port}`,
-          '--execute',
-          'SELECT 1',
-        ]
-        await new Promise<void>((resolve, reject) => {
-          const proc = spawn(cockroach, args, {
-            stdio: ['ignore', 'pipe', 'pipe'],
-          })
-          proc.on('close', (code) => {
-            logDebug(`Client process closed with code ${code}`)
-            if (code === 0) resolve()
-            else reject(new Error(`Exit code ${code}`))
-          })
-          proc.on('error', (err) => {
-            logDebug(`Client process error: ${err}`)
-            reject(err)
-          })
-        })
-        logDebug(`CockroachDB ready on port ${port}`)
-        return true
-      } catch (err) {
-        logDebug(`Attempt ${attempt} failed: ${err}`)
-        await new Promise((resolve) => setTimeout(resolve, checkInterval))
-      }
-    }
-
-    logWarning(`CockroachDB did not become ready within ${timeoutMs}ms`)
-    return false
-  }
-
-  /**
-   * Stop CockroachDB server
-   */
-  async stop(container: ContainerConfig): Promise<void> {
-    const { name, port } = container
-    const containerDir = paths.getContainerPath(name, { engine: ENGINE })
-    const pidFile = join(containerDir, 'cockroach.pid')
-
-    logDebug(`Stopping CockroachDB container "${name}" on port ${port}`)
-
-    // Find PID by checking the process using cross-platform helper
-    let pid: number | null = null
-
-    // Try to find CockroachDB process by port
-    try {
-      const pids = await platformService.findProcessByPort(port)
-      if (pids.length > 0) {
-        pid = pids[0]
-      }
-    } catch {
-      // Ignore
-    }
-
-    // Kill process if found
-    if (pid && platformService.isProcessRunning(pid)) {
-      logDebug(`Killing CockroachDB process ${pid}`)
-      try {
-        await platformService.terminateProcess(pid, false)
-        // Wait for graceful termination
-        // On Windows, CockroachDB's RocksDB uses memory-mapped files that
-        // take longer to release, so we wait longer to avoid EBUSY errors
-        const gracefulWait = process.platform === 'win32' ? 5000 : 2000
-        await new Promise((resolve) => setTimeout(resolve, gracefulWait))
-
-        if (platformService.isProcessRunning(pid)) {
-          logWarning(`Graceful termination failed, force killing ${pid}`)
-          await platformService.terminateProcess(pid, true)
-          // Additional wait after force kill on Windows for file handle release
-          if (process.platform === 'win32') {
-            await new Promise((resolve) => setTimeout(resolve, 3000))
-          }
-        }
-      } catch (error) {
-        logDebug(`Process termination error: ${error}`)
-      }
-    }
-
-    // Cleanup PID file
-    if (existsSync(pidFile)) {
-      try {
-        await unlink(pidFile)
-      } catch {
-        // Ignore
-      }
-    }
-
-    // Kill pgweb if running for this container
-    await this.stopPgweb(name)
-
-    logDebug('CockroachDB stopped')
-  }
-
-  // Get CockroachDB server status
-  async status(container: ContainerConfig): Promise<StatusResult> {
-    const { port, version } = container
-
-    // Try to connect
-    try {
-      const cockroach = await this.getCockroachPath(version)
-      const args = [
-        'sql',
-        '--insecure',
-        '--host',
-        `127.0.0.1:${port}`,
-        '--execute',
-        'SELECT 1',
-      ]
-      await new Promise<void>((resolve, reject) => {
-        const proc = spawn(cockroach, args, {
-          stdio: ['ignore', 'pipe', 'pipe'],
-        })
-        proc.on('close', (code) => {
-          if (code === 0) resolve()
-          else reject(new Error(`Exit code ${code}`))
-        })
-        proc.on('error', reject)
-      })
-      return { running: true, message: 'CockroachDB is running' }
-    } catch {
-      return { running: false, message: 'CockroachDB is not running' }
-    }
-  }
-
-  // Detect backup format
-  async detectBackupFormat(filePath: string): Promise<BackupFormat> {
-    return detectBackupFormatImpl(filePath)
-  }
-
-  /**
-   * Restore a backup
-   */
-  async restore(
-    container: ContainerConfig,
-    backupPath: string,
-    options: { database?: string; clean?: boolean } = {},
-  ): Promise<RestoreResult> {
-    const { name, port, version } = container
-
-    return restoreBackup(backupPath, {
-      containerName: name,
-      port,
-      database: options.database || container.database || 'defaultdb',
-      version,
-      clean: options.clean,
-    })
-  }
-
-  /**
-   * Get connection string
-   * Format: postgresql://root@127.0.0.1:PORT/DATABASE?sslmode=disable
-   */
-  getConnectionString(container: ContainerConfig, database?: string): string {
-    const { port } = container
-    const db = database || container.database || 'defaultdb'
-    return `postgresql://root@127.0.0.1:${port}/${db}?sslmode=disable`
-  }
-
-  // Open cockroach sql interactive shell
-  async connect(container: ContainerConfig, database?: string): Promise<void> {
-    const { port, version } = container
-    const db = database || container.database || 'defaultdb'
-
-    const cockroach = await this.getCockroachPath(version)
-
-    const spawnOptions: SpawnOptions = {
-      stdio: 'inherit',
-    }
-
-    return new Promise((resolve, reject) => {
-      const proc = spawn(
-        cockroach,
-        ['sql', '--insecure', '--host', `127.0.0.1:${port}`, '--database', db],
-        spawnOptions,
-      )
-
-      proc.on('error', reject)
-      proc.on('close', () => resolve())
-    })
-  }
-
-  /**
-   * Create a new database
-   */
-  async createDatabase(
-    container: ContainerConfig,
-    database: string,
-  ): Promise<void> {
-    const { port, version } = container
-
-    // Validate database identifier to prevent SQL injection
-    validateCockroachIdentifier(database, 'database')
-    const escapedDb = escapeCockroachIdentifier(database)
-
-    const cockroach = await this.getCockroachPath(version)
-
-    const args = [
-      'sql',
-      '--insecure',
-      '--host',
-      `127.0.0.1:${port}`,
-      '--execute',
-      `CREATE DATABASE IF NOT EXISTS ${escapedDb}`,
-    ]
-
-    await new Promise<void>((resolve, reject) => {
-      const proc = spawn(cockroach, args, {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      })
-
-      let stderr = ''
-      proc.stderr?.on('data', (data: Buffer) => {
-        stderr += data.toString()
-      })
-
-      proc.on('close', (code) => {
-        if (code === 0) {
-          logDebug(`Created CockroachDB database: ${database}`)
-          resolve()
-        } else {
-          reject(new Error(`Failed to create database: ${stderr}`))
-        }
-      })
-      proc.on('error', reject)
-    })
-  }
-
-  /**
-   * Drop a database
-   */
-  async dropDatabase(
-    container: ContainerConfig,
-    database: string,
-  ): Promise<void> {
-    const { port, version } = container
-
-    // Don't allow dropping system databases
-    const systemDatabases = ['defaultdb', 'postgres', 'system']
-    if (systemDatabases.includes(database.toLowerCase())) {
-      throw new Error(`Cannot drop system database: ${database}`)
-    }
-
-    // Validate database identifier to prevent SQL injection
-    validateCockroachIdentifier(database, 'database')
-    const escapedDb = escapeCockroachIdentifier(database)
-
-    const cockroach = await this.getCockroachPath(version)
-
-    const args = [
-      'sql',
-      '--insecure',
-      '--host',
-      `127.0.0.1:${port}`,
-      '--execute',
-      `DROP DATABASE IF EXISTS ${escapedDb}`,
-    ]
-
-    await new Promise<void>((resolve, reject) => {
-      const proc = spawn(cockroach, args, {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      })
-
-      let stderr = ''
-      proc.stderr?.on('data', (data: Buffer) => {
-        stderr += data.toString()
-      })
-
-      proc.on('close', (code) => {
-        if (code === 0) {
-          logDebug(`Dropped CockroachDB database: ${database}`)
-          resolve()
-        } else {
-          reject(new Error(`Failed to drop database: ${stderr}`))
-        }
-      })
-      proc.on('error', reject)
-    })
-  }
-
-  /**
-   * Get the database size in bytes
-   */
-  async getDatabaseSize(container: ContainerConfig): Promise<number | null> {
-    const { port, version, database } = container
-    const db = database || 'defaultdb'
-
-    try {
-      const cockroach = await this.getCockroachPath(version)
-      validateCockroachIdentifier(db, 'database')
-
-      // CockroachDB query to get database size
-      const query = `SELECT sum(range_size_mb) * 1024 * 1024 as size_bytes FROM [SHOW RANGES FROM DATABASE ${escapeCockroachIdentifier(db)}]`
-
-      const result = await new Promise<string>((resolve, reject) => {
-        const args = [
-          'sql',
-          '--insecure',
-          '--host',
-          `127.0.0.1:${port}`,
-          '--database',
-          db,
-          '--execute',
-          query,
-          '--format=csv',
-        ]
-
-        const proc = spawn(cockroach, args, {
-          stdio: ['ignore', 'pipe', 'pipe'],
-        })
-
-        let stdout = ''
-        proc.stdout?.on('data', (data: Buffer) => {
-          stdout += data.toString()
-        })
-
-        proc.on('close', (code) => {
-          if (code === 0) resolve(stdout.trim())
-          else reject(new Error(`Exit code ${code}`))
-        })
-        proc.on('error', reject)
-      })
-
-      // Parse CSV output - skip header
-      const lines = result.split('\n')
-      if (lines.length >= 2) {
-        const size = parseFloat(lines[1])
-        return isNaN(size) ? null : Math.round(size)
-      }
-
-      return null
-    } catch {
-      return null
-    }
-  }
-
-  /**
-   * Dump from a remote CockroachDB connection
-   * Uses cockroach sql to export schema and data
-   *
-   * Connection string format: postgresql://[user[:password]@]host[:port][/database][?sslmode=...]
-   *
-   * Supports both insecure (local dev) and secure (production) connections:
-   * - sslmode=disable or localhost without sslmode: uses --insecure flag
-   * - Other SSL modes: passes connection string directly (handles certs via URL params)
-   */
-  async dumpFromConnectionString(
-    connectionString: string,
-    outputPath: string,
-  ): Promise<DumpResult> {
-    // Parse connection string
-    let url: URL
-    try {
-      url = new URL(connectionString)
-    } catch {
-      // Redact credentials before including in error message
-      const sanitized = connectionString.replace(/\/\/([^@]+)@/, '//***@')
-      throw new Error(
-        `Invalid connection string: ${sanitized}\n` +
-          'Expected format: postgresql://[user[:password]@]host[:port][/database][?sslmode=...]',
-      )
-    }
-
-    const host = url.hostname || '127.0.0.1'
-    const port = parseInt(url.port, 10) || 26257
-    const database = url.pathname.replace(/^\//, '') || 'defaultdb'
-
-    logDebug(
-      `Connecting to remote CockroachDB at ${host}:${port} (db: ${database})`,
-    )
-
-    // For remote dump, we need a local cockroach binary
-    // Try multiple methods to find an installed version
-    let cockroach: string | null = null
-
-    // 1. Try 'cockroach' key in config
-    const cachedCockroach = await configManager.getBinaryPath('cockroach')
-    if (cachedCockroach && existsSync(cachedCockroach)) {
-      cockroach = cachedCockroach
-      logDebug(
-        `Found cockroach binary via 'cockroach' config key: ${cockroach}`,
-      )
-    }
-
-    // 2. Try to find via dependency manager (checks config + system PATH)
-    if (!cockroach) {
-      const binaryResult = await findBinary('cockroach')
-      if (binaryResult?.path && existsSync(binaryResult.path)) {
-        cockroach = binaryResult.path
-        logDebug(`Found cockroach binary via dependency manager: ${cockroach}`)
-      }
-    }
-
-    // 3. Try to use any downloaded version via getCockroachPath
-    if (!cockroach) {
-      for (const version of SUPPORTED_MAJOR_VERSIONS) {
-        try {
-          cockroach = await this.getCockroachPath(version)
-          logDebug(
-            `Found cockroach binary for version ${version}: ${cockroach}`,
-          )
-          break
-        } catch {
-          // Version not installed, try next
-        }
-      }
-    }
-
-    if (!cockroach) {
-      throw new Error(
-        'CockroachDB binary not found. Run: spindb engines download cockroachdb 25\n' +
-          'A local CockroachDB binary is needed to dump from remote connections.',
-      )
-    }
-
-    const lines: string[] = []
-    lines.push('-- CockroachDB backup generated by SpinDB')
-    lines.push(`-- Source: ${host}:${port}`)
-    lines.push(`-- Database: ${database}`)
-    lines.push(`-- Date: ${new Date().toISOString()}`)
-    lines.push('')
-
-    // Build connection args using --url to preserve auth/SSL settings
-    const connArgs = ['sql', '--url', connectionString]
-
-    // Only add --insecure for local dev or explicit sslmode=disable
-    if (isInsecureConnection(connectionString)) {
-      connArgs.push('--insecure')
-    }
-
-    // Get list of tables
-    const tablesQuery = `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_type = 'BASE TABLE' ORDER BY table_name`
-    const tablesResult = await this.execRemoteQuery(
-      cockroach,
-      connArgs,
-      tablesQuery,
-    )
-    // Parse CSV output properly to handle quoted identifiers
-    const tableRecords = parseCsvRecords(tablesResult, true) // Skip header
-    const tables = tableRecords
-      .map((line) => {
-        const fields = parseCsvLine(line)
-        return fields.length > 0 ? fields[0].value : ''
-      })
-      .filter((t) => t)
-
-    logDebug(`Found ${tables.length} tables in database ${database}`)
-
-    for (const table of tables) {
-      // Table names from information_schema are safe (already unquoted by CSV parser)
-      // Only validate that we got a non-empty name
-      if (!table) {
-        continue
-      }
-
-      lines.push(`-- Table: ${table}`)
-      lines.push('')
-
-      // Get CREATE TABLE - use proper identifier escaping
-      try {
-        const createQuery = `SHOW CREATE TABLE ${escapeCockroachIdentifier(table)}`
-        const createResult = await this.execRemoteQuery(
-          cockroach,
-          connArgs,
-          createQuery,
-        )
-        // Parse CSV output safely using record-aware parser
-        // Format is: table_name,create_statement (create statement may contain newlines)
-        const createRecords = parseCsvRecords(createResult, true) // Skip header
-        if (createRecords.length > 0) {
-          const columns = parseCsvLine(createRecords[0])
-          if (columns.length >= 2) {
-            // Second column is the CREATE TABLE statement
-            const createStatement = columns[1].value.trim()
-            lines.push(createStatement + ';')
-          } else {
-            logWarning(`Unexpected SHOW CREATE TABLE output for ${table}`)
-          }
-        }
-        lines.push('')
-      } catch (error) {
-        logWarning(`Could not get CREATE TABLE for ${table}: ${error}`)
-        continue
-      }
-
-      // Export table data
-      try {
-        // Get column names first
-        // Escape single quotes in table name for string literal comparison
-        const escapedTableForString = table.replace(/'/g, "''")
-        const columnsQuery = `SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = '${escapedTableForString}' ORDER BY ordinal_position`
-        const columnsResult = await this.execRemoteQuery(
-          cockroach,
-          connArgs,
-          columnsQuery,
-        )
-        // Parse each CSV record properly to handle quoted column names
-        const columnRecords = parseCsvRecords(columnsResult, true) // Skip header
-        const columns = columnRecords
-          .map((record) => {
-            const fields = parseCsvLine(record)
-            return fields.length > 0 ? fields[0].value.trim() : ''
-          })
-          .filter((c) => c)
-
-        if (columns.length === 0) {
-          logDebug(`No columns found for table ${table}, skipping data export`)
-          continue
-        }
-
-        // Get all rows - use proper identifier escaping
-        const dataQuery = `SELECT * FROM ${escapeCockroachIdentifier(table)}`
-        const dataResult = await this.execRemoteQuery(
-          cockroach,
-          connArgs,
-          dataQuery,
-        )
-        // Use record-aware parser to handle fields with embedded newlines
-        const dataRecords = parseCsvRecords(dataResult, true) // Skip header
-
-        if (dataRecords.length > 0) {
-          lines.push(`-- Data for ${table}`)
-
-          for (const dataRecord of dataRecords) {
-            const fields = parseCsvLine(dataRecord)
-            if (fields.length !== columns.length) {
-              logWarning(
-                `Column count mismatch for table ${table}: expected ${columns.length}, got ${fields.length}`,
-              )
-              continue
-            }
-
-            const escapedCols = columns
-              .map((c) => escapeCockroachIdentifier(c))
-              .join(', ')
-            const escapedVals = fields
-              .map((f) => escapeSqlValue(f.value, f.wasQuoted))
-              .join(', ')
-            lines.push(
-              `INSERT INTO ${escapeCockroachIdentifier(table)} (${escapedCols}) VALUES (${escapedVals});`,
-            )
-          }
-          lines.push('')
-        }
-      } catch (error) {
-        logWarning(`Could not export data for table ${table}: ${error}`)
-      }
-    }
-
-    // Write to file
-    const content = lines.join('\n')
-    await writeFile(outputPath, content, 'utf-8')
-
-    return {
-      filePath: outputPath,
-      warnings:
-        tables.length === 0
-          ? [`Database '${database}' has no tables`]
-          : undefined,
-    }
-  }
-
-  // Helper to execute a query on a remote CockroachDB
-  private async execRemoteQuery(
-    cockroach: string,
-    connArgs: string[],
-    query: string,
-  ): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const args = [...connArgs, '--execute', query, '--format=csv']
-
-      const proc = spawn(cockroach, args, {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      })
-
-      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(stdout)
-        } else {
-          reject(new Error(stderr || `Exit code ${code}`))
-        }
-      })
-      proc.on('error', reject)
-    })
-  }
-
-  // Create a backup
-  async backup(
-    container: ContainerConfig,
-    outputPath: string,
-    options: BackupOptions,
-  ): Promise<BackupResult> {
-    return createBackup(container, outputPath, options)
-  }
-
-  // Run a SQL file or inline SQL statement
-  async runScript(
-    container: ContainerConfig,
-    options: { file?: string; sql?: string; database?: string },
-  ): Promise<void> {
-    const { port, version } = container
-    const db = options.database || container.database || 'defaultdb'
-
-    const cockroach = await this.getCockroachPath(version)
-
-    if (options.file) {
-      // Run SQL file
-      const args = [
-        'sql',
-        '--insecure',
-        '--host',
-        `127.0.0.1:${port}`,
-        '--database',
-        db,
-        '--file',
-        options.file,
-      ]
-
-      await new Promise<void>((resolve, reject) => {
-        const proc = spawn(cockroach, args, {
-          stdio: 'inherit',
-        })
-
-        proc.on('error', reject)
-        proc.on('close', (code) => {
-          if (code === 0) {
-            resolve()
-          } else if (code === null) {
-            reject(new Error('cockroach sql was terminated by a signal'))
-          } else {
-            reject(new Error(`cockroach sql exited with code ${code}`))
-          }
-        })
-      })
-    } else if (options.sql) {
-      // Run inline SQL via stdin
-      const args = [
-        'sql',
-        '--insecure',
-        '--host',
-        `127.0.0.1:${port}`,
-        '--database',
-        db,
-      ]
-
-      await new Promise<void>((resolve, reject) => {
-        const proc = spawn(cockroach, args, {
-          stdio: ['pipe', 'inherit', 'inherit'],
-        })
-
-        proc.on('error', reject)
-        proc.on('close', (code) => {
-          if (code === 0) {
-            resolve()
-          } else if (code === null) {
-            reject(new Error('cockroach sql was terminated by a signal'))
-          } else {
-            reject(new Error(`cockroach sql exited with code ${code}`))
-          }
-        })
-
-        proc.stdin?.write(options.sql)
-        proc.stdin?.end()
-      })
-    } else {
-      throw new Error('Either file or sql option must be provided')
-    }
-  }
-
-  /**
-   * Execute a SQL query and return structured results
-   */
-  async executeQuery(
-    container: ContainerConfig,
-    query: string,
-    options?: QueryOptions,
-  ): Promise<QueryResult> {
-    const { port, version } = container
-    const db = options?.database || container.database || 'defaultdb'
-
-    const cockroach = await this.getCockroachPath(version)
-
-    return new Promise((resolve, reject) => {
-      const args = [
-        'sql',
-        '--insecure',
-        '--host',
-        `127.0.0.1:${port}`,
-        '--database',
-        db,
-        '--execute',
-        query,
-        '--format=csv',
-      ]
-
-      const proc = spawn(cockroach, args, {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      })
-
-      let stdout = ''
-      let stderr = ''
-
-      proc.stdout?.on('data', (data: Buffer) => {
-        stdout += data.toString()
-      })
-      proc.stderr?.on('data', (data: Buffer) => {
-        stderr += data.toString()
-      })
-
-      proc.on('error', reject)
-
-      proc.on('close', (code) => {
-        if (code !== 0) {
-          reject(new Error(stderr || `cockroach sql exited with code ${code}`))
-          return
-        }
-
-        try {
-          resolve(parseCSVToQueryResult(stdout))
-        } catch (error) {
-          reject(
-            new Error(
-              `Failed to parse query result: ${error instanceof Error ? error.message : error}`,
-            ),
-          )
-        }
-      })
-    })
-  }
-
-  /**
-   * List all user databases, excluding system databases (defaultdb, postgres, system).
-   */
-  async listDatabases(container: ContainerConfig): Promise<string[]> {
-    const { port, version } = container
-    const cockroach = await this.getCockroachPath(version)
-
-    return new Promise((resolve, reject) => {
-      const args = [
-        'sql',
-        '--insecure',
-        '--host',
-        `127.0.0.1:${port}`,
-        '--execute',
-        `SHOW DATABASES`,
-        '--format=csv',
-      ]
-
-      const proc = spawn(cockroach, args, {
-        stdio: ['ignore', 'pipe', 'pipe'],
-      })
-
-      let stdout = ''
-      let stderr = ''
-
-      proc.stdout?.on('data', (data: Buffer) => {
-        stdout += data.toString()
-      })
-      proc.stderr?.on('data', (data: Buffer) => {
-        stderr += data.toString()
-      })
-
-      proc.on('error', reject)
-
-      proc.on('close', (code) => {
-        if (code !== 0) {
-          reject(new Error(stderr || `cockroach sql exited with code ${code}`))
-          return
-        }
-
-        // Parse CSV output (first column is database_name, skip header)
-        const systemDatabases = ['defaultdb', 'postgres', 'system']
-        const lines = stdout.trim().split('\n')
-        const databases = lines
-          .slice(1) // Skip header
-          .map((line) => line.split(',')[0].trim())
-          .filter((db) => db.length > 0 && !systemDatabases.includes(db))
-
-        resolve(databases)
-      })
-    })
-  }
-
-  async createUser(
-    container: ContainerConfig,
-    options: CreateUserOptions,
-  ): Promise<UserCredentials> {
-    const { username, password, database } = options
-    assertValidUsername(username)
-    const { port, version } = container
-    const db = database || container.database || 'defaultdb'
-
-    validateCockroachIdentifier(username, 'user')
-    validateCockroachIdentifier(db, 'database')
-    const escapedUser = escapeCockroachIdentifier(username)
-    const escapedDb = escapeCockroachIdentifier(db)
-
-    const cockroach = await this.getCockroachPath(version)
-
-    // CockroachDB in insecure mode doesn't support passwords.
-    // Create user without password and grant privileges.
-    // SQL is sent via stdin to avoid shell escaping issues with --execute.
-    const sql = `CREATE USER IF NOT EXISTS ${escapedUser}; GRANT ALL ON DATABASE ${escapedDb} TO ${escapedUser};`
-
-    const args = ['sql', '--insecure', '--host', `127.0.0.1:${port}`]
-
-    await new Promise<void>((resolve, reject) => {
-      const proc = spawn(cockroach, args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-      })
-
-      let stderr = ''
-      proc.stderr?.on('data', (data: Buffer) => {
-        stderr += data.toString()
-      })
-
-      proc.on('close', (code) => {
-        if (code === 0) {
-          resolve()
-        } else {
-          reject(new Error(`Failed to create user: ${stderr}`))
-        }
-      })
-      proc.on('error', reject)
-
-      proc.stdin?.write(sql)
-      proc.stdin?.end()
-    })
-
-    // In insecure mode, connections don't use passwords
-    const connectionString = `postgresql://${encodeURIComponent(username)}@127.0.0.1:${port}/${db}?sslmode=disable`
-
-    return {
-      username,
-      // CockroachDB insecure mode does not enforce password authentication,
-      // but we return the caller-provided password for credential file consistency.
-      password,
-      connectionString,
-      engine: container.engine,
-      container: container.name,
-      database: db,
-    }
-  }
-}
-
-export const cockroachdbEngine = new CockroachDBEngine()