spindb 0.68.7 → 0.68.9

package/dist/engines/mysql/dump-normalize.js

@@ -0,0 +1,201 @@
+/**
+ * MariaDB -> MySQL Dump Normalization
+ *
+ * A dump taken from a MariaDB source with `mariadb-dump` is valid SQL for
+ * MariaDB, not for MySQL. Three things in it stop a MySQL 8 or 9 target, and
+ * all three are mechanical rewrites of statements MySQL has an exact or a
+ * near-exact equivalent for:
+ *
+ * 1. **uca1400 collations.** MariaDB 11.4 made `utf8mb4_uca1400_ai_ci` the
+ *    default database collation, so nearly every `CREATE TABLE` in a modern
+ *    MariaDB dump names a collation MySQL has never had. MySQL's UCA 9.0.0
+ *    collations are the same Unicode collation algorithm at a newer UCA
+ *    version, so `utf8mb4_0900_ai_ci` is the honest counterpart.
+ * 2. **`NO_AUTO_CREATE_USER` in `SET sql_mode`.** MariaDB still emits it around
+ *    triggers and routines; MySQL removed the mode in 8.0 and answers
+ *    ERROR 1231 (Variable 'sql_mode' can't be set to the value of
+ *    'NO_AUTO_CREATE_USER').
+ * 3. **The sandbox directive.** `mariadb-dump` 11.x opens every dump with
+ *    `/*M!999999\- enable the sandbox mode *\/`. MySQL reads it as a comment
+ *    and is unharmed, but it is MariaDB-only noise in a file we are converting.
+ *
+ * What is deliberately NOT rewritten: sequences (`CREATE SEQUENCE`, `nextval()`
+ * defaults) and MariaDB-only column types (`UUID`, `INET4`, `INET6`,
+ * `VECTOR`). MySQL has no equivalent, and quietly substituting one would put
+ * different data in the target than the source holds. Those statements are left
+ * to fail with the server's own error, which names the object that could not be
+ * converted. `json_valid()` CHECK constraints need no rewrite: MySQL has
+ * `json_valid()`.
+ *
+ * Every rule is line-oriented, so a multi-gigabyte dump is rewritten as a
+ * stream and never held in memory.
+ */
+import { createReadStream, createWriteStream } from 'fs';
+import { createInterface } from 'readline';
+import { once } from 'events';
+export function emptyNormalizationCounts() {
+    return {
+        collationsMapped: 0,
+        sqlModeFlagsRemoved: 0,
+        sandboxDirectivesDropped: 0,
+    };
+}
+export function totalRewrites(counts) {
+    return (counts.collationsMapped +
+        counts.sqlModeFlagsRemoved +
+        counts.sandboxDirectivesDropped);
+}
+// MySQL's UCA 9.0.0 counterparts, keyed by MariaDB's accent/case suffix.
+// MySQL has no accent-insensitive-but-case-sensitive utf8mb4 collation, so
+// `ai_cs` maps to `as_cs`: the case sensitivity the schema asked for is kept,
+// and accent sensitivity is the property that cannot be honored.
+const UCA1400_SUFFIX_MAP = {
+    ai_ci: 'utf8mb4_0900_ai_ci',
+    as_cs: 'utf8mb4_0900_as_cs',
+    as_ci: 'utf8mb4_0900_as_ci',
+    ai_cs: 'utf8mb4_0900_as_cs',
+};
+// The two suffixes that ask for case sensitivity. MariaDB spells accent and
+// case sensitivity separately; only the case half survives a utf8mb3 target.
+const CASE_SENSITIVE_SUFFIXES = new Set(['as_cs', 'ai_cs']);
+const UTF8MB4_FALLBACK = 'utf8mb4_0900_ai_ci';
+const UTF8MB3_FALLBACK = 'utf8mb3_unicode_ci';
+// MySQL has no utf8mb3 UCA collation that is case sensitive, so a schema that
+// asked for one gets `utf8mb3_bin`. Binary ordering is not UCA ordering, but it
+// is the only utf8mb3 collation that keeps case sensitivity, and losing case
+// sensitivity silently changes which rows a comparison matches.
+const UTF8MB3_CASE_SENSITIVE = 'utf8mb3_bin';
+const UTF8MB4_UCA1400 = /\butf8mb4_uca1400_([a-z0-9_]+)/gi;
+const UTF8MB3_UCA1400 = /\b(?:utf8mb3|utf8)_uca1400_([a-z0-9_]+)/gi;
+const SQL_MODE_ASSIGNMENT = /\bsql_mode\s*=\s*'/i;
+const ROW_STATEMENT = /^\s*(?:INSERT|REPLACE)\b/i;
+const SANDBOX_DIRECTIVE = /^\s*\/\*M!\d+\\?-.*sandbox mode.*\*\/\s*;?\s*$/i;
+const NO_AUTO_CREATE_USER = 'NO_AUTO_CREATE_USER';
+/**
+ * Map one MariaDB uca1400 collation name to its MySQL counterpart.
+ *
+ * `nopad_` is a padding variant MySQL does not spell out in the collation
+ * name, so it is stripped and the remaining suffix decides the target. Any
+ * suffix that is not one of the four accent/case combinations (locale-specific
+ * collations such as `utf8mb4_uca1400_swedish_ai_ci`) falls back to the
+ * default `utf8mb4_0900_ai_ci`, because MySQL's locale-tailored collations do
+ * not line up one-for-one with MariaDB's.
+ */
+export function mapUca1400Collation(suffix) {
+    return UCA1400_SUFFIX_MAP[normalizeUca1400Suffix(suffix)] ?? UTF8MB4_FALLBACK;
+}
+/**
+ * Map one MariaDB utf8mb3 uca1400 collation name to a utf8mb3 collation MySQL
+ * has.
+ *
+ * Same suffix parsing as `mapUca1400Collation`, different target set: MySQL's
+ * UCA 9.0.0 collations are utf8mb4 only, so a utf8mb3 column cannot follow the
+ * charset it declared into `utf8mb4_0900_*`. What it can keep is case
+ * sensitivity, so `_as_cs` and `_ai_cs` (and their `nopad_` forms) map to
+ * `utf8mb3_bin` rather than being flattened into a `_ci` collation that would
+ * quietly start matching rows the source did not.
+ */
+export function mapUca1400Utf8mb3Collation(suffix) {
+    return CASE_SENSITIVE_SUFFIXES.has(normalizeUca1400Suffix(suffix))
+        ? UTF8MB3_CASE_SENSITIVE
+        : UTF8MB3_FALLBACK;
+}
+/**
+ * `nopad_` is a padding variant MySQL does not spell out in the collation name,
+ * so it is stripped before the accent/case suffix is read.
+ */
+function normalizeUca1400Suffix(suffix) {
+    return suffix.toLowerCase().replace(/^nopad_/, '');
+}
+/**
+ * Rewrite one line of a MariaDB dump so a MySQL server accepts it.
+ *
+ * Pure: the whole contract of the conversion lives here, so it is unit tested
+ * line by line rather than by diffing a real dump.
+ */
+export function normalizeMariaDbDumpForMysql(line) {
+    const counts = emptyNormalizationCounts();
+    if (SANDBOX_DIRECTIVE.test(line)) {
+        counts.sandboxDirectivesDropped = 1;
+        return { line: null, counts };
+    }
+    // A row is data, never DDL. A collation name is an ordinary string that a
+    // user is entitled to store (a migration log, a schema-tracking table, an
+    // ORM's own bookkeeping), and rewriting it would put different bytes in the
+    // target than the source holds - the exact outcome the sql_mode rule below
+    // already refuses. No INSERT or REPLACE in a dump carries a collation that
+    // needs converting, so the whole line is left alone.
+    if (ROW_STATEMENT.test(line)) {
+        return { line, counts };
+    }
+    let result = line.replace(UTF8MB4_UCA1400, (_match, suffix) => {
+        counts.collationsMapped++;
+        return mapUca1400Collation(suffix);
+    });
+    result = result.replace(UTF8MB3_UCA1400, (_match, suffix) => {
+        counts.collationsMapped++;
+        return mapUca1400Utf8mb3Collation(suffix);
+    });
+    if (result.includes(NO_AUTO_CREATE_USER) &&
+        SQL_MODE_ASSIGNMENT.test(result)) {
+        result = result.replace(/'([^']*)'/g, (match, contents) => {
+            if (!contents.includes(NO_AUTO_CREATE_USER))
+                return match;
+            const kept = contents
+                .split(',')
+                .filter((mode) => mode.trim() !== NO_AUTO_CREATE_USER);
+            const removed = contents.split(',').length - kept.length;
+            if (removed === 0)
+                return match;
+            counts.sqlModeFlagsRemoved += removed;
+            return `'${kept.join(',')}'`;
+        });
+    }
+    return { line: result, counts };
+}
+/**
+ * Stream a MariaDB dump through `normalizeMariaDbDumpForMysql`, writing the
+ * MySQL-ready result to a new file.
+ *
+ * Line by line with explicit backpressure: a dump is routinely larger than the
+ * process can hold, so it is never read into a string.
+ *
+ * **Read and written as `latin1`, never `utf8`.** A dump is not guaranteed to
+ * be valid UTF-8: a `latin1` column, or a BLOB that `mariadb-dump` writes as
+ * escaped bytes rather than a hex literal, puts arbitrary bytes above 0x7F in
+ * the file. Decoding those as UTF-8 replaces every invalid sequence with
+ * U+FFFD, so the conversion silently rewrote the user's data (a `0x80 0xFF`
+ * BLOB came out as six `EF BF BD` bytes). `latin1` maps bytes 1:1 to code
+ * points 0-255 and back, so the file round-trips byte for byte and only the
+ * ASCII tokens the rules match are ever changed. Line splitting stays correct
+ * because MySQL escapes `\n` and `\r` inside string literals, so a raw
+ * newline byte never appears in dump data.
+ */
+export async function normalizeMariaDbDumpFile(options) {
+    const { inputPath, outputPath } = options;
+    const counts = emptyNormalizationCounts();
+    const input = createReadStream(inputPath, { encoding: 'latin1' });
+    const output = createWriteStream(outputPath, { encoding: 'latin1' });
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            const normalized = normalizeMariaDbDumpForMysql(line);
+            counts.collationsMapped += normalized.counts.collationsMapped;
+            counts.sqlModeFlagsRemoved += normalized.counts.sqlModeFlagsRemoved;
+            counts.sandboxDirectivesDropped +=
+                normalized.counts.sandboxDirectivesDropped;
+            if (normalized.line === null)
+                continue;
+            if (!output.write(`${normalized.line}\n`)) {
+                await once(output, 'drain');
+            }
+        }
+    }
+    finally {
+        lines.close();
+        output.end();
+    }
+    await once(output, 'close');
+    return counts;
+}
+//# sourceMappingURL=dump-normalize.js.map

