spindb 0.37.2 → 0.38.0

package/dist/engines/mysql/index.js

@@ -0,0 +1,1066 @@
+/**
+ * MySQL Engine implementation
+ * Manages MySQL database containers using pre-built binaries from hostdb
+ */
+import { spawn, exec } from 'child_process';
+import { promisify } from 'util';
+import { existsSync, createReadStream } from 'fs';
+import { mkdir, writeFile, readFile, unlink, rm } from 'fs/promises';
+import { join } from 'path';
+import { BaseEngine } from '../base-engine.js';
+import { paths } from '../../config/paths.js';
+import { getEngineDefaults } from '../../config/defaults.js';
+import { platformService, isWindows, getWindowsSpawnOptions, } from '../../core/platform-service.js';
+import { configManager } from '../../core/config-manager.js';
+import { logDebug, logWarning, ErrorCodes, SpinDBError, assertValidDatabaseName, assertValidUsername, } from '../../core/error-handler.js';
+import { mysqlBinaryManager } from './binary-manager.js';
+import { getBinaryUrl } from './binary-urls.js';
+import { fetchAvailableVersions, getLatestVersion } from './hostdb-releases.js';
+import { SUPPORTED_MAJOR_VERSIONS, FALLBACK_VERSION_MAP } from './version-maps.js';
+import { detectBackupFormat as detectBackupFormatImpl, restoreBackup, parseConnectionString, } from './restore.js';
+import { createBackup } from './backup.js';
+import { Platform, } from '../../types/index.js';
+import { parseTSVToQueryResult } from '../../core/query-parser.js';
+const execAsync = promisify(exec);
+const ENGINE = 'mysql';
+const engineDef = getEngineDefaults(ENGINE);
+/**
+ * Build a Windows-safe mysql command string for either a file or inline SQL.
+ * This is exported for unit testing.
+ */
+export function buildWindowsMysqlCommand(mysqlPath, port, user, db, options) {
+    if (!options.file && !options.sql) {
+        throw new Error('Either file or sql option must be provided');
+    }
+    let cmd = `"${mysqlPath}" -h 127.0.0.1 -P ${port} -u ${user} ${db}`;
+    if (options.file) {
+        // Redirection requires shell, so use < operator
+        cmd += ` < "${options.file}"`;
+    }
+    else if (options.sql) {
+        const escaped = options.sql.replace(/"/g, '\\"');
+        cmd += ` -e "${escaped}"`;
+    }
+    return cmd;
+}
+/**
+ * Build a platform-safe mysql command string with SQL inline.
+ * On Unix, uses single quotes to prevent shell interpretation of backticks.
+ * On Windows, uses double quotes (backticks are literal in cmd.exe).
+ * This is exported for unit testing.
+ */
+export function buildMysqlInlineCommand(mysqlPath, port, user, sql, options = {}) {
+    const dbArg = options.database ? ` ${options.database}` : '';
+    if (isWindows()) {
+        // Windows: use double quotes, escape inner double quotes
+        const escaped = sql.replace(/"/g, '\\"');
+        return `"${mysqlPath}" -h 127.0.0.1 -P ${port} -u ${user}${dbArg} -e "${escaped}"`;
+    }
+    else {
+        // Unix: use single quotes to prevent backtick interpretation
+        // Escape any single quotes in the SQL by ending the string, adding escaped quote, starting new string
+        const escaped = sql.replace(/'/g, "'\\''");
+        return `"${mysqlPath}" -h 127.0.0.1 -P ${port} -u ${user}${dbArg} -e '${escaped}'`;
+    }
+}
+export class MySQLEngine extends BaseEngine {
+    name = ENGINE;
+    displayName = 'MySQL';
+    defaultPort = engineDef.defaultPort;
+    supportedVersions = SUPPORTED_MAJOR_VERSIONS;
+    async fetchAvailableVersions() {
+        return fetchAvailableVersions();
+    }
+    getPlatformInfo() {
+        const info = platformService.getPlatformInfo();
+        return {
+            platform: info.platform,
+            arch: info.arch,
+        };
+    }
+    resolveFullVersion(version) {
+        // Check if already a full version (has at least two dots)
+        if (/^\d+\.\d+\.\d+/.test(version)) {
+            return version;
+        }
+        // It's a major version, resolve using fallback map
+        const resolved = FALLBACK_VERSION_MAP[version];
+        if (!resolved) {
+            const availableVersions = Object.keys(FALLBACK_VERSION_MAP).join(', ');
+            logWarning(`Unknown MySQL major version "${version}". Available versions: ${availableVersions}. ` +
+                `Falling back to ${version}.0.0 which may not exist.`);
+            return `${version}.0.0`;
+        }
+        return resolved;
+    }
+    async resolveFullVersionAsync(version) {
+        if (/^\d+\.\d+\.\d+/.test(version)) {
+            return version;
+        }
+        return getLatestVersion(version);
+    }
+    getBinaryPath(version) {
+        const fullVersion = this.resolveFullVersion(version);
+        const { platform: p, arch: a } = this.getPlatformInfo();
+        return paths.getBinaryPath({
+            engine: 'mysql',
+            version: fullVersion,
+            platform: p,
+            arch: a,
+        });
+    }
+    getBinaryUrl(version, plat, arc) {
+        return getBinaryUrl(version, plat, arc);
+    }
+    /**
+     * Verify MySQL binaries are installed and working.
+     *
+     * **Prefer passing `version` explicitly** - the fallback path extraction is fragile.
+     *
+     * When `version` is provided, verification uses it directly. Otherwise, the method
+     * attempts to extract a semver-like pattern (`\d+\.\d+\.\d+`) from the basename of
+     * `binPath` (e.g., "mysql-8.0.40-darwin-arm64" → "8.0.40"). This fallback can fail
+     * if the path doesn't follow the expected naming convention, resulting in false negatives.
+     *
+     * Platform and architecture are derived internally via `getPlatformInfo()`.
+     * Verification is delegated to `mysqlBinaryManager.verify(version, platform, arch)`.
+     *
+     * @param binPath - Path to the binary directory (used for fallback version extraction)
+     * @param version - Explicit version string (e.g., "8.0.40", "9.5.0"). Always pass this
+     *   when available to avoid relying on path-based extraction.
+     * @returns `true` if binaries are verified, `false` if verification fails or version
+     *   cannot be determined
+     *
+     * @example
+     * // Preferred: pass version explicitly
+     * await engine.verifyBinary('/path/to/mysql-8.0.40-darwin-arm64', '8.0.40')
+     *
+     * // Fallback: version extracted from path (less reliable)
+     * await engine.verifyBinary('/path/to/mysql-8.0.40-darwin-arm64')
+     */
+    async verifyBinary(binPath, version) {
+        const { platform: p, arch: a } = this.getPlatformInfo();
+        // Use explicit version if provided
+        if (version) {
+            return mysqlBinaryManager.verify(version, p, a);
+        }
+        // Fallback: extract version from path (less reliable)
+        // Matches patterns like mysql-8.0.40-darwin-arm64 or mysql-9.0.0-linux-x64
+        const basename = binPath.split('/').pop() || binPath.split('\\').pop() || '';
+        const versionMatch = basename.match(/\b(\d+\.\d+\.\d+)\b/);
+        if (!versionMatch) {
+            logDebug(`Could not extract version from binary path: ${binPath}`);
+            return false;
+        }
+        logDebug(`Extracted version ${versionMatch[1]} from path (prefer explicit version)`);
+        return mysqlBinaryManager.verify(versionMatch[1], p, a);
+    }
+    async ensureBinaries(version, onProgress) {
+        const { platform: p, arch: a } = this.getPlatformInfo();
+        const binPath = await mysqlBinaryManager.ensureInstalled(version, p, a, onProgress);
+        // Register all MySQL binaries from downloaded package
+        const ext = platformService.getExecutableExtension();
+        const tools = ['mysqld', 'mysqladmin', 'mysql', 'mysqldump'];
+        for (const tool of tools) {
+            const toolPath = join(binPath, 'bin', `${tool}${ext}`);
+            if (existsSync(toolPath)) {
+                await configManager.setBinaryPath(tool, toolPath, 'bundled');
+            }
+        }
+        return binPath;
+    }
+    async isBinaryInstalled(version) {
+        const { platform: p, arch: a } = this.getPlatformInfo();
+        return mysqlBinaryManager.isInstalled(version, p, a);
+    }
+    async initDataDir(containerName, version, _options = {}) {
+        const binPath = this.getBinaryPath(version);
+        const ext = platformService.getExecutableExtension();
+        const dataDir = paths.getContainerDataPath(containerName, {
+            engine: ENGINE,
+        });
+        let createdDataDir = false;
+        if (!existsSync(dataDir)) {
+            await mkdir(dataDir, { recursive: true });
+            createdDataDir = true;
+        }
+        const cleanupOnFailure = async () => {
+            if (createdDataDir) {
+                try {
+                    await rm(dataDir, { recursive: true, force: true });
+                    logDebug(`Cleaned up data directory after init failure: ${dataDir}`);
+                }
+                catch (cleanupErr) {
+                    logDebug(`Failed to clean up data directory: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`);
+                }
+            }
+        };
+        // MySQL uses mysqld --initialize-insecure
+        const mysqld = join(binPath, 'bin', `mysqld${ext}`);
+        if (!existsSync(mysqld)) {
+            await cleanupOnFailure();
+            throw new Error(`MySQL server binary not found in ${binPath}/bin/.\n` +
+                'Re-download the MySQL binaries: spindb engines download mysql');
+        }
+        // MySQL initialization
+        // --initialize-insecure creates root user without password (for local dev)
+        const logFile = paths.getContainerLogPath(containerName, { engine: ENGINE });
+        if (isWindows()) {
+            // On Windows, use exec with properly quoted command
+            const cmd = `"${mysqld}" --initialize-insecure --datadir="${dataDir}" --log-error="${logFile}"`;
+            return new Promise((resolve, reject) => {
+                exec(cmd, { timeout: 120000 }, async (error, stdout, stderr) => {
+                    if (error) {
+                        await cleanupOnFailure();
+                        reject(new Error(`MySQL initialization failed with code ${error.code}: ${stderr || stdout || error.message}`));
+                    }
+                    else {
+                        resolve(dataDir);
+                    }
+                });
+            });
+        }
+        // Unix path - use spawn without shell
+        // --user: Required for non-root, but when running as root we can skip it to avoid
+        //         needing a dedicated 'mysql' user to exist on the system
+        const isRunningAsRoot = process.getuid?.() === 0;
+        const args = [
+            '--initialize-insecure',
+            `--datadir=${dataDir}`,
+            `--basedir=${binPath}`,
+            `--log-error=${logFile}`,
+        ];
+        // Only add --user when not running as root
+        // When running as root, mysqld --initialize-insecure works without specifying a user
+        if (!isRunningAsRoot && process.env.USER) {
+            args.push(`--user=${process.env.USER}`);
+        }
+        // Timeout for initialization (same as Windows path)
+        const INIT_TIMEOUT_MS = 120000;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeoutId = null;
+            const proc = spawn(mysqld, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            // Set up timeout
+            timeoutId = setTimeout(async () => {
+                if (settled)
+                    return;
+                settled = true;
+                // Kill the process
+                try {
+                    proc.kill('SIGKILL');
+                }
+                catch {
+                    // Ignore errors if process already exited
+                }
+                await cleanupOnFailure();
+                reject(new Error(`MySQL initialization timed out after ${INIT_TIMEOUT_MS / 1000}s. Check logs at: ${logFile}`));
+            }, INIT_TIMEOUT_MS);
+            proc.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('close', async (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                if (code === 0) {
+                    resolve(dataDir);
+                }
+                else {
+                    await cleanupOnFailure();
+                    reject(new Error(`MySQL initialization failed with code ${code}: ${stderr || stdout}`));
+                }
+            });
+            proc.on('error', async (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                    timeoutId = null;
+                }
+                await cleanupOnFailure();
+                reject(err);
+            });
+        });
+    }
+    async start(container, onProgress) {
+        const { name, port, version } = container;
+        const alreadyRunning = await this.isRunning(name);
+        if (alreadyRunning) {
+            return {
+                port,
+                connectionString: this.getConnectionString(container),
+            };
+        }
+        const binPath = this.getBinaryPath(version);
+        const ext = platformService.getExecutableExtension();
+        const mysqld = join(binPath, 'bin', `mysqld${ext}`);
+        if (!existsSync(mysqld)) {
+            throw new Error(`MySQL server binary not found in ${binPath}/bin/.\n` +
+                'Re-download the MySQL binaries: spindb engines download mysql');
+        }
+        const dataDir = paths.getContainerDataPath(name, { engine: ENGINE });
+        const logFile = paths.getContainerLogPath(name, { engine: ENGINE });
+        const pidFile = paths.getContainerPidPath(name, { engine: ENGINE });
+        const { platform } = platformService.getPlatformInfo();
+        onProgress?.({ stage: 'starting', message: 'Starting MySQL...' });
+        const args = [
+            `--datadir=${dataDir}`,
+            `--port=${port}`,
+            `--pid-file=${pidFile}`,
+            `--log-error=${logFile}`,
+            '--bind-address=127.0.0.1',
+            `--max-connections=${engineDef.maxConnections}`,
+        ];
+        if (platform !== Platform.Win32) {
+            const socketFile = join(paths.getContainerPath(name, { engine: ENGINE }), 'mysql.sock');
+            args.push(`--socket=${socketFile}`);
+        }
+        let proc = null;
+        if (isWindows()) {
+            proc = spawn(mysqld, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                detached: true,
+                windowsHide: true,
+            });
+            proc.stdout?.on('data', (data) => {
+                logDebug(`mysqld stdout: ${data.toString()}`);
+            });
+            proc.stderr?.on('data', (data) => {
+                logDebug(`mysqld stderr: ${data.toString()}`);
+            });
+            proc.unref();
+        }
+        else {
+            proc = spawn(mysqld, args, {
+                stdio: ['ignore', 'ignore', 'ignore'],
+                detached: true,
+            });
+            proc.unref();
+        }
+        return new Promise((resolve, reject) => {
+            // Track whether we've already settled the promise to avoid race conditions
+            let settled = false;
+            const errorHandler = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (proc) {
+                    proc.removeListener('error', errorHandler);
+                }
+                reject(err);
+            };
+            if (proc) {
+                proc.on('error', errorHandler);
+            }
+            setTimeout(async () => {
+                if (proc && proc.pid) {
+                    try {
+                        await writeFile(pidFile, String(proc.pid));
+                    }
+                    catch (error) {
+                        logDebug(`Could not write PID file: ${error}`);
+                    }
+                }
+                // Wait for MySQL to be ready
+                let attempts = 0;
+                const maxAttempts = 60;
+                const checkInterval = 500;
+                const checkReady = async () => {
+                    if (settled)
+                        return;
+                    attempts++;
+                    try {
+                        const mysqladmin = await this.getMysqladminPath();
+                        await execAsync(`"${mysqladmin}" -h 127.0.0.1 -P ${port} -u root ping`);
+                        if (settled)
+                            return;
+                        settled = true;
+                        if (proc) {
+                            proc.removeListener('error', errorHandler);
+                        }
+                        resolve({
+                            port,
+                            connectionString: this.getConnectionString(container),
+                        });
+                    }
+                    catch {
+                        if (settled)
+                            return;
+                        if (attempts < maxAttempts) {
+                            setTimeout(checkReady, checkInterval);
+                        }
+                        else {
+                            if (settled)
+                                return;
+                            settled = true;
+                            if (proc) {
+                                proc.removeListener('error', errorHandler);
+                            }
+                            reject(new Error('MySQL failed to start within timeout'));
+                        }
+                    }
+                };
+                checkReady();
+            }, 1000);
+        });
+    }
+    async isRunning(containerName) {
+        const pidFile = paths.getContainerPidPath(containerName, { engine: ENGINE });
+        if (!existsSync(pidFile)) {
+            return false;
+        }
+        try {
+            const pid = parseInt(await readFile(pidFile, 'utf8'), 10);
+            return platformService.isProcessRunning(pid);
+        }
+        catch {
+            return false;
+        }
+    }
+    async stop(container) {
+        const { name, port } = container;
+        const pidFile = paths.getContainerPidPath(name, { engine: ENGINE });
+        logDebug(`Stopping MySQL container "${name}" on port ${port}`);
+        const pid = await this.getValidatedPid(pidFile);
+        if (pid === null) {
+            logDebug('No valid PID, checking if MySQL is responding on port');
+            try {
+                const mysqladmin = await this.getMysqladminPath();
+                await execAsync(`"${mysqladmin}" -h 127.0.0.1 -P ${port} -u root ping`, { timeout: 2000 });
+                logWarning(`MySQL responding on port ${port} but no valid PID file`);
+                await this.gracefulShutdown(port);
+            }
+            catch {
+                logDebug('MySQL not responding, nothing to stop');
+            }
+            return;
+        }
+        const gracefulSuccess = await this.gracefulShutdown(port, pid);
+        if (gracefulSuccess) {
+            await this.cleanupPidFile(pidFile);
+            logDebug('MySQL stopped gracefully');
+            return;
+        }
+        await this.forceKillWithEscalation(pid, pidFile);
+    }
+    async getValidatedPid(pidFile) {
+        if (!existsSync(pidFile)) {
+            logDebug('PID file does not exist');
+            return null;
+        }
+        try {
+            const content = await readFile(pidFile, 'utf8');
+            const pid = parseInt(content.trim(), 10);
+            if (isNaN(pid) || pid <= 0) {
+                logWarning(`PID file contains invalid value: "${content.trim()}"`);
+                await this.cleanupPidFile(pidFile);
+                return null;
+            }
+            if (platformService.isProcessRunning(pid)) {
+                logDebug(`Validated PID ${pid}`);
+                return pid;
+            }
+            else {
+                logWarning(`PID file references non-existent process ${pid}`);
+                await this.cleanupPidFile(pidFile);
+                return null;
+            }
+        }
+        catch (error) {
+            const e = error;
+            if (e.code !== 'ENOENT') {
+                logWarning(`Failed to read PID file: ${e.message}`);
+            }
+            return null;
+        }
+    }
+    async gracefulShutdown(port, pid, timeoutMs = 10000) {
+        try {
+            const mysqladmin = await this.getMysqladminPath();
+            logDebug('Attempting mysqladmin shutdown');
+            await execAsync(`"${mysqladmin}" -h 127.0.0.1 -P ${port} -u root shutdown`, { timeout: 5000 });
+        }
+        catch (error) {
+            const e = error;
+            logDebug(`mysqladmin shutdown failed: ${e.message}`);
+            if (pid) {
+                try {
+                    await platformService.terminateProcess(pid, false);
+                }
+                catch (terminateError) {
+                    const termErr = terminateError;
+                    // ESRCH means process doesn't exist - it's already gone
+                    if (termErr.code === 'ESRCH') {
+                        logDebug(`Process ${pid} already terminated (ESRCH)`);
+                        return true;
+                    }
+                    logDebug(`terminateProcess failed for PID ${pid}: ${termErr.message}`);
+                    return false;
+                }
+            }
+        }
+        if (pid) {
+            const startTime = Date.now();
+            const checkIntervalMs = 200;
+            while (Date.now() - startTime < timeoutMs) {
+                if (!platformService.isProcessRunning(pid)) {
+                    logDebug(`Process ${pid} terminated after graceful shutdown`);
+                    return true;
+                }
+                await this.sleep(checkIntervalMs);
+            }
+            logDebug(`Graceful shutdown timed out after ${timeoutMs}ms`);
+            return false;
+        }
+        return true;
+    }
+    async forceKillWithEscalation(pid, pidFile) {
+        logWarning(`Graceful shutdown failed, force killing process ${pid}`);
+        try {
+            await platformService.terminateProcess(pid, false);
+            await this.sleep(2000);
+            if (!platformService.isProcessRunning(pid)) {
+                logDebug(`Process ${pid} terminated after graceful signal`);
+                await this.cleanupPidFile(pidFile);
+                return;
+            }
+        }
+        catch (error) {
+            const e = error;
+            if (e.code === 'ESRCH') {
+                await this.cleanupPidFile(pidFile);
+                return;
+            }
+            logDebug(`Graceful termination failed: ${e.message}`);
+        }
+        const { platform } = platformService.getPlatformInfo();
+        const killCmd = platform === Platform.Win32 ? 'taskkill /F' : 'kill -9';
+        logWarning(`Escalating to force kill for process ${pid}`);
+        try {
+            await platformService.terminateProcess(pid, true);
+            await this.sleep(1000);
+            if (platformService.isProcessRunning(pid)) {
+                throw new SpinDBError(ErrorCodes.PROCESS_STOP_TIMEOUT, `Failed to stop MySQL process ${pid} even with force kill`, 'error', `Try manually killing the process: ${killCmd} ${pid}`);
+            }
+            logDebug(`Process ${pid} terminated after force kill`);
+            await this.cleanupPidFile(pidFile);
+        }
+        catch (error) {
+            if (error instanceof SpinDBError)
+                throw error;
+            const e = error;
+            if (e.code === 'ESRCH') {
+                await this.cleanupPidFile(pidFile);
+                return;
+            }
+            logDebug(`Force kill failed: ${e.message}`);
+        }
+    }
+    async cleanupPidFile(pidFile) {
+        try {
+            await unlink(pidFile);
+            logDebug('PID file cleaned up');
+        }
+        catch (error) {
+            const e = error;
+            if (e.code !== 'ENOENT') {
+                logDebug(`Failed to clean up PID file: ${e.message}`);
+            }
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    async status(container) {
+        const { name, port } = container;
+        const pidFile = paths.getContainerPidPath(name, { engine: ENGINE });
+        if (!existsSync(pidFile)) {
+            return { running: false, message: 'MySQL is not running' };
+        }
+        try {
+            const mysqladmin = await this.getMysqladminPath();
+            await execAsync(`"${mysqladmin}" -h 127.0.0.1 -P ${port} -u root ping`);
+            return { running: true, message: 'MySQL is running' };
+        }
+        catch {
+            return { running: false, message: 'MySQL is not responding' };
+        }
+    }
+    async detectBackupFormat(filePath) {
+        return detectBackupFormatImpl(filePath);
+    }
+    async restore(container, backupPath, options = {}) {
+        const { port, version } = container;
+        const database = options.database || container.database;
+        const binPath = this.getBinaryPath(version);
+        if (options.createDatabase !== false) {
+            await this.createDatabase(container, database);
+        }
+        return restoreBackup(backupPath, {
+            port,
+            database,
+            user: engineDef.superuser,
+            createDatabase: false,
+            validateVersion: options.validateVersion !== false,
+            binPath,
+            containerVersion: version,
+        });
+    }
+    getConnectionString(container, database) {
+        const { port } = container;
+        const db = database || container.database || 'mysql';
+        return `mysql://${engineDef.superuser}@127.0.0.1:${port}/${db}`;
+    }
+    async getMysqlClientPath() {
+        const configPath = await configManager.getBinaryPath('mysql');
+        if (configPath)
+            return configPath;
+        throw new Error('mysql client not found. Ensure MySQL binaries are downloaded:\n' +
+            '  spindb engines download mysql');
+    }
+    async getMysqladminPath() {
+        const cfg = await configManager.getBinaryPath('mysqladmin');
+        if (cfg)
+            return cfg;
+        throw new Error('mysqladmin not found. Ensure MySQL binaries are downloaded:\n' +
+            '  spindb engines download mysql');
+    }
+    async connect(container, database) {
+        const { port } = container;
+        const db = database || container.database || 'mysql';
+        const mysql = await this.getMysqlClientPath();
+        const spawnOptions = {
+            stdio: 'inherit',
+            ...getWindowsSpawnOptions(),
+        };
+        return new Promise((resolve, reject) => {
+            const proc = spawn(mysql, ['-h', '127.0.0.1', '-P', String(port), '-u', engineDef.superuser, db], spawnOptions);
+            proc.on('error', reject);
+            proc.on('close', () => resolve());
+        });
+    }
+    async createDatabase(container, database) {
+        assertValidDatabaseName(database);
+        const { port } = container;
+        const mysql = await this.getMysqlClientPath();
+        try {
+            const cmd = buildMysqlInlineCommand(mysql, port, engineDef.superuser, `CREATE DATABASE IF NOT EXISTS \`${database}\``);
+            await execAsync(cmd);
+        }
+        catch (error) {
+            const err = error;
+            if (!err.message.includes('database exists')) {
+                throw error;
+            }
+        }
+    }
+    async dropDatabase(container, database) {
+        assertValidDatabaseName(database);
+        const { port } = container;
+        const mysql = await this.getMysqlClientPath();
+        try {
+            const cmd = buildMysqlInlineCommand(mysql, port, engineDef.superuser, `DROP DATABASE IF EXISTS \`${database}\``);
+            await execAsync(cmd);
+        }
+        catch (error) {
+            const err = error;
+            if (!err.message.includes("database doesn't exist")) {
+                throw error;
+            }
+        }
+    }
+    async getDatabaseSize(container) {
+        const { port, database } = container;
+        const db = database || 'mysql';
+        assertValidDatabaseName(db);
+        try {
+            const mysql = await this.getMysqlClientPath();
+            const { stdout } = await execAsync(`"${mysql}" -h 127.0.0.1 -P ${port} -u ${engineDef.superuser} -N -e "SELECT COALESCE(SUM(data_length + index_length), 0) FROM information_schema.tables WHERE table_schema = '${db}'"`);
+            const size = parseInt(stdout.trim(), 10);
+            return isNaN(size) ? null : size;
+        }
+        catch {
+            return null;
+        }
+    }
+    async dumpFromConnectionString(connectionString, outputPath) {
+        const dumpPath = await this.getDumpPath();
+        const { host, port, user, password, database } = parseConnectionString(connectionString);
+        if (isWindows()) {
+            let cmd = `"${dumpPath}" -h ${host} -P ${port} -u ${user} --result-file "${outputPath}" ${database}`;
+            let safeCmd = cmd;
+            if (password) {
+                cmd = `"${dumpPath}" -h ${host} -P ${port} -u ${user} -p"${password}" --result-file "${outputPath}" ${database}`;
+                safeCmd = `"${dumpPath}" -h ${host} -P ${port} -u ${user} -p"****" --result-file "${outputPath}" ${database}`;
+            }
+            try {
+                logDebug('Executing mysqldump command', { cmd: safeCmd });
+                await execAsync(cmd);
+                return {
+                    filePath: outputPath,
+                    stdout: '',
+                    stderr: '',
+                    code: 0,
+                };
+            }
+            catch (error) {
+                throw new Error(error.message);
+            }
+        }
+        const args = [
+            '-h',
+            host,
+            '-P',
+            port,
+            '-u',
+            user,
+            '--result-file',
+            outputPath,
+        ];
+        if (password) {
+            args.push(`-p${password}`);
+        }
+        args.push(database);
+        const spawnOptions = {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            ...getWindowsSpawnOptions(),
+        };
+        return new Promise((resolve, reject) => {
+            const proc = spawn(dumpPath, 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 || `mysqldump exited with code ${code}`));
+                }
+            });
+        });
+    }
+    async getDumpPath() {
+        const configPath = await configManager.getBinaryPath('mysqldump');
+        if (configPath)
+            return configPath;
+        throw new Error('mysqldump not found. Ensure MySQL binaries are downloaded:\n' +
+            '  spindb engines download mysql');
+    }
+    async backup(container, outputPath, options) {
+        return createBackup(container, outputPath, options);
+    }
+    async terminateConnections(container, database) {
+        assertValidDatabaseName(database);
+        const { port } = container;
+        const mysql = await this.getMysqlClientPath();
+        // Get all connection IDs for the target database and kill them
+        // We need to do this in two steps since MySQL doesn't support subqueries in KILL
+        const getIdsCmd = buildMysqlInlineCommand(mysql, port, engineDef.superuser, `SELECT ID FROM information_schema.PROCESSLIST WHERE DB = '${database}' AND ID != CONNECTION_ID()`);
+        try {
+            const { stdout } = await execAsync(getIdsCmd);
+            const lines = stdout
+                .trim()
+                .split('\n')
+                .filter((l) => l.trim());
+            // Skip header row if present
+            const ids = lines
+                .slice(1)
+                .map((l) => l.trim())
+                .filter((l) => /^\d+$/.test(l));
+            for (const id of ids) {
+                const killCmd = buildMysqlInlineCommand(mysql, port, engineDef.superuser, `KILL CONNECTION ${id}`);
+                try {
+                    await execAsync(killCmd);
+                }
+                catch {
+                    // Connection may already be gone
+                }
+            }
+        }
+        catch {
+            // Ignore errors - connections may already be gone
+        }
+    }
+    async runScript(container, options) {
+        const { port } = container;
+        const db = options.database || container.database || 'mysql';
+        assertValidDatabaseName(db);
+        const mysql = await this.getMysqlClientPath();
+        if (isWindows()) {
+            const cmd = buildWindowsMysqlCommand(mysql, port, engineDef.superuser, db, options);
+            try {
+                const { stdout, stderr } = await execAsync(cmd);
+                if (stdout)
+                    process.stdout.write(stdout);
+                if (stderr)
+                    process.stderr.write(stderr);
+                return;
+            }
+            catch (error) {
+                const err = error;
+                throw new Error(`mysql client failed: ${err.message}`);
+            }
+        }
+        const args = [
+            '-h',
+            '127.0.0.1',
+            '-P',
+            String(port),
+            '-u',
+            engineDef.superuser,
+            db,
+        ];
+        if (options.sql) {
+            args.push('-e', options.sql);
+            const spawnOptions = {
+                stdio: 'inherit',
+            };
+            return new Promise((resolve, reject) => {
+                const proc = spawn(mysql, args, spawnOptions);
+                proc.on('error', reject);
+                proc.on('close', (code) => {
+                    if (code === 0) {
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`mysql client exited with code ${code}`));
+                    }
+                });
+            });
+        }
+        else if (options.file) {
+            const spawnOptions = {
+                stdio: ['pipe', 'inherit', 'inherit'],
+            };
+            return new Promise((resolve, reject) => {
+                const fileStream = createReadStream(options.file);
+                const proc = spawn(mysql, args, spawnOptions);
+                fileStream.pipe(proc.stdin);
+                fileStream.on('error', (err) => {
+                    proc.kill();
+                    reject(err);
+                });
+                proc.on('error', reject);
+                proc.on('close', (code) => {
+                    if (code === 0) {
+                        resolve();
+                    }
+                    else {
+                        reject(new Error(`mysql client exited with code ${code}`));
+                    }
+                });
+            });
+        }
+        else {
+            throw new Error('Either file or sql option must be provided');
+        }
+    }
+    async executeQuery(container, query, options) {
+        const { port } = container;
+        const db = options?.database || container.database || 'mysql';
+        assertValidDatabaseName(db);
+        const mysql = await this.getMysqlClientPath();
+        // Use -B (batch mode) for tab-separated output
+        const args = [
+            '-h',
+            '127.0.0.1',
+            '-P',
+            String(port),
+            '-u',
+            engineDef.superuser,
+            '-B',
+            db,
+            '-e',
+            query,
+        ];
+        return new Promise((resolve, reject) => {
+            const proc = spawn(mysql, 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();
+            });
+            proc.on('error', reject);
+            proc.on('close', (code) => {
+                if (code === 0) {
+                    resolve(parseTSVToQueryResult(stdout));
+                }
+                else {
+                    reject(new Error(stderr || `mysql exited with code ${code}`));
+                }
+            });
+        });
+    }
+    /**
+     * List all user databases, excluding system databases
+     * (information_schema, mysql, performance_schema, sys).
+     */
+    async listDatabases(container) {
+        const { port } = container;
+        const mysql = await this.getMysqlClientPath();
+        // Query for all non-system databases
+        const sql = `SHOW DATABASES WHERE \`Database\` NOT IN ('information_schema', 'mysql', 'performance_schema', 'sys')`;
+        const args = [
+            '-h',
+            '127.0.0.1',
+            '-P',
+            String(port),
+            '-u',
+            engineDef.superuser,
+            '-N', // Skip column names
+            '-B', // Batch mode (no formatting)
+            '-e',
+            sql,
+        ];
+        return new Promise((resolve, reject) => {
+            const proc = spawn(mysql, 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();
+            });
+            proc.on('error', reject);
+            proc.on('close', (code) => {
+                if (code === 0) {
+                    const databases = stdout
+                        .trim()
+                        .split('\n')
+                        .map((db) => db.trim())
+                        .filter((db) => db.length > 0);
+                    resolve(databases);
+                }
+                else {
+                    reject(new Error(stderr || `mysql exited with code ${code}`));
+                }
+            });
+        });
+    }
+    async createUser(container, options) {
+        const { username, password, database } = options;
+        assertValidUsername(username);
+        const { port } = container;
+        const db = database || container.database;
+        if (!db) {
+            throw new Error('No target database specified. Provide a database name with --database or ensure the container has a default database.');
+        }
+        assertValidDatabaseName(db);
+        const mysql = await this.getMysqlClientPath();
+        // Check if NO_BACKSLASH_ESCAPES is enabled — if so, only escape single quotes
+        let noBackslashEscapes = false;
+        try {
+            const modeArgs = [
+                '-h',
+                '127.0.0.1',
+                '-P',
+                String(port),
+                '-u',
+                engineDef.superuser,
+                '-N',
+                '-B',
+                '-e',
+                'SELECT @@sql_mode',
+            ];
+            const modeResult = await new Promise((resolve, reject) => {
+                const proc = spawn(mysql, modeArgs, {
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                let stdout = '';
+                proc.stdout?.on('data', (data) => {
+                    stdout += data.toString();
+                });
+                proc.on('close', (code) => {
+                    if (code === 0)
+                        resolve(stdout.trim());
+                    else
+                        reject(new Error(`Failed to query sql_mode`));
+                });
+                proc.on('error', reject);
+            });
+            noBackslashEscapes = modeResult.includes('NO_BACKSLASH_ESCAPES');
+        }
+        catch {
+            // Default to backslash-escaping if query fails
+        }
+        const escapedPass = noBackslashEscapes
+            ? password.replace(/'/g, "''")
+            : password.replace(/\\/g, '\\\\').replace(/'/g, "''");
+        const escapedDb = db.replace(/`/g, '``');
+        const escapedUser = noBackslashEscapes
+            ? username.replace(/'/g, "''")
+            : username.replace(/\\/g, '\\\\').replace(/'/g, "''");
+        const sql = `CREATE USER IF NOT EXISTS '${escapedUser}'@'%' IDENTIFIED BY '${escapedPass}'; CREATE USER IF NOT EXISTS '${escapedUser}'@'localhost' IDENTIFIED BY '${escapedPass}'; ALTER USER '${escapedUser}'@'%' IDENTIFIED BY '${escapedPass}'; ALTER USER '${escapedUser}'@'localhost' IDENTIFIED BY '${escapedPass}'; GRANT ALL ON \`${escapedDb}\`.* TO '${escapedUser}'@'%'; GRANT ALL ON \`${escapedDb}\`.* TO '${escapedUser}'@'localhost'; FLUSH PRIVILEGES;`;
+        // Send SQL via stdin to avoid leaking password in process argv
+        const args = [
+            '-h',
+            '127.0.0.1',
+            '-P',
+            String(port),
+            '-u',
+            engineDef.superuser,
+        ];
+        await new Promise((resolve, reject) => {
+            const proc = spawn(mysql, args, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            let stderr = '';
+            proc.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('close', (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`Failed to create user: ${stderr}`));
+            });
+            proc.on('error', reject);
+            proc.stdin?.write(sql);
+            proc.stdin?.end();
+        });
+        const connectionString = `mysql://${encodeURIComponent(username)}:${encodeURIComponent(password)}@127.0.0.1:${port}/${db}`;
+        return {
+            username,
+            password,
+            connectionString,
+            engine: container.engine,
+            container: container.name,
+            database: db,
+        };
+    }
+}
+export const mysqlEngine = new MySQLEngine();
+//# sourceMappingURL=index.js.map