spindb 0.37.2 → 0.38.0

package/dist/engines/ferretdb/index.js

@@ -0,0 +1,1517 @@
+/**
+ * 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, } 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.js';
+import { paths } from '../../config/paths.js';
+import { getEngineDefaults } from '../../config/defaults.js';
+import { platformService, isWindows } from '../../core/platform-service.js';
+import { configManager } from '../../core/config-manager.js';
+import { containerManager } from '../../core/container-manager.js';
+import { logDebug, logWarning, assertValidDatabaseName, assertValidUsername, } from '../../core/error-handler.js';
+import { processManager } from '../../core/process-manager.js';
+import { spawnAsync } from '../../core/spawn-utils.js';
+import { ferretdbBinaryManager } from './binary-manager.js';
+import { SUPPORTED_MAJOR_VERSIONS, FALLBACK_VERSION_MAP, DEFAULT_DOCUMENTDB_VERSION, DEFAULT_V1_POSTGRESQL_VERSION, normalizeVersion, normalizeDocumentDBVersion, isV1, } from './version-maps.js';
+import { getBinaryUrls, isPlatformSupported } from './binary-urls.js';
+import { detectBackupFormat as detectBackupFormatImpl, restoreBackup, } from './restore.js';
+import { createBackup } from './backup.js';
+import { parseMongoDBResult } from '../../core/query-parser.js';
+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() {
+    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) {
+    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, timeoutMs = 30000) {
+    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, args, input, options) {
+    return new Promise((resolve, reject) => {
+        let proc;
+        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) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on('data', (data) => {
+            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() {
+        return platformService.getPlatformInfo();
+    }
+    /**
+     * Check if the current platform supports FerretDB
+     * @param version - Optional version to check (v1 supports Windows, v2 does not)
+     */
+    isPlatformSupported(version) {
+        const { platform, arch } = this.getPlatformInfo();
+        return isPlatformSupported(platform, arch, version);
+    }
+    /**
+     * Returns available FerretDB versions from the fallback version map.
+     */
+    async fetchAvailableVersions() {
+        const versions = {};
+        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, platform, arch) {
+        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) {
+        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) {
+        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, version) {
+        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) {
+        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, onProgress) {
+        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.
+     */
+    getBackendPaths(version, backendVersion, platform, arch) {
+        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, _version, options = {}) {
+        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 || DEFAULT_V1_POSTGRESQL_VERSION
+            : options.backendVersion || 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 = [
+                        { 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;
+                            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;
+                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, onProgress) {
+        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)}`);
+                }
+            }
+            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 = {
+                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) => {
+                logDebug(`ferretdb stdout: ${data.toString()}`);
+            });
+            proc.stderr?.on('data', (data) => {
+                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) {
+        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.
+     */
+    async fixDylibDependencies(documentdbPath) {
+        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();
+        const bundledLibPaths = new Map();
+        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;
+        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
+     */
+    async stopFerretDBProcess(containerDir) {
+        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
+     */
+    async stopPostgreSQLProcess(pgCtl, pgDataDir, spawnEnv) {
+        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) {
+        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((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) {
+        return detectBackupFormatImpl(filePath);
+    }
+    // Restore a backup
+    async restore(container, backupPath, options = {}) {
+        const { backendPort } = container;
+        const database = options.database || '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;
+            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, database) {
+        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) {
+        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
+     */
+    async getMongoshPath() {
+        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, database) {
+        const { port } = container;
+        const db = database || 'test';
+        const mongosh = await this.getMongoshPath();
+        const 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, database) {
+        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, database) {
+        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) {
+        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, outputPath) {
+        // 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 = {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        };
+        return new Promise((resolve, reject) => {
+            const proc = spawn(mongodump, args, spawnOptions);
+            let stdout = '';
+            let stderr = '';
+            proc.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on('data', (data) => {
+                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, outputPath, options) {
+        return createBackup(container, outputPath, options);
+    }
+    // Run a JavaScript file or inline script against the database
+    async runScript(container, options) {
+        const { port } = container;
+        const db = options.database || container.database || 'test';
+        const mongosh = await this.getMongoshPath();
+        if (options.file) {
+            const 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) => {
+                    stdout += data.toString();
+                });
+                proc.stderr?.on('data', (data) => {
+                    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, query, options) {
+        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) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on('data', (data) => {
+                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) {
+        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) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on('data', (data) => {
+                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());
+                    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, options) {
+        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) => new Promise((resolve, reject) => {
+            const proc = spawn(mongosh, mongoshArgs, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stderr = '';
+            proc.stderr?.on('data', (data) => {
+                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;
+            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();
+//# sourceMappingURL=index.js.map