package/dist/engines/mysql/dump-normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dump-normalize.js","sourceRoot":"","sources":["../../../engines/mysql/dump-normalize.ts"],"names":[],"mappings":"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"}

package/dist/engines/mysql/index.js

@@ -22,6 +22,11 @@ import { SUPPORTED_MAJOR_VERSIONS, FALLBACK_VERSION_MAP } from './version-maps.j
 import { resolveEngineVersion } from '../../core/version-resolver.js';
 import { detectBackupFormat as detectBackupFormatImpl, restoreBackup, parseConnectionString, } from './restore.js';
 import { createBackup } from './backup.js';
+import { normalizeMariaDbDumpFile, totalRewrites, } from './dump-normalize.js';
+import { buildMariaDbRemoteDumpArgs } from '../mariadb/index.js';
+import { mariadbBinaryManager } from '../mariadb/binary-manager.js';
+import { probeMysqlFamilyServer, } from '../../core/server-handshake.js';
+import { resolveBundledMysqlFamilyBinary } from '../../core/mysql-family-binary-resolver.js';
 import { Engine, Platform, } from '../../types/index.js';
 import { parseTSVToQueryResult } from '../../core/query-parser.js';
 const execFileAsync = promisify(execFile);
@@ -837,9 +842,49 @@ export class MySQLEngine extends BaseEngine {
             return null;
         }
     }
