spindb 0.37.2 → 0.38.0

package/engines/ferretdb/index.ts

@@ -1,1907 +0,0 @@
-/**
- * FerretDB Engine implementation
- *
- * FerretDB is a MongoDB-compatible proxy that stores data in PostgreSQL.
- * This is a composite engine that manages two processes:
- * 1. PostgreSQL backend (postgresql-documentdb)
- * 2. FerretDB proxy
- *
- * The lifecycle is:
- * - Start: Start PostgreSQL → Wait for ready → Start FerretDB
- * - Stop: Stop FerretDB → Stop PostgreSQL
- */
-
-import {
-  spawn,
-  exec,
-  type ChildProcess,
-  type SpawnOptions,
-} from 'child_process'
-import { promisify } from 'util'
-import { existsSync } from 'fs'
-import net from 'net'
-import {
-  mkdir,
-  writeFile,
-  readFile,
-  symlink,
-  unlink,
-  readdir,
-} from 'fs/promises'
-import { join, basename, dirname } from 'path'
-import { BaseEngine } from '../base-engine'
-import { paths } from '../../config/paths'
-import { getEngineDefaults } from '../../config/defaults'
-import { platformService, isWindows } from '../../core/platform-service'
-import { configManager } from '../../core/config-manager'
-import { containerManager } from '../../core/container-manager'
-import {
-  logDebug,
-  logWarning,
-  assertValidDatabaseName,
-  assertValidUsername,
-} from '../../core/error-handler'
-import { processManager } from '../../core/process-manager'
-import { spawnAsync } from '../../core/spawn-utils'
-import { ferretdbBinaryManager } from './binary-manager'
-import {
-  SUPPORTED_MAJOR_VERSIONS,
-  FALLBACK_VERSION_MAP,
-  DEFAULT_DOCUMENTDB_VERSION,
-  DEFAULT_V1_POSTGRESQL_VERSION,
-  normalizeVersion,
-  normalizeDocumentDBVersion,
-  isV1,
-} from './version-maps'
-import { getBinaryUrls, isPlatformSupported } from './binary-urls'
-import {
-  detectBackupFormat as detectBackupFormatImpl,
-  restoreBackup,
-} from './restore'
-import { createBackup } from './backup'
-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 { parseMongoDBResult } from '../../core/query-parser'
-
-const execAsync = promisify(exec)
-
-const ENGINE = 'ferretdb'
-const engineDef = getEngineDefaults(ENGINE)
-
-// Default internal PostgreSQL port range for FerretDB backends
-const BACKEND_PORT_START = 54320
-const BACKEND_PORT_END = 54400
-
-/**
- * Allocate a port for the PostgreSQL backend
- *
- * KNOWN LIMITATION (TOCTOU): There is a race condition between checking port
- * availability and PostgreSQL actually binding to the port. Another process
- * could claim the port in between. This is acceptable for SpinDB's use case:
- *
- * 1. The backend port range (54320-54400) is unlikely to be used by other apps
- * 2. SpinDB is a local development tool, not a production server
- * 3. If a collision occurs, PostgreSQL will fail to start with a clear error
- * 4. The CLI layer uses startWithRetry() which can re-attempt with a new port
- *
- * A more robust solution would use SO_REUSEPORT or hold the socket until
- * PostgreSQL starts, but this adds complexity for minimal real-world benefit.
- */
-async function allocateBackendPort(): Promise<number> {
-  for (let port = BACKEND_PORT_START; port <= BACKEND_PORT_END; port++) {
-    if (await isPortAvailable(port)) {
-      return port
-    }
-  }
-  throw new Error(
-    `No available ports in range ${BACKEND_PORT_START}-${BACKEND_PORT_END} for PostgreSQL backend`,
-  )
-}
-
-/**
- * Check if a port is available
- */
-function isPortAvailable(port: number): Promise<boolean> {
-  return new Promise((resolve) => {
-    const server = net.createServer()
-    server.once('error', () => resolve(false))
-    server.once('listening', () => {
-      server.close()
-      resolve(true)
-    })
-    server.listen(port, '127.0.0.1')
-  })
-}
-
-/**
- * Wait for a TCP port to accept connections
- */
-function waitForPort(port: number, timeoutMs = 30000): Promise<boolean> {
-  const startTime = Date.now()
-  const checkInterval = 500
-
-  return new Promise((resolve) => {
-    const check = () => {
-      const socket = new net.Socket()
-      socket.setTimeout(1000)
-      socket.once('connect', () => {
-        socket.destroy()
-        resolve(true)
-      })
-      socket.once('error', () => {
-        socket.destroy()
-        if (Date.now() - startTime < timeoutMs) {
-          setTimeout(check, checkInterval)
-        } else {
-          resolve(false)
-        }
-      })
-      socket.once('timeout', () => {
-        socket.destroy()
-        if (Date.now() - startTime < timeoutMs) {
-          setTimeout(check, checkInterval)
-        } else {
-          resolve(false)
-        }
-      })
-      socket.connect(port, '127.0.0.1')
-    }
-    check()
-  })
-}
-
-/**
- * Spawn a process and pipe input to its stdin.
- * Used for `postgres --single` which reads SQL from stdin.
- */
-function spawnWithInput(
-  command: string,
-  args: string[],
-  input: string,
-  options?: { env?: Record<string, string>; timeout?: number },
-): Promise<{ stdout: string; stderr: string }> {
-  return new Promise((resolve, reject) => {
-    let proc: ChildProcess
-    try {
-      proc = spawn(command, args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        env: options?.env ? { ...process.env, ...options.env } : undefined,
-      })
-    } catch (error) {
-      reject(error)
-      return
-    }
-
-    let stdout = ''
-    let stderr = ''
-    let timedOut = false
-
-    const timer = options?.timeout
-      ? setTimeout(() => {
-          timedOut = true
-          proc.kill('SIGKILL')
-          reject(
-            new Error(
-              `Command "${command}" timed out after ${options.timeout}ms`,
-            ),
-          )
-        }, options.timeout)
-      : undefined
-
-    proc.stdout?.on('data', (data: Buffer) => {
-      stdout += data.toString()
-    })
-    proc.stderr?.on('data', (data: Buffer) => {
-      stderr += data.toString()
-    })
-
-    proc.on('close', (code) => {
-      if (timer) clearTimeout(timer)
-      if (timedOut) return
-      if (code === 0) {
-        resolve({ stdout, stderr })
-      } else {
-        reject(
-          new Error(
-            `Command "${command}" failed with code ${code}: ${stderr || stdout}`,
-          ),
-        )
-      }
-    })
-
-    proc.on('error', (err) => {
-      if (timer) clearTimeout(timer)
-      if (timedOut) return
-      reject(err)
-    })
-
-    proc.stdin?.write(input)
-    proc.stdin?.end()
-  })
-}
-
-export class FerretDBEngine extends BaseEngine {
-  name = ENGINE
-  displayName = 'FerretDB'
-  defaultPort = engineDef.defaultPort
-  supportedVersions = SUPPORTED_MAJOR_VERSIONS
-
-  // Get the current platform and architecture
-  getPlatformInfo(): { platform: Platform; arch: Arch } {
-    return platformService.getPlatformInfo()
-  }
-
-  /**
-   * Check if the current platform supports FerretDB
-   * @param version - Optional version to check (v1 supports Windows, v2 does not)
-   */
-  isPlatformSupported(version?: string): boolean {
-    const { platform, arch } = this.getPlatformInfo()
-    return isPlatformSupported(platform, arch, version)
-  }
-
-  /**
-   * Returns available FerretDB versions from the fallback version map.
-   */
-  async fetchAvailableVersions(): Promise<Record<string, string[]>> {
-    const versions: Record<string, string[]> = {}
-
-    for (const [major, full] of Object.entries(FALLBACK_VERSION_MAP)) {
-      if (/^\d+$/.test(major)) {
-        versions[major] = [full]
-      }
-    }
-
-    return versions
-  }
-
-  // Get binary download URL from hostdb
-  getBinaryUrl(version: string, platform: Platform, arch: Arch): string {
-    const backendVersion = isV1(version)
-      ? DEFAULT_V1_POSTGRESQL_VERSION
-      : DEFAULT_DOCUMENTDB_VERSION
-    const urls = getBinaryUrls(version, backendVersion, platform, arch)
-    return urls.ferretdb
-  }
-
-  // Resolves version string to full version
-  resolveFullVersion(version: string): string {
-    if (/^\d+\.\d+\.\d+$/.test(version)) {
-      return version
-    }
-    return FALLBACK_VERSION_MAP[version] || `${version}.0.0`
-  }
-
-  // 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 ferretdbBinaryManager.getFerretDBBinaryPath(fullVersion, p, a)
-  }
-
-  /**
-   * Verify that FerretDB binaries are available and functional
-   */
-  async verifyBinary(binPath: string, version?: string): Promise<boolean> {
-    const { platform: p, arch: a } = this.getPlatformInfo()
-
-    if (version) {
-      const backendVersion = isV1(version)
-        ? DEFAULT_V1_POSTGRESQL_VERSION
-        : DEFAULT_DOCUMENTDB_VERSION
-      return ferretdbBinaryManager.isInstalled(version, p, a, backendVersion)
-    }
-
-    // Fallback: extract version from directory name
-    const dirName = basename(binPath)
-    const match = dirName.match(/^ferretdb-([\d.]+)-/)
-    if (match) {
-      const extractedVersion = match[1]
-      const backendVersion = isV1(extractedVersion)
-        ? DEFAULT_V1_POSTGRESQL_VERSION
-        : DEFAULT_DOCUMENTDB_VERSION
-      return ferretdbBinaryManager.isInstalled(
-        extractedVersion,
-        p,
-        a,
-        backendVersion,
-      )
-    }
-
-    // Last resort: check file existence
-    const ext = platformService.getExecutableExtension()
-    const ferretdbPath = join(binPath, 'bin', `ferretdb${ext}`)
-    return existsSync(ferretdbPath)
-  }
-
-  // Check if a specific FerretDB version is installed
-  async isBinaryInstalled(version: string): Promise<boolean> {
-    const { platform, arch } = this.getPlatformInfo()
-    const backendVersion = isV1(version)
-      ? DEFAULT_V1_POSTGRESQL_VERSION
-      : DEFAULT_DOCUMENTDB_VERSION
-    return ferretdbBinaryManager.isInstalled(
-      version,
-      platform,
-      arch,
-      backendVersion,
-    )
-  }
-
-  /**
-   * Ensure FerretDB binaries are available for a specific version
-   */
-  async ensureBinaries(
-    version: string,
-    onProgress?: ProgressCallback,
-  ): Promise<string> {
-    const { platform, arch } = this.getPlatformInfo()
-    const backendVersion = isV1(version)
-      ? DEFAULT_V1_POSTGRESQL_VERSION
-      : DEFAULT_DOCUMENTDB_VERSION
-
-    // Download binaries (proxy + backend)
-    const { ferretdbPath } = await ferretdbBinaryManager.ensureInstalled(
-      version,
-      platform,
-      arch,
-      onProgress,
-      backendVersion,
-    )
-
-    // Register ferretdb binary in config
-    const ext = platformService.getExecutableExtension()
-    const ferretdbBinary = join(ferretdbPath, 'bin', `ferretdb${ext}`)
-    if (existsSync(ferretdbBinary)) {
-      await configManager.setBinaryPath('ferretdb', ferretdbBinary, 'bundled')
-    }
-
-    return ferretdbPath
-  }
-
-  /**
-   * Get backend binary paths and spawn environment for a container.
-   * Centralizes the v1/v2 branching logic for backend resolution.
-   */
-  private getBackendPaths(
-    version: string,
-    backendVersion: string,
-    platform: Platform,
-    arch: Arch,
-  ): { backendPath: string; pgSpawnEnv: Record<string, string> | undefined } {
-    const fullVersion = normalizeVersion(version)
-    const backendPath = ferretdbBinaryManager.getBackendBinaryPath(
-      fullVersion,
-      backendVersion,
-      platform,
-      arch,
-    )
-
-    const baseSpawnEnv = ferretdbBinaryManager.getBackendSpawnEnv(
-      fullVersion,
-      backendVersion,
-      platform,
-      arch,
-    )
-    const pgSpawnEnv =
-      platform === 'darwin'
-        ? {
-            ...baseSpawnEnv,
-            DYLD_FALLBACK_LIBRARY_PATH: join(backendPath, 'lib'),
-          }
-        : baseSpawnEnv
-
-    return { backendPath, pgSpawnEnv }
-  }
-
-  /**
-   * Initialize a new FerretDB container directory
-   * Creates both the PostgreSQL data directory and FerretDB config
-   */
-  async initDataDir(
-    containerName: string,
-    _version: string,
-    options: Record<string, unknown> = {},
-  ): Promise<string> {
-    const { platform, arch } = this.getPlatformInfo()
-    const version = normalizeVersion(_version)
-    const v1 = isV1(version)
-
-    // Get binary paths - resolve backend based on v1/v2
-    const backendVersion = v1
-      ? (options.backendVersion as string) || DEFAULT_V1_POSTGRESQL_VERSION
-      : (options.backendVersion as string) || DEFAULT_DOCUMENTDB_VERSION
-
-    const { backendPath: documentdbPath, pgSpawnEnv: initSpawnEnv } =
-      this.getBackendPaths(version, backendVersion, platform, arch)
-
-    // Container directory structure
-    const containerDir = paths.getContainerPath(containerName, {
-      engine: ENGINE,
-    })
-    const pgDataDir = join(containerDir, 'pg_data')
-    const logsDir = join(containerDir, 'logs')
-
-    // Create directories
-    await mkdir(containerDir, { recursive: true })
-    await mkdir(logsDir, { recursive: true })
-
-    // Initialize PostgreSQL data directory
-    // Check for PG_VERSION file to determine if already initialized
-    // (directory may exist but be empty if created by containerManager.create)
-    const pgVersionFile = join(pgDataDir, 'PG_VERSION')
-    if (!existsSync(pgVersionFile)) {
-      const ext = platformService.getExecutableExtension()
-      const initdb = join(documentdbPath, 'bin', `initdb${ext}`)
-
-      if (!existsSync(initdb)) {
-        throw new Error(`initdb not found at ${initdb}`)
-      }
-
-      // Homebrew-derived x64 binaries have compiled-in absolute paths for
-      // sharedir, pkglibdir ($libdir), and libdir that don't exist when running
-      // from ~/.spindb/bin/. We fix this by:
-      // 1. Using initdb's -L flag to explicitly set the share directory
-      // 2. Creating symlinks at compiled-in paths for pkglibdir and libdir
-      //    (these are needed by the bootstrap postgres subprocess during initdb)
-      const shareDirBase = join(documentdbPath, 'share')
-      const actualShareDir = existsSync(join(shareDirBase, 'postgres.bki'))
-        ? shareDirBase
-        : existsSync(join(shareDirBase, 'postgresql', 'postgres.bki'))
-          ? join(shareDirBase, 'postgresql')
-          : shareDirBase
-
-      // v2 only: Homebrew-derived DocumentDB binaries need compiled-in path fixups
-      // v1 uses plain PostgreSQL which has correct relative paths
-      if (!v1 && platform === 'darwin') {
-        const pgConfigBin = join(documentdbPath, 'bin', `pg_config${ext}`)
-        if (existsSync(pgConfigBin)) {
-          // Query all relevant compiled-in paths and create symlinks where needed
-          const pathFixups: Array<{
-            flag: string
-            actualDir: string
-            label: string
-          }> = [
-            { flag: '--sharedir', actualDir: actualShareDir, label: 'share' },
-            {
-              flag: '--pkglibdir',
-              actualDir: existsSync(join(documentdbPath, 'lib', 'postgresql'))
-                ? join(documentdbPath, 'lib', 'postgresql')
-                : join(documentdbPath, 'lib'),
-              label: 'pkglib',
-            },
-            {
-              flag: '--libdir',
-              actualDir: join(documentdbPath, 'lib'),
-              label: 'lib',
-            },
-          ]
-
-          // Create symlinks at compiled-in paths so PostgreSQL can find its
-          // libraries. These paths may be in system directories (e.g. /usr/local/),
-          // which require elevated privileges to write to.
-          for (const { flag, actualDir, label } of pathFixups) {
-            try {
-              const { stdout: out } = await execAsync(
-                `"${pgConfigBin}" ${flag}`,
-                { timeout: 5000 },
-              )
-              const compiledDir = out.trim()
-              logDebug(`pg_config ${flag}: ${compiledDir}`)
-              if (compiledDir && !existsSync(compiledDir)) {
-                await mkdir(dirname(compiledDir), { recursive: true })
-                await symlink(actualDir, compiledDir)
-                logDebug(
-                  `Created ${label} symlink: ${compiledDir} -> ${actualDir}`,
-                )
-              }
-            } catch (error) {
-              const e = error as NodeJS.ErrnoException
-              const isPermission =
-                e.code === 'EACCES' ||
-                e.code === 'EPERM' ||
-                (e.message && /permission denied/i.test(e.message))
-              if (isPermission) {
-                logWarning(
-                  `Cannot create ${label} symlink (permission denied). ` +
-                    `This can be caused by macOS SIP or container/sudo limitations when compiled-in paths point to system directories. ` +
-                    `Workaround: use a non-system install path, or run with elevated privileges if available (e.g., sudo spindb engines download ferretdb <version>). ` +
-                    `See https://github.com/robertjbass/spindb#ferretdb for details. ` +
-                    `Target: ${flag} -> ${actualDir}`,
-                )
-              } else {
-                logDebug(`Could not fix compiled ${label} path: ${e.message}`)
-              }
-            }
-          }
-        }
-      } else if (!v1) {
-        logDebug(
-          'Skipping pg_config symlink fixups (not required on this platform)',
-        )
-      }
-
-      // v2 only: Fix hardcoded Homebrew dylib paths in DocumentDB extension libraries
-      // v1 uses plain PostgreSQL which doesn't have DocumentDB extensions
-      if (!v1 && platform === 'darwin') {
-        const dylibMarker = join(documentdbPath, '.dylib_fix_done')
-        if (!existsSync(dylibMarker)) {
-          await this.fixDylibDependencies(documentdbPath)
-          try {
-            await writeFile(dylibMarker, '', { flag: 'wx' })
-          } catch {
-            // Marker may already exist from a parallel init — safe to ignore
-          }
-        }
-      }
-
-      try {
-        await spawnAsync(
-          initdb,
-          [
-            '-D',
-            pgDataDir,
-            '-U',
-            'postgres',
-            '--encoding=UTF8',
-            '--locale=C',
-            '-L',
-            actualShareDir,
-          ],
-          { env: initSpawnEnv, timeout: 60000 },
-        )
-        logDebug(`Initialized PostgreSQL data directory: ${pgDataDir}`)
-      } catch (error) {
-        const err = error as Error
-        throw new Error(`Failed to initialize PostgreSQL: ${err.message}`)
-      }
-
-      // v2 only: Copy the bundled postgresql.conf.sample to ensure shared_preload_libraries is set
-      // This is critical for DocumentDB extension to load properly
-      // v1 uses initdb defaults (no DocumentDB extensions to preload)
-      if (!v1) {
-        const bundledConf = existsSync(
-          join(shareDirBase, 'postgresql.conf.sample'),
-        )
-          ? join(shareDirBase, 'postgresql.conf.sample')
-          : join(shareDirBase, 'postgresql', 'postgresql.conf.sample')
-        const pgConf = join(pgDataDir, 'postgresql.conf')
-
-        if (existsSync(bundledConf)) {
-          try {
-            // Read the bundled config
-            let confContent = await readFile(bundledConf, 'utf8')
-
-            // Update cron.database_name to 'ferretdb' (required for pg_cron to work with DocumentDB)
-            confContent = confContent.replace(
-              /cron\.database_name\s*=\s*'[^']*'/,
-              "cron.database_name = 'ferretdb'",
-            )
-
-            // Write the modified config
-            await writeFile(pgConf, confContent)
-            logDebug(`Copied and configured postgresql.conf to ${pgConf}`)
-          } catch (copyError) {
-            logDebug(
-              `Warning: Could not copy postgresql.conf.sample: ${copyError}`,
-            )
-            // Continue anyway - initdb creates a default config
-          }
-        } else {
-          logDebug(`Bundled postgresql.conf.sample not found at ${bundledConf}`)
-        }
-      }
-    }
-
-    return pgDataDir
-  }
-
-  /**
-   * Start FerretDB (two-process lifecycle)
-   *
-   * 1. Allocate/verify backend port
-   * 2. Start PostgreSQL
-   * 3. Wait for PostgreSQL ready
-   * 4. Create ferretdb database + extension (first start)
-   * 5. Start FerretDB proxy
-   * 6. Verify FerretDB connectivity
-   */
-  async start(
-    container: ContainerConfig,
-    onProgress?: ProgressCallback,
-  ): Promise<{ port: number; connectionString: string }> {
-    const {
-      name,
-      port,
-      version,
-      backendVersion,
-      backendPort: existingBackendPort,
-    } = container
-
-    // Check if already running
-    const alreadyRunning = await processManager.isRunning(name, {
-      engine: ENGINE,
-    })
-    if (alreadyRunning) {
-      return {
-        port,
-        connectionString: this.getConnectionString(container),
-      }
-    }
-
-    const { platform, arch } = this.getPlatformInfo()
-    const fullVersion = normalizeVersion(version)
-    const v1 = isV1(version)
-    const effectiveBackendVersion = v1
-      ? backendVersion || DEFAULT_V1_POSTGRESQL_VERSION
-      : normalizeDocumentDBVersion(backendVersion || DEFAULT_DOCUMENTDB_VERSION)
-
-    // Get binary paths using version-aware helper
-    const ferretdbPath = ferretdbBinaryManager.getFerretDBBinaryPath(
-      fullVersion,
-      platform,
-      arch,
-    )
-    const { backendPath: documentdbPath, pgSpawnEnv } = this.getBackendPaths(
-      version,
-      effectiveBackendVersion,
-      platform,
-      arch,
-    )
-
-    const ext = platformService.getExecutableExtension()
-    const ferretdbBinary = join(ferretdbPath, 'bin', `ferretdb${ext}`)
-    const pgCtl = join(documentdbPath, 'bin', `pg_ctl${ext}`)
-    // v1 backend may be a minimal PostgreSQL install (shared with DocumentDB) that
-    // lacks client tools. Use postgres --single as fallback for database creation.
-    const psqlCandidate = join(documentdbPath, 'bin', `psql${ext}`)
-    const psql = existsSync(psqlCandidate) ? psqlCandidate : null
-    const postgresBinary = join(documentdbPath, 'bin', `postgres${ext}`)
-
-    // Verify binaries exist
-    if (!existsSync(ferretdbBinary)) {
-      throw new Error(
-        `FerretDB binary not found. Run: spindb engines download ferretdb ${version}`,
-      )
-    }
-    if (!existsSync(pgCtl)) {
-      throw new Error(
-        `postgresql-documentdb not found. Run: spindb engines download ferretdb ${version}`,
-      )
-    }
-
-    // Container paths
-    const containerDir = paths.getContainerPath(name, { engine: ENGINE })
-    const pgDataDir = join(containerDir, 'pg_data')
-    const logsDir = join(containerDir, 'logs')
-    const pgLogFile = join(logsDir, 'postgres.log')
-    const ferretPidFile = join(containerDir, 'ferretdb.pid')
-
-    // Allocate backend port
-    const backendPort = existingBackendPort || (await allocateBackendPort())
-
-    // v2 only: Fix hardcoded Homebrew dylib paths (darwin-x64 binaries)
-    // Skip if already completed (marker written by initDataDir or a previous start)
-    // v1 uses plain PostgreSQL which doesn't have DocumentDB extensions
-    if (!v1 && platform === 'darwin') {
-      const dylibMarker = join(documentdbPath, '.dylib_fix_done')
-      if (!existsSync(dylibMarker)) {
-        await this.fixDylibDependencies(documentdbPath)
-        try {
-          await writeFile(dylibMarker, '', { flag: 'wx' })
-        } catch {
-          // Marker may already exist — safe to ignore
-        }
-      }
-    }
-
-    let pgStarted = false
-    let ferretStarted = false
-
-    try {
-      // 1. Start PostgreSQL (skip if already running)
-      onProgress?.({
-        stage: 'starting',
-        message: 'Starting PostgreSQL backend...',
-      })
-
-      // Check if PostgreSQL backend is already running in this data dir
-      let pgAlreadyRunning = false
-      try {
-        await spawnAsync(pgCtl, ['status', '-D', pgDataDir], {
-          env: pgSpawnEnv,
-          timeout: 5000,
-        })
-        // pg_ctl status exits 0 if server is running
-        pgAlreadyRunning = true
-        logDebug('PostgreSQL backend already running, skipping start')
-      } catch {
-        // Exit code != 0 means not running — proceed to start
-      }
-
-      // v1 pre-start: Create ferretdb database using postgres --single mode
-      // when psql is unavailable (minimal PG install may lack client tools).
-      // postgres --single requires exclusive data dir access, so this MUST
-      // happen before pg_ctl start.
-      if (v1 && !psql && !pgAlreadyRunning) {
-        logDebug(
-          'psql not found in backend, using postgres --single to pre-create database',
-        )
-        try {
-          await spawnWithInput(
-            postgresBinary,
-            ['--single', '-D', pgDataDir, 'postgres'],
-            "CREATE DATABASE ferretdb ENCODING 'UTF8';\n",
-            { env: pgSpawnEnv, timeout: 30000 },
-          )
-          logDebug('Pre-created ferretdb database via postgres --single')
-        } catch {
-          // Database may already exist from a previous start — safe to ignore
-          logDebug(
-            'postgres --single CREATE DATABASE failed (may already exist)',
-          )
-        }
-      }
-
-      if (!pgAlreadyRunning) {
-        // Use pg_ctl to start PostgreSQL
-        // On Windows, spawnAsync pipes stdout/stderr which get inherited by the
-        // PostgreSQL background process, preventing the 'close' event from firing
-        // until PG itself exits (causing a 60s timeout even though PG is ready).
-        // Use exec() on Windows (matches process-manager.ts approach) which runs
-        // through the shell and doesn't hold pipes open. On Unix, use -w (wait mode).
-        try {
-          if (isWindows()) {
-            const cmd = `"${pgCtl}" start -D "${pgDataDir}" -l "${pgLogFile}" -o "-p ${backendPort} -h 127.0.0.1"`
-            await execAsync(cmd, {
-              env: { ...process.env, ...pgSpawnEnv },
-              timeout: 30000,
-            })
-          } else {
-            const pgCtlArgs = [
-              'start',
-              '-D',
-              pgDataDir,
-              '-l',
-              pgLogFile,
-              '-o',
-              `-p ${backendPort} -h 127.0.0.1`,
-              '-w',
-            ]
-            await spawnAsync(pgCtl, pgCtlArgs, {
-              env: pgSpawnEnv,
-              timeout: 60000,
-            })
-          }
-        } catch (pgError) {
-          // Read PostgreSQL log for debugging
-          let pgLog = ''
-          try {
-            pgLog = await readFile(pgLogFile, 'utf8')
-          } catch {
-            pgLog = '(no log available)'
-          }
-          throw new Error(
-            `PostgreSQL backend failed to start: ${pgError instanceof Error ? pgError.message : pgError}\n` +
-              `PostgreSQL log:\n${pgLog.slice(-2000)}`, // Last 2KB of log
-          )
-        }
-      }
-
-      pgStarted = true
-      logDebug(`PostgreSQL started on port ${backendPort}`)
-
-      // 2. Wait for PostgreSQL to be ready
-      onProgress?.({ stage: 'starting', message: 'Waiting for PostgreSQL...' })
-      const pgReady = await waitForPort(backendPort, 30000)
-      if (!pgReady) {
-        throw new Error('PostgreSQL failed to start within timeout')
-      }
-
-      // 3. Create ferretdb database and extension (first start)
-      // For v1 without psql, database was already created pre-start via postgres --single
-      if (psql) {
-        onProgress?.({
-          stage: 'starting',
-          message: 'Initializing FerretDB database...',
-        })
-        try {
-          // Create ferretdb database if it doesn't exist
-          await spawnAsync(
-            psql,
-            [
-              '-h',
-              '127.0.0.1',
-              '-p',
-              String(backendPort),
-              '-U',
-              'postgres',
-              '-c',
-              "CREATE DATABASE ferretdb WITH ENCODING 'UTF8';",
-            ],
-            { env: pgSpawnEnv, timeout: 30000 },
-          ).catch(() => {
-            // Ignore error if database already exists (error code 42P04)
-          })
-
-          // v2 only: Create DocumentDB extension
-          // v1 uses plain PostgreSQL without DocumentDB
-          if (!v1) {
-            await spawnAsync(
-              psql,
-              [
-                '-h',
-                '127.0.0.1',
-                '-p',
-                String(backendPort),
-                '-U',
-                'postgres',
-                '-d',
-                'ferretdb',
-                '-c',
-                'CREATE EXTENSION IF NOT EXISTS documentdb CASCADE;',
-              ],
-              { env: pgSpawnEnv, timeout: 30000 },
-            ).catch((error) => {
-              logWarning(`Failed to create documentdb extension: ${error}`)
-              // Continue anyway - extension might already exist
-            })
-          }
-
-          logDebug('FerretDB database initialized')
-        } catch (error) {
-          logDebug(`Database initialization warning: ${error}`)
-          // Continue - might already be initialized
-        }
-      }
-
-      // 4. Start FerretDB proxy
-      onProgress?.({ stage: 'starting', message: 'Starting FerretDB proxy...' })
-
-      // Disable authentication for local development (similar to PostgreSQL trust auth)
-      // FerretDB 2.x has auth enabled by default, but for local dev we disable it
-      // Use a unique debug port to avoid conflicts when running multiple FerretDB containers
-      const FERRETDB_DEBUG_PORT_OFFSET = 10000
-      const FERRETDB_DEBUG_PORT_MAX_ATTEMPTS = 10
-      let debugPort = port + FERRETDB_DEBUG_PORT_OFFSET
-
-      // Probe for an available debug port, incrementing if the computed one is occupied
-      let debugPortFound = false
-      for (
-        let attempt = 0;
-        attempt < FERRETDB_DEBUG_PORT_MAX_ATTEMPTS;
-        attempt++
-      ) {
-        const candidatePort = debugPort + attempt
-        if (await isPortAvailable(candidatePort)) {
-          debugPort = candidatePort
-          debugPortFound = true
-          break
-        }
-        logDebug(`Debug port ${candidatePort} is occupied, trying next...`)
-      }
-
-      if (!debugPortFound) {
-        logWarning(
-          `Could not find available debug port in range ${debugPort}-${debugPort + FERRETDB_DEBUG_PORT_MAX_ATTEMPTS - 1}, using computed port ${port + FERRETDB_DEBUG_PORT_OFFSET} anyway`,
-        )
-        debugPort = port + FERRETDB_DEBUG_PORT_OFFSET
-      }
-
-      logDebug(`Using debug port ${debugPort} for FerretDB HTTP debug handler`)
-
-      // v1 uses plain PostgreSQL without TLS configured, so sslmode=disable is required
-      // v2 uses postgresql-documentdb which handles SSL negotiation internally
-      const pgUrl = isV1(version)
-        ? `postgres://postgres@127.0.0.1:${backendPort}/ferretdb?sslmode=disable`
-        : `postgres://postgres@127.0.0.1:${backendPort}/ferretdb`
-
-      const ferretArgs = [
-        '--listen-addr',
-        `127.0.0.1:${port}`,
-        '--postgresql-url',
-        pgUrl,
-        '--state-dir',
-        containerDir,
-        // v2 requires --no-auth to disable SCRAM authentication
-        // v1 has auth disabled by default (flag doesn't exist)
-        ...(isV1(version) ? [] : ['--no-auth']),
-        '--debug-addr',
-        `127.0.0.1:${debugPort}`,
-      ]
-
-      logDebug(`Starting FerretDB with args: ${ferretArgs.join(' ')}`)
-
-      const spawnOpts: SpawnOptions = {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        detached: true,
-        // Run FerretDB in the container directory so telemetry.json/state.json
-        // are written there instead of polluting the user's cwd
-        cwd: containerDir,
-      }
-
-      const proc = spawn(ferretdbBinary, ferretArgs, spawnOpts)
-
-      // Log output
-      let stderrOutput = ''
-      proc.stdout?.on('data', (data: Buffer) => {
-        logDebug(`ferretdb stdout: ${data.toString()}`)
-      })
-      proc.stderr?.on('data', (data: Buffer) => {
-        stderrOutput += data.toString()
-        logDebug(`ferretdb stderr: ${data.toString()}`)
-      })
-
-      proc.unref()
-
-      // Write PID file
-      if (proc.pid) {
-        await writeFile(ferretPidFile, String(proc.pid))
-        ferretStarted = true
-      }
-
-      // 5. Wait for FerretDB to be ready
-      const ferretReady = await waitForPort(port, 30000)
-      if (!ferretReady) {
-        throw new Error(
-          `FerretDB failed to start within timeout. Stderr: ${stderrOutput}`,
-        )
-      }
-
-      logDebug(`FerretDB started on port ${port}`)
-
-      // Persist the allocated backend port if newly allocated
-      if (!existingBackendPort && backendPort) {
-        await containerManager.updateConfig(name, { backendPort })
-        logDebug(`Persisted backend port ${backendPort} to container config`)
-      }
-
-      return {
-        port,
-        connectionString: this.getConnectionString(container),
-      }
-    } catch (error) {
-      // Rollback: stop any started processes
-      if (ferretStarted) {
-        await this.stopFerretDBProcess(containerDir).catch(() => {})
-      }
-      if (pgStarted) {
-        await this.stopPostgreSQLProcess(pgCtl, pgDataDir, pgSpawnEnv).catch(
-          () => {},
-        )
-      }
-      throw error
-    }
-  }
-
-  /**
-   * Stop FerretDB (reverse order: FerretDB first, then PostgreSQL)
-   */
-  async stop(container: ContainerConfig): Promise<void> {
-    const { name, version, backendVersion } = container
-    const { platform, arch } = this.getPlatformInfo()
-    const v1 = isV1(version)
-
-    const effectiveBackendVersion = v1
-      ? backendVersion || DEFAULT_V1_POSTGRESQL_VERSION
-      : backendVersion || DEFAULT_DOCUMENTDB_VERSION
-
-    const { backendPath: documentdbPath, pgSpawnEnv } = this.getBackendPaths(
-      version,
-      effectiveBackendVersion,
-      platform,
-      arch,
-    )
-
-    const ext = platformService.getExecutableExtension()
-    const pgCtl = join(documentdbPath, 'bin', `pg_ctl${ext}`)
-
-    const containerDir = paths.getContainerPath(name, { engine: ENGINE })
-    const pgDataDir = join(containerDir, 'pg_data')
-
-    logDebug(`Stopping FerretDB container "${name}"`)
-
-    // 1. Stop FerretDB proxy
-    await this.stopFerretDBProcess(containerDir)
-
-    // 2. Stop PostgreSQL
-    if (existsSync(pgCtl)) {
-      await this.stopPostgreSQLProcess(pgCtl, pgDataDir, pgSpawnEnv)
-    }
-
-    // Kill pgweb if running for this container
-    await this.stopPgweb(name)
-
-    logDebug('FerretDB stopped')
-  }
-
-  /**
-   * Fix hardcoded Homebrew dylib paths in extension libraries.
-   *
-   * The x64 darwin build of postgresql-documentdb has extensions whose dylib
-   * load commands reference absolute Homebrew paths (e.g.
-   * /usr/local/opt/mongo-c-driver/lib/libbson2.2.dylib). When these paths
-   * don't exist on the target machine, the extension fails to load.
-   *
-   * This method scans extension dylibs with `otool -L`, finds missing
-   * dependencies, searches our bundle for matching libraries, and creates
-   * symlinks at the expected Homebrew paths.
-   */
-  private async fixDylibDependencies(documentdbPath: string): Promise<void> {
-    const libDir = join(documentdbPath, 'lib')
-    const pkgLibDir = join(libDir, 'postgresql')
-
-    if (!existsSync(pkgLibDir)) return
-
-    // Collect all .dylib files in our bundle's lib/ directory
-    const bundledLibNames = new Set<string>()
-    const bundledLibPaths = new Map<string, string>()
-    try {
-      const libFiles = await readdir(libDir)
-      for (const f of libFiles) {
-        if (f.endsWith('.dylib')) {
-          bundledLibNames.add(f)
-          bundledLibPaths.set(f, join(libDir, f))
-        }
-      }
-    } catch {
-      return
-    }
-
-    // Scan extension dylibs for missing dependencies
-    let extFiles: string[]
-    try {
-      extFiles = (await readdir(pkgLibDir)).filter((f) => f.endsWith('.dylib'))
-    } catch {
-      return
-    }
-
-    for (const extFile of extFiles) {
-      const extPath = join(pkgLibDir, extFile)
-      try {
-        const { stdout } = await execAsync(`otool -L "${extPath}"`, {
-          timeout: 5000,
-        })
-
-        for (const line of stdout.split('\n')) {
-          const match = line.trim().match(/^(\/[^\s]+\.dylib)\s/)
-          if (!match) continue
-          const depPath = match[1]
-
-          // Skip system libs, @-prefixed paths, and paths in our bundle
-          if (depPath.startsWith('/usr/lib/')) continue
-          if (depPath.startsWith('/System/')) continue
-          if (depPath.startsWith('@')) continue
-          if (depPath.includes(documentdbPath)) continue
-
-          if (!existsSync(depPath)) {
-            const depName = basename(depPath)
-
-            // Check if we have this exact library in our bundle
-            if (bundledLibPaths.has(depName)) {
-              try {
-                await mkdir(dirname(depPath), { recursive: true })
-              } catch {
-                logDebug(
-                  `Cannot create directory for dylib dep: ${dirname(depPath)} (skipping)`,
-                )
-                continue
-              }
-              try {
-                await symlink(bundledLibPaths.get(depName)!, depPath)
-                logDebug(
-                  `Fixed dylib dep: ${depPath} -> ${bundledLibPaths.get(depName)}`,
-                )
-              } catch {
-                // Symlink may already exist from a parallel fix
-              }
-            } else {
-              logDebug(
-                `Missing dylib dependency: ${depPath} (not found in bundle)`,
-              )
-            }
-          }
-        }
-      } catch {
-        logDebug(`Could not scan dylib deps for ${extFile}`)
-      }
-    }
-  }
-
-  /**
-   * Stop FerretDB proxy process
-   */
-  private async stopFerretDBProcess(containerDir: string): Promise<void> {
-    const pidFile = join(containerDir, 'ferretdb.pid')
-
-    if (existsSync(pidFile)) {
-      let pid = NaN
-      try {
-        const pidContent = await readFile(pidFile, 'utf8')
-        pid = parseInt(pidContent.trim(), 10)
-      } catch {
-        // PID file unreadable — clean it up below
-      }
-
-      if (!isNaN(pid) && platformService.isProcessRunning(pid)) {
-        logDebug(`Killing FerretDB process ${pid}`)
-
-        // On Windows, taskkill without /F sends WM_CLOSE which console/server
-        // processes ignore, causing an error. Use force kill directly.
-        if (isWindows()) {
-          try {
-            await platformService.terminateProcess(pid, true)
-          } catch {
-            logDebug(`Force kill of FerretDB process ${pid} failed`)
-          }
-        } else {
-          // Unix: try graceful SIGTERM first, then SIGKILL
-          try {
-            await platformService.terminateProcess(pid, false)
-          } catch {
-            // Graceful termination failed — force kill below
-          }
-
-          // Poll until process exits or timeout (10 seconds)
-          const maxWaitMs = 10000
-          const pollIntervalMs = 200
-          const startTime = Date.now()
-
-          while (Date.now() - startTime < maxWaitMs) {
-            if (!platformService.isProcessRunning(pid)) {
-              logDebug(`FerretDB process ${pid} terminated gracefully`)
-              break
-            }
-            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs))
-          }
-
-          // Force kill if still running after timeout
-          if (platformService.isProcessRunning(pid)) {
-            logWarning(`Graceful termination timed out, force killing ${pid}`)
-            try {
-              await platformService.terminateProcess(pid, true)
-            } catch {
-              logDebug(`Force kill of FerretDB process ${pid} failed`)
-            }
-          }
-        }
-
-        // Wait briefly for process to fully exit after force kill
-        const exitWaitMs = isWindows() ? 3000 : 1000
-        const pollMs = 100
-        const exitStart = Date.now()
-        while (Date.now() - exitStart < exitWaitMs) {
-          if (!platformService.isProcessRunning(pid)) break
-          await new Promise((resolve) => setTimeout(resolve, pollMs))
-        }
-      }
-
-      // Always clean up PID file
-      await unlink(pidFile).catch(() => {})
-    }
-  }
-
-  /**
-   * Stop PostgreSQL process
-   */
-  private async stopPostgreSQLProcess(
-    pgCtl: string,
-    pgDataDir: string,
-    spawnEnv?: Record<string, string>,
-  ): Promise<void> {
-    if (isWindows()) {
-      // On Windows, use exec() instead of spawnAsync() to avoid pipe-related
-      // hangs (same issue as pg_ctl start -w). pg_ctl stop -w can block when
-      // stdout/stderr pipes prevent the child process from exiting cleanly.
-      try {
-        await execAsync(`"${pgCtl}" stop -D "${pgDataDir}" -m fast -w`, {
-          timeout: 30000,
-          env: spawnEnv ? { ...process.env, ...spawnEnv } : undefined,
-        })
-        logDebug('PostgreSQL stopped')
-      } catch (error) {
-        logDebug(`pg_ctl stop error: ${error}`)
-        try {
-          await execAsync(`"${pgCtl}" stop -D "${pgDataDir}" -m immediate -w`, {
-            timeout: 15000,
-            env: spawnEnv ? { ...process.env, ...spawnEnv } : undefined,
-          })
-        } catch {
-          logWarning('Failed to stop PostgreSQL gracefully')
-        }
-      }
-    } else {
-      try {
-        await spawnAsync(pgCtl, ['stop', '-D', pgDataDir, '-m', 'fast', '-w'], {
-          env: spawnEnv,
-          timeout: 30000,
-        })
-        logDebug('PostgreSQL stopped')
-      } catch (error) {
-        logDebug(`pg_ctl stop error: ${error}`)
-        try {
-          await spawnAsync(
-            pgCtl,
-            ['stop', '-D', pgDataDir, '-m', 'immediate', '-w'],
-            { env: spawnEnv, timeout: 15000 },
-          )
-        } catch {
-          logWarning('Failed to stop PostgreSQL gracefully')
-        }
-      }
-    }
-  }
-
-  // Get FerretDB server status
-  async status(container: ContainerConfig): Promise<StatusResult> {
-    const { name, port } = container
-    const containerDir = paths.getContainerPath(name, { engine: ENGINE })
-    const pidFile = join(containerDir, 'ferretdb.pid')
-
-    // Check if FerretDB is responding
-    const isOpen = await new Promise<boolean>((resolve) => {
-      const socket = new net.Socket()
-      socket.setTimeout(1000)
-      socket.once('connect', () => {
-        socket.destroy()
-        resolve(true)
-      })
-      socket.once('error', () => {
-        socket.destroy()
-        resolve(false)
-      })
-      socket.once('timeout', () => {
-        socket.destroy()
-        resolve(false)
-      })
-      socket.connect(port, '127.0.0.1')
-    })
-
-    if (isOpen) {
-      return { running: true, message: 'FerretDB is running' }
-    }
-
-    // Check PID file
-    if (existsSync(pidFile)) {
-      try {
-        const content = await readFile(pidFile, 'utf8')
-        const pid = parseInt(content.trim(), 10)
-        if (!isNaN(pid) && pid > 0 && platformService.isProcessRunning(pid)) {
-          return {
-            running: true,
-            message: `FerretDB is running (PID: ${pid})`,
-          }
-        }
-      } catch {
-        // Ignore
-      }
-    }
-
-    return { running: false, message: 'FerretDB 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: Record<string, unknown> = {},
-  ): Promise<RestoreResult> {
-    const { backendPort } = container
-    const database = (options.database as string) || 'ferretdb'
-
-    if (!backendPort) {
-      throw new Error('Backend port not set - start the container first')
-    }
-
-    // Validate database name before restore (defense-in-depth)
-    assertValidDatabaseName(database)
-
-    const result = await restoreBackup(container, backupPath, {
-      database,
-      drop: options.drop !== false,
-    })
-
-    // Restart FerretDB proxy so it picks up the restored data.
-    // pg_restore writes directly to PostgreSQL, but FerretDB's proxy
-    // caches schema/collection metadata in memory and won't see
-    // the restored collections until restarted.
-    const containerDir = paths.getContainerPath(container.name, {
-      engine: ENGINE,
-    })
-    try {
-      await this.stopFerretDBProcess(containerDir)
-      // start() detects PG is already running and only launches the proxy
-      await this.start(container)
-    } catch (error) {
-      const err = error as Error
-      logWarning(
-        `Failed to restart FerretDB proxy after restore: ${err.message}`,
-      )
-      // Retry once — transient issues (port race, slow PG) can resolve on second attempt
-      try {
-        await this.stopFerretDBProcess(containerDir).catch(() => {})
-        await this.start(container)
-      } catch {
-        throw new Error(
-          `Restore succeeded but FerretDB proxy failed to restart. ` +
-            `Data is safely in PostgreSQL. Run 'spindb start ${container.name}' to restart manually. ` +
-            `Original error: ${err.message}`,
-        )
-      }
-    }
-
-    return result
-  }
-
-  // Get connection string (MongoDB-compatible)
-  getConnectionString(container: ContainerConfig, database?: string): string {
-    const { port } = container
-    const db = database || container.database || 'test'
-    // No authentication required - FerretDB runs with --no-auth for local dev
-    return `mongodb://127.0.0.1:${port}/${db}`
-  }
-
-  // Get PostgreSQL backend connection string (for debugging)
-  getBackendConnectionString(container: ContainerConfig): string {
-    const { backendPort } = container
-    if (!backendPort) {
-      throw new Error(
-        'Backend port not available - start the container first to allocate a port',
-      )
-    }
-    return `postgresql://postgres@127.0.0.1:${backendPort}/ferretdb`
-  }
-
-  /**
-   * Get the path to mongosh (uses MongoDB's mongosh)
-   * FerretDB is MongoDB-compatible, so it uses the same shell
-   */
-  override async getMongoshPath(): Promise<string> {
-    const cached = await configManager.getBinaryPath('mongosh')
-    if (cached && existsSync(cached)) return cached
-
-    // Try to find in PATH as fallback
-    const detected = await platformService.findToolPath('mongosh')
-    if (detected) {
-      await configManager.setBinaryPath('mongosh', detected, 'system')
-      return detected
-    }
-
-    throw new Error(
-      'mongosh not found. To connect to FerretDB, install mongosh:\n' +
-        '  Download from: https://www.mongodb.com/try/download/shell\n' +
-        '  Or download MongoDB binaries: spindb engines download mongodb <version>',
-    )
-  }
-
-  // Open mongosh interactive shell
-  async connect(container: ContainerConfig, database?: string): Promise<void> {
-    const { port } = container
-    const db = database || 'test'
-
-    const mongosh = await this.getMongoshPath()
-
-    const spawnOptions: SpawnOptions = {
-      stdio: 'inherit',
-    }
-
-    return new Promise((resolve, reject) => {
-      const proc = spawn(
-        mongosh,
-        ['--host', '127.0.0.1', '--port', String(port), db],
-        spawnOptions,
-      )
-
-      proc.on('error', reject)
-      proc.on('close', () => resolve())
-    })
-  }
-
-  /**
-   * Create a new database
-   * FerretDB/MongoDB creates databases implicitly when you first write to them.
-   * To force immediate creation, we create a temporary collection and drop it.
-   * This leaves the database visible in tools without any marker clutter.
-   */
-  async createDatabase(
-    container: ContainerConfig,
-    database: string,
-  ): Promise<void> {
-    assertValidDatabaseName(database)
-    const { port } = container
-
-    try {
-      const mongosh = await this.getMongoshPath()
-      // Create a temp collection then immediately drop it to force database creation
-      // without leaving any visible marker collections.
-      // Pre-drop in case a previous run was interrupted and left a stale collection.
-      // NOTE: Use db.getCollection() instead of db._spindb_init shorthand because
-      // mongosh doesn't support shorthand notation for collection names starting with underscore.
-      const script =
-        'try { db.getCollection("_spindb_init").drop(); } catch(e) {} db.createCollection("_spindb_init"); db.getCollection("_spindb_init").drop();'
-      const cmd = isWindows()
-        ? `"${mongosh}" --host 127.0.0.1 --port ${port} ${database} --eval "${script.replace(/"/g, '\\"')}"`
-        : `"${mongosh}" --host 127.0.0.1 --port ${port} ${database} --eval '${script}'`
-
-      await execAsync(cmd, { timeout: 10000 })
-      logDebug(`Database "${database}" created via temp collection`)
-    } catch (error) {
-      // Ignore errors - database may already exist or collection cleanup succeeded
-      logDebug(`createDatabase result: ${error}`)
-    }
-  }
-
-  // Drop a database
-  async dropDatabase(
-    container: ContainerConfig,
-    database: string,
-  ): Promise<void> {
-    assertValidDatabaseName(database)
-    const { port } = container
-
-    try {
-      const mongosh = await this.getMongoshPath()
-      const cmd = isWindows()
-        ? `"${mongosh}" --host 127.0.0.1 --port ${port} ${database} --eval "db.dropDatabase()"`
-        : `"${mongosh}" --host 127.0.0.1 --port ${port} ${database} --eval 'db.dropDatabase()'`
-
-      await execAsync(cmd, { timeout: 10000 })
-    } catch (error) {
-      logDebug(`dropDatabase result: ${error}`)
-    }
-  }
-
-  // Get the size of the database in bytes
-  async getDatabaseSize(container: ContainerConfig): Promise<number | null> {
-    const { port, database } = container
-    const db = database || 'test'
-    assertValidDatabaseName(db)
-
-    try {
-      const mongosh = await this.getMongoshPath()
-      const script = 'JSON.stringify(db.stats())'
-      const cmd = isWindows()
-        ? `"${mongosh}" --host 127.0.0.1 --port ${port} ${db} --quiet --eval "${script}"`
-        : `"${mongosh}" --host 127.0.0.1 --port ${port} ${db} --quiet --eval '${script}'`
-
-      const { stdout } = await execAsync(cmd, { timeout: 10000 })
-
-      // Extract JSON from output
-      const firstBrace = stdout.indexOf('{')
-      const lastBrace = stdout.lastIndexOf('}')
-      if (firstBrace !== -1 && lastBrace !== -1 && lastBrace > firstBrace) {
-        const stats = JSON.parse(stdout.substring(firstBrace, lastBrace + 1))
-        const dataSize = Number(stats?.dataSize)
-        return Number.isFinite(dataSize) && dataSize > 0 ? dataSize : null
-      }
-      return null
-    } catch {
-      return null
-    }
-  }
-
-  // Create a dump from a remote database
-  async dumpFromConnectionString(
-    connectionString: string,
-    outputPath: string,
-  ): Promise<DumpResult> {
-    // Use mongodump if available
-    const mongodump = await configManager.getBinaryPath('mongodump')
-    if (!mongodump) {
-      throw new Error(
-        'mongodump not found. Download MongoDB binaries:\n' +
-          '  Run: spindb engines download mongodb <version>',
-      )
-    }
-
-    const args = [
-      '--uri',
-      connectionString,
-      '--archive=' + outputPath,
-      '--gzip',
-    ]
-
-    const spawnOptions: SpawnOptions = {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }
-
-    return new Promise((resolve, reject) => {
-      const proc = spawn(mongodump, args, spawnOptions)
-
-      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) {
-          resolve({
-            filePath: outputPath,
-            stdout,
-            stderr,
-            code,
-          })
-        } else {
-          reject(new Error(stderr || `mongodump exited with code ${code}`))
-        }
-      })
-    })
-  }
-
-  // Create a backup
-  async backup(
-    container: ContainerConfig,
-    outputPath: string,
-    options: BackupOptions,
-  ): Promise<BackupResult> {
-    return createBackup(container, outputPath, options)
-  }
-
-  // Run a JavaScript file or inline script against the database
-  async runScript(
-    container: ContainerConfig,
-    options: { file?: string; sql?: string; database?: string },
-  ): Promise<void> {
-    const { port } = container
-    const db = options.database || container.database || 'test'
-
-    const mongosh = await this.getMongoshPath()
-
-    if (options.file) {
-      const spawnOptions: SpawnOptions = {
-        stdio: 'inherit',
-      }
-
-      return new Promise((resolve, reject) => {
-        const proc = spawn(
-          mongosh,
-          [
-            '--host',
-            '127.0.0.1',
-            '--port',
-            String(port),
-            db,
-            '--file',
-            options.file!,
-          ],
-          spawnOptions,
-        )
-
-        proc.on('error', reject)
-        proc.on('close', (code) => {
-          if (code === 0) {
-            resolve()
-          } else {
-            reject(new Error(`mongosh exited with code ${code}`))
-          }
-        })
-      })
-    } else if (options.sql) {
-      // sql field is actually JS for MongoDB-compatible databases
-      const script = options.sql
-
-      return new Promise((resolve, reject) => {
-        const proc = spawn(
-          mongosh,
-          ['--host', '127.0.0.1', '--port', String(port), db, '--eval', script],
-          { stdio: ['pipe', 'pipe', 'pipe'] },
-        )
-
-        let stdout = ''
-        let stderr = ''
-
-        proc.stdout?.on('data', (data: Buffer) => {
-          stdout += data.toString()
-        })
-        proc.stderr?.on('data', (data: Buffer) => {
-          stderr += data.toString()
-        })
-
-        // 60 second timeout
-        const timeout = setTimeout(() => {
-          proc.kill('SIGTERM')
-          reject(new Error('mongosh timed out after 60 seconds'))
-        }, 60000)
-
-        proc.on('error', (err) => {
-          clearTimeout(timeout)
-          reject(err)
-        })
-
-        proc.on('close', (code) => {
-          clearTimeout(timeout)
-          if (stdout) process.stdout.write(stdout)
-          if (stderr) process.stderr.write(stderr)
-          if (code === 0) {
-            resolve()
-          } else {
-            reject(new Error(`mongosh exited with code ${code}`))
-          }
-        })
-      })
-    } else {
-      throw new Error('Either file or sql option must be provided')
-    }
-  }
-
-  /**
-   * Execute a query and return structured results
-   * FerretDB uses MongoDB JavaScript syntax
-   *
-   * Examples:
-   *   db.users.find({active: true})
-   *   db.orders.countDocuments()
-   */
-  async executeQuery(
-    container: ContainerConfig,
-    query: string,
-    options?: QueryOptions,
-  ): Promise<QueryResult> {
-    const { port } = container
-    const db = options?.database || container.database || 'test'
-
-    const mongosh = await this.getMongoshPath()
-
-    // Normalize query - only prepend "db." for collection operations
-    // Collection operations match pattern: identifier.method(...) e.g., "users.find({})"
-    // Non-collection queries (show dbs, arbitrary JS) are rejected with clear error
-    let normalizedQuery = query.trim()
-    if (!normalizedQuery.startsWith('db.')) {
-      // Check if it looks like a collection operation: identifier.method(
-      const collectionOpPattern =
-        /^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*\s*\(/
-      if (collectionOpPattern.test(normalizedQuery)) {
-        normalizedQuery = `db.${normalizedQuery}`
-      } else {
-        throw new Error(
-          'Invalid query format. Expected a collection operation like "users.find({})" or "db.users.find({})"\n' +
-            'Shell commands like "show dbs" and "use dbname" are not supported in executeQuery.',
-        )
-      }
-    }
-
-    // Wrap query in async IIFE to properly await cursor.toArray()
-    // This prevents JSON.stringify from serializing a Promise
-    const script = `(async () => { const res = ${normalizedQuery}; return JSON.stringify(res.toArray ? await res.toArray() : await Promise.resolve(res)); })()`
-
-    return new Promise((resolve, reject) => {
-      const args = [
-        '--host',
-        '127.0.0.1',
-        '--port',
-        String(port),
-        db,
-        '--quiet',
-        '--eval',
-        script,
-      ]
-
-      const proc = spawn(mongosh, args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-      })
-
-      let stdout = ''
-      let stderr = ''
-
-      proc.stdout?.on('data', (data: Buffer) => {
-        stdout += data.toString()
-      })
-      proc.stderr?.on('data', (data: Buffer) => {
-        stderr += data.toString()
-      })
-
-      const timeout = setTimeout(() => {
-        proc.kill('SIGTERM')
-        reject(new Error('Query timed out after 60 seconds'))
-      }, 60000)
-
-      proc.on('error', (err) => {
-        clearTimeout(timeout)
-        reject(err)
-      })
-
-      proc.on('close', (code) => {
-        clearTimeout(timeout)
-        if (code !== 0) {
-          reject(new Error(stderr || `mongosh exited with code ${code}`))
-          return
-        }
-
-        try {
-          // Extract JSON from output (mongosh may output extra info)
-          const jsonStart = stdout.indexOf('[')
-          const jsonEnd = stdout.lastIndexOf(']')
-
-          if (jsonStart !== -1 && jsonEnd !== -1 && jsonEnd > jsonStart) {
-            const jsonStr = stdout.substring(jsonStart, jsonEnd + 1)
-            resolve(parseMongoDBResult(jsonStr))
-          } else {
-            // Try parsing as single object or scalar
-            const objStart = stdout.indexOf('{')
-            const objEnd = stdout.lastIndexOf('}')
-            if (objStart !== -1 && objEnd !== -1 && objEnd > objStart) {
-              const jsonStr = stdout.substring(objStart, objEnd + 1)
-              resolve(parseMongoDBResult(jsonStr))
-            } else {
-              // Return as scalar result
-              resolve({
-                columns: ['result'],
-                rows: [{ result: stdout.trim() }],
-                rowCount: 1,
-              })
-            }
-          }
-        } catch (error) {
-          reject(
-            new Error(
-              `Failed to parse query result: ${error instanceof Error ? error.message : error}`,
-            ),
-          )
-        }
-      })
-    })
-  }
-
-  /**
-   * List all user databases, excluding system databases (admin, config, local).
-   * FerretDB uses MongoDB protocol, so same approach as MongoDB.
-   */
-  async listDatabases(container: ContainerConfig): Promise<string[]> {
-    const { port } = container
-    const mongosh = await this.getMongoshPath()
-
-    return new Promise((resolve, reject) => {
-      // Use JSON output for reliable parsing
-      const script = `JSON.stringify(db.adminCommand({listDatabases: 1}).databases.map(d => d.name))`
-      const args = [
-        '--quiet',
-        '--host',
-        '127.0.0.1',
-        '--port',
-        String(port),
-        '--eval',
-        script,
-      ]
-
-      const proc = spawn(mongosh, 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 || `mongosh exited with code ${code}`))
-          return
-        }
-
-        try {
-          const allDatabases = JSON.parse(stdout.trim()) as string[]
-          const systemDatabases = ['admin', 'config', 'local']
-          const databases = allDatabases.filter(
-            (db) => !systemDatabases.includes(db),
-          )
-          resolve(databases)
-        } catch (error) {
-          reject(new Error(`Failed to parse database list: ${error}`))
-        }
-      })
-    })
-  }
-
-  async createUser(
-    container: ContainerConfig,
-    options: CreateUserOptions,
-  ): Promise<UserCredentials> {
-    const { username, password, database } = options
-    assertValidUsername(username)
-    const { port } = container
-    const db = database ?? container.database ?? 'admin'
-    assertValidDatabaseName(db)
-    const mongosh = await this.getMongoshPath()
-
-    // Same as MongoDB - auth disabled with --no-auth but user is still created
-    // Use JSON.stringify for password to safely escape all special characters in JS context
-    // Pass script via stdin to avoid exposing passwords in process listings
-    const jsonPwd = JSON.stringify(password)
-    const script = `db.getSiblingDB('${db}').createUser({user:'${username}',pwd:${jsonPwd},roles:[{role:'readWrite',db:'${db}'}]})`
-
-    const mongoshArgs = ['--host', '127.0.0.1', '--port', String(port), 'admin']
-
-    const runMongoshViaStdin = (js: string): Promise<void> =>
-      new Promise((resolve, reject) => {
-        const proc = spawn(mongosh, mongoshArgs, {
-          stdio: ['pipe', 'pipe', 'pipe'],
-        })
-
-        let stderr = ''
-        proc.stderr?.on('data', (data: Buffer) => {
-          stderr += data.toString()
-        })
-
-        const timeout = setTimeout(() => {
-          proc.kill('SIGTERM')
-          reject(new Error('mongosh timed out after 10 seconds'))
-        }, 10000)
-
-        proc.on('error', (err) => {
-          clearTimeout(timeout)
-          reject(err)
-        })
-
-        proc.on('close', (code) => {
-          clearTimeout(timeout)
-          if (code === 0) resolve()
-          else reject(new Error(stderr || `mongosh exited with code ${code}`))
-        })
-
-        proc.stdin?.write(js)
-        proc.stdin?.end()
-      })
-
-    try {
-      await runMongoshViaStdin(script)
-    } catch (error) {
-      const err = error as Error
-      if (
-        err.message.includes('51003') ||
-        err.message.includes('already exists')
-      ) {
-        // User exists — update password instead
-        const updateScript = `db.getSiblingDB('${db}').updateUser('${username}',{pwd:${jsonPwd}})`
-        await runMongoshViaStdin(updateScript)
-      } else {
-        throw error
-      }
-    }
-
-    const connectionString = `mongodb://${encodeURIComponent(username)}:${encodeURIComponent(password)}@127.0.0.1:${port}/${db}`
-
-    return {
-      username,
-      password,
-      connectionString,
-      engine: container.engine,
-      container: container.name,
-      database: db,
-    }
-  }
-}
-
-export const ferretdbEngine = new FerretDBEngine()