+    /**
+     * Dump a remote database reached through a `mysql://` URL.
+     *
+     * **The dump tool follows the SOURCE server, not this container.** That is
+     * the rule PostgreSQL already follows (`validateDumpCompatibility` in
+     * `engines/postgresql/version-validator.ts` swaps in a `pg_dump` that can
+     * read the remote major). PostgreSQL only has to follow a version. The MySQL
+     * family has to follow a flavor as well, because MySQL and MariaDB share a
+     * wire protocol and a URL scheme: `mysql://host/db` says nothing about which
+     * server is on the other end, and the two ship different, mutually
+     * unusable dump tools.
+     *
+     * Guessing wrong is not a degraded dump, it is no dump at all. `mysqldump` 9
+     * cannot even authenticate against a MariaDB server: MySQL 9 dropped the
+     * `mysql_native_password` client plugin, MariaDB's root user still uses it,
+     * and the dump dies on `Authentication plugin 'mysql_native_password' cannot
+     * be loaded` before it reads a single table. No flag fixes that.
+     *
+     * So the source is probed first (`core/server-handshake.ts` reads the
+     * greeting the server sends on connect, without writing anything or
+     * authenticating), and a MariaDB source is dumped with `mariadb-dump` and
+     * then normalized for this MySQL target. A MySQL source, or a source that
+     * could not be probed, takes the unchanged `mysqldump` path.
+     */
     async dumpFromConnectionString(connectionString, outputPath, options) {
-        const dumpPath = await this.getDumpPath();
         const { host, port, user, password, database } = parseConnectionString(connectionString);
+        const source = await probeMysqlFamilyServer({
+            host,
+            port: parseInt(port, 10) || 3306,
+        });
+        if (source.flavor === 'mariadb') {
+            return this.dumpFromMariaDbSource({
+                source,
+                host,
+                port,
+                user,
+                password,
+                database,
+                outputPath,
+                excludeTables: options?.excludeTables,
+            });
+        }
+        const dumpPath = await this.getDumpPath(options?.targetVersion);
         const args = buildMysqlRemoteDumpArgs({
             host,
             port,
@@ -848,12 +893,159 @@ export class MySQLEngine extends BaseEngine {
             outputPath,
             excludeTables: options?.excludeTables,
         });
+        const { stdout, stderr } = await this.runDumpTool({
+            toolPath: dumpPath,
+            toolName: 'mysqldump',
+            args,
+            password,
+        });
+        logDebug('Remote dump taken with mysqldump', {
+            host,
+            sourceFlavor: source.flavor,
+            sourceVersion: source.version,
+            dumpPath,
+        });
+        return {
+            filePath: outputPath,
+            stdout,
+            stderr,
+            code: 0,
+            remoteSource: {
+                flavor: source.flavor,
+                serverVersion: source.version || undefined,
+                dumpTool: 'mysqldump',
+            },
+        };
+    }
+    /**
+     * Dump a MariaDB source into a file this MySQL container can restore.
+     *
+     * Two steps, both of which are needed: take the dump with MariaDB's own
+     * tool, then rewrite the MariaDB-only SQL it emits (see
+     * `engines/mysql/dump-normalize.ts` for exactly which statements and why).
+     */
+    async dumpFromMariaDbSource(options) {
+        const { source, host, port, user, password, database, outputPath, excludeTables, } = options;
+        const tool = await this.resolveMariaDbDumpPath(source);
+        // mariadb-dump writes through --result-file, so the raw dump lands beside
+        // the requested path and is rewritten into it.
+        const rawPath = `${outputPath}.mariadb`;
+        const warnings = [
+            `Source is MariaDB ${source.version}; dumped with mariadb-dump ${tool.version} ` +
+                '(mysqldump cannot authenticate against a MariaDB server)',
+        ];
+        if (tool.downloaded) {
+            warnings.push(`Downloaded MariaDB ${tool.version} client tools to read the source`);
+        }
+        let counts;
+        let stdout;
+        let stderr;
+        try {
+            const dump = await this.runDumpTool({
+                toolPath: tool.path,
+                toolName: 'mariadb-dump',
+                args: buildMariaDbRemoteDumpArgs({
+                    host,
+                    port,
+                    user,
+                    database,
+                    outputPath: rawPath,
+                    excludeTables,
+                }),
+                password,
+            });
+            stdout = dump.stdout;
+            stderr = dump.stderr;
+            counts = await normalizeMariaDbDumpFile({
+                inputPath: rawPath,
+                outputPath,
+            });
+        }
+        finally {
+            await rm(rawPath, { force: true });
+        }
+        if (totalRewrites(counts) > 0) {
+            warnings.push(`Converted the dump for MySQL: ${counts.collationsMapped} uca1400 collations mapped, ` +
+                `${counts.sqlModeFlagsRemoved} NO_AUTO_CREATE_USER sql_mode flags removed, ` +
+                `${counts.sandboxDirectivesDropped} MariaDB sandbox directives dropped`);
+        }
+        warnings.push('MariaDB-only objects (sequences, UUID/INET4/INET6/VECTOR columns) are not ' +
+            'converted and will be reported by the server if the source uses them');
+        logDebug('Remote dump taken with mariadb-dump', {
+            host,
+            sourceVersion: source.version,
+            dumpPath: tool.path,
+            ...counts,
+        });
+        return {
+            filePath: outputPath,
+            stdout,
+            stderr,
+            code: 0,
+            warnings,
+            remoteSource: {
+                flavor: 'mariadb',
+                serverVersion: source.version,
+                dumpTool: 'mariadb-dump',
+                dumpToolVersion: tool.version,
+                rewrites: {
+                    collationsMapped: counts.collationsMapped,
+                    sqlModeFlagsRemoved: counts.sqlModeFlagsRemoved,
+                    sandboxDirectivesDropped: counts.sandboxDirectivesDropped,
+                },
+            },
+        };
+    }
+    /**
+     * Find a `mariadb-dump` able to read this source, downloading MariaDB's
+     * client tools if none is installed.
+     *
+     * The source's own major.minor line is preferred, so an 11.8 server is read
+     * by an 11.8 tool when one is on disk; otherwise the newest installed
+     * MariaDB is used, and only a machine with no MariaDB at all downloads.
+     */
+    async resolveMariaDbDumpPath(source) {
+        const preferVersion = source.majorVersion !== null && source.minorVersion !== null
+            ? `${source.majorVersion}.${source.minorVersion}`
+            : undefined;
+        const installed = resolveBundledMysqlFamilyBinary({
+            engine: 'mariadb',
+            tool: 'mariadb-dump',
+            preferVersion,
+        });
+        if (installed)
+            return { ...installed, downloaded: false };
+        const { platform: p, arch: a } = this.getPlatformInfo();
+        const defaultVersion = getEngineDefaults('mariadb').defaultVersion;
+        try {
+            await mariadbBinaryManager.ensureInstalled(defaultVersion, p, a);
+        }
+        catch (error) {
+            throw new SpinDBError(ErrorCodes.DEPENDENCY_MISSING, `The source server is MariaDB ${source.version}, which needs mariadb-dump, ` +
+                `and downloading MariaDB ${defaultVersion} failed: ${error.message}`, 'fatal', 'Download MariaDB client tools: spindb engines download mariadb');
+        }
+        const downloaded = resolveBundledMysqlFamilyBinary({
+            engine: 'mariadb',
+            tool: 'mariadb-dump',
+            preferVersion,
+        });
+        if (!downloaded) {
+            throw new SpinDBError(ErrorCodes.DEPENDENCY_MISSING, `The source server is MariaDB ${source.version}, but no mariadb-dump is installed.`, 'fatal', 'Download MariaDB client tools: spindb engines download mariadb');
+        }
+        return { ...downloaded, downloaded: true };
+    }
+    /**
+     * Run a dump tool and collect its output. Shared by both source flavors so
+     * the failure surface (and the password handling) is identical.
+     */
+    async runDumpTool(options) {
+        const { toolPath, toolName, args, password } = options;
         const spawnOptions = {
             stdio: ['pipe', 'pipe', 'pipe'],
             env: password ? { ...process.env, MYSQL_PWD: password } : process.env,
         };
         return new Promise((resolve, reject) => {
-            const proc = spawn(dumpPath, args, spawnOptions);
+            const proc = spawn(toolPath, args, spawnOptions);
             let stdout = '';
             let stderr = '';
             proc.stdout?.on('data', (data) => {
@@ -865,20 +1057,32 @@ export class MySQLEngine extends BaseEngine {
             proc.on('error', reject);
             proc.on('close', (code) => {
                 if (code === 0) {
-                    resolve({
-                        filePath: outputPath,
-                        stdout,
-                        stderr,
-                        code,
-                    });
+                    resolve({ stdout, stderr });
                 }
                 else {
-                    reject(new Error(stderr || `mysqldump exited with code ${code}`));
+                    reject(new Error(stderr || `${toolName} exited with code ${code}`));
                 }
             });
         });
     }
-    async getDumpPath() {
+    /**
+     * Resolve mysqldump, preferring the version the dump is headed for.
+     *
+     * `configManager.getBinaryPath('mysqldump')` keeps ONE path per tool name
+     * with no version dimension, so on a machine with several MySQL versions
+     * installed it returns whichever was registered first and still exists: a
+     * 9.7.2 container was dumping through `mysql-9.6.0/bin/mysqldump`. The
+     * bundled cache is asked first, exactly as the local backup path already
+     * does, and the globally registered path stays the last resort.
+     */
+    async getDumpPath(preferVersion) {
+        const bundled = resolveBundledMysqlFamilyBinary({
+            engine: 'mysql',
+            tool: 'mysqldump',
+            preferVersion,
+        });
+        if (bundled)
+            return bundled.path;
         const configPath = await configManager.getBinaryPath('mysqldump');
         if (configPath)
             return configPath;