tablewalk 0.0.1

package/dist/adapters/mysql.js

@@ -0,0 +1,951 @@
+/**
+ * MySQL adapter, on `mysql2`.
+ *
+ * The catalog is `information_schema`, so introspection is four queries no
+ * matter how many tables exist — the same trade the Postgres adapter makes,
+ * and for the same reason: a schema with four hundred tables should cost one
+ * round trip per *kind* of fact, not one per table.
+ *
+ * Two things about MySQL shape everything below.
+ *
+ * The first is that a database *is* a schema. There is no second level of
+ * namespacing, so `TABLE_SCHEMA` in the catalog is what `USE` selects and what
+ * a connection URL's path names. That makes the Postgres mapping exact rather
+ * than approximate: a table's `schema` is its database and its `id` is
+ * `database.table`, qualified in every statement as `` `shop`.`invoice` ``.
+ * Naming the database in the statement is also what keeps a browsing session
+ * honest when the connection's default database is not the one being read —
+ * `USE` is a mutable, per-connection setting and nothing here relies on it.
+ *
+ * The second is that a MySQL connection has no read-only mode of its own, the
+ * way a SQLite handle does. `SET SESSION TRANSACTION READ ONLY` is the closest
+ * equivalent and it is a real one: with autocommit on, every statement is its
+ * own transaction and inherits the session's access mode, so INSERT, UPDATE,
+ * DELETE, TRUNCATE, CREATE and DROP all come back as error 1792 rather than
+ * running. See `open` for what that does and does not cover.
+ */
+import { MYSQL_STYLE, buildWhere, clampLimit, boundStatement, dedupe, looksWrappable, refuseStacked, trimStatement, clampOffset, Refusal, Serial, } from './adapter.js';
+import { compileView, compileViewCount } from '../shared/view.js';
+import { compileBreakdown, compileBreakdownCount } from '../shared/breakdown.js';
+import { typeVocabulary } from '../shared/vocabulary.js';
+import { coerceForColumn, deleteRuleOf, } from '../shared/schema.js';
+export class MysqlAdapter {
+    connectionString;
+    label;
+    extraDatabases;
+    dialect = 'mysql';
+    client = null;
+    /** Opened lazily, only when an edit is actually applied. */
+    writeClient = null;
+    /* Every write on that connection, one at a time. See `Serial`. */
+    writes = new Serial();
+    /** Filled in on connect: the database the URL names, plus any extras. */
+    databases = [];
+    constructor(connectionString, label = redact(connectionString), 
+    /**
+     * Further databases to browse alongside the one the URL selects.
+     *
+     * Empty — the normal case — means just that one. A MySQL server hosts
+     * every tenant's database side by side in one `information_schema`, so
+     * introspecting the lot by default would hand someone browsing `shop`
+     * four hundred tables belonging to people who are not them.
+     */
+    extraDatabases = []) {
+        this.connectionString = connectionString;
+        this.label = label;
+        this.extraDatabases = extraDatabases;
+    }
+    async conn() {
+        if (this.client)
+            return this.client;
+        const client = await this.open(true);
+        /* Asked of the server rather than parsed out of the URL, so a socket
+           connection, a `?database=` parameter and a plain path all resolve the
+           same way — and so the answer is the database the server actually put us
+           in rather than the one we hoped for. */
+        const [rows] = await client.query('SELECT DATABASE() AS db');
+        const current = rows[0]?.db ?? '';
+        if (!current && !this.extraDatabases.length) {
+            await client.end();
+            throw new Error('A MySQL URL has to name a database: mysql://user:password@host:3306/dbname');
+        }
+        this.databases = [...new Set([current, ...this.extraDatabases].filter(Boolean))];
+        this.client = client;
+        return client;
+    }
+    /**
+     * Open a connection, read-only unless this is the write handle.
+     *
+     * The read-only part is enforced by the server, not by convention here:
+     * `SET SESSION TRANSACTION READ ONLY` makes every subsequent statement on
+     * this connection run in a read-only transaction, and MySQL answers a write
+     * with ER_CANT_EXECUTE_IN_READ_ONLY_TRANSACTION (1792). Verified against
+     * MySQL 8.4 for INSERT, UPDATE, DELETE, TRUNCATE, CREATE TABLE, CREATE
+     * TEMPORARY TABLE and DROP TABLE.
+     *
+     * What it does not cover: a user with SUPER could turn it off again by
+     * running `SET SESSION TRANSACTION READ WRITE`, and nothing stops a stored
+     * procedure called from a SELECT from writing. Neither is reachable through
+     * this adapter — it only ever sends the statements it builds — but the
+     * guarantee is "this connection refuses writes", not "this connection could
+     * not write under any circumstances", and it is worth being exact about
+     * which of those is true.
+     */
+    async open(readOnly) {
+        const createConnection = await driver();
+        const client = await createConnection({
+            uri: this.connectionString,
+            /* A stacked `; DROP TABLE customer` has to be a syntax error rather than
+               a second statement. It is mysql2's default; set explicitly because the
+               entire safety argument here rests on one statement per call. */
+            multipleStatements: false,
+            /* DATETIME and TIMESTAMP arrive as the text the server stores. A JS Date
+               would be read in the process's local zone and written back out as UTC,
+               so `2025-03-14 00:00:00` would be shown as the 13th to anyone east of
+               Greenwich — a browsing tool inventing an offset the column does not
+               have. The query language's date windows are the same text format, so
+               filters and displayed values also stay comparable. */
+            dateStrings: true,
+            /* A BIGINT past 2^53 becomes a string rather than a silently wrong
+               number. Losing the last digits of an id is the kind of error that
+               looks fine on screen and matches nothing when clicked. */
+            supportBigNumbers: true,
+            connectTimeout: 15_000,
+        });
+        if (!readOnly)
+            return client;
+        await client.query('SET SESSION TRANSACTION READ ONLY');
+        try {
+            await client.query('SET SESSION max_execution_time = 30000');
+        }
+        catch {
+            /* MariaDB spells this `max_statement_time` and measures it in seconds.
+               A missing statement timeout is worth a slow query, not a refusal to
+               open the connection at all. */
+        }
+        return client;
+    }
+    async introspect() {
+        const db = await this.conn();
+        const holes = this.databases.map(() => '?').join(', ');
+        const tableRows = await this.read(db, `SELECT TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE, TABLE_ROWS, TABLE_COMMENT
+         FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA IN (${holes})
+        ORDER BY TABLE_SCHEMA, TABLE_NAME`, this.databases);
+        const wanted = new Set(tableRows.rows.map((r) => `${r.TABLE_SCHEMA}.${r.TABLE_NAME}`));
+        const columnRows = await this.read(db, `SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE,
+              COLUMN_DEFAULT, COLUMN_KEY, COLUMN_COMMENT
+         FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA IN (${holes})
+        ORDER BY TABLE_SCHEMA, TABLE_NAME, ORDINAL_POSITION`, this.databases);
+        /* Only the leading column of each index, which is the only one an ORDER BY
+           can be satisfied by: an index on (customer_id, opened_at) makes
+           `ORDER BY customer_id` free and `ORDER BY opened_at` a full sort. The
+           primary key is in here too, because MySQL reports it as an index named
+           PRIMARY and it is the default order's last resort.
+    
+           A functional index (8.0.13 and later) has a NULL COLUMN_NAME and an
+           EXPRESSION instead; it is dropped, as it should be, since there is no
+           bare column for a sort to lean on. */
+        const indexRows = await this.read(db, `SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME
+         FROM information_schema.STATISTICS
+        WHERE TABLE_SCHEMA IN (${holes})
+          AND SEQ_IN_INDEX = 1
+          AND COLUMN_NAME IS NOT NULL`, this.databases);
+        /* KEY_COLUMN_USAGE carries one row per column of a key, so a two-column
+           foreign key is two rows to be collapsed by ORDINAL_POSITION — the same
+           shape SQLite's PRAGMA returns. The join to REFERENTIAL_CONSTRAINTS is
+           what makes these foreign keys specifically: KEY_COLUMN_USAGE also lists
+           primary and unique keys, which have no referenced table and would
+           otherwise have to be filtered by a NULL check standing in for a fact the
+           catalog states directly. */
+        const keyRows = await this.read(db, `SELECT k.CONSTRAINT_NAME, k.TABLE_SCHEMA, k.TABLE_NAME, k.COLUMN_NAME,
+              k.REFERENCED_TABLE_SCHEMA, k.REFERENCED_TABLE_NAME, k.REFERENCED_COLUMN_NAME,
+              r.DELETE_RULE
+         FROM information_schema.KEY_COLUMN_USAGE k
+         JOIN information_schema.REFERENTIAL_CONSTRAINTS r
+           ON r.CONSTRAINT_SCHEMA = k.CONSTRAINT_SCHEMA
+          AND r.CONSTRAINT_NAME = k.CONSTRAINT_NAME
+          AND r.TABLE_NAME = k.TABLE_NAME
+        WHERE k.TABLE_SCHEMA IN (${holes})
+        ORDER BY k.TABLE_SCHEMA, k.TABLE_NAME, k.CONSTRAINT_NAME, k.ORDINAL_POSITION`, this.databases);
+        const foreignKeys = [];
+        /* A column-level reference map, so the table view can show "this column
+           points there" without searching the whole key list per cell. */
+        const refByColumn = new Map();
+        const byConstraint = new Map();
+        for (const row of keyRows.rows) {
+            /* Keyed by table as well as constraint name: MySQL only requires a
+               foreign key name to be unique within its database, so two tables may
+               each have an `fk_customer` and grouping by name alone would weld them
+               into one four-column key pointing at the wrong thing. */
+            const id = `${row.TABLE_SCHEMA}.${row.TABLE_NAME}.${row.CONSTRAINT_NAME}`;
+            const list = byConstraint.get(id) ?? [];
+            list.push(row);
+            byConstraint.set(id, list);
+        }
+        for (const group of byConstraint.values()) {
+            const from = `${group[0].TABLE_SCHEMA}.${group[0].TABLE_NAME}`;
+            const to = `${group[0].REFERENCED_TABLE_SCHEMA}.${group[0].REFERENCED_TABLE_NAME}`;
+            // A key can point at a database this session is not browsing. Those
+            // edges lead nowhere the user can click, so they are dropped rather
+            // than drawn broken.
+            if (!wanted.has(from) || !wanted.has(to))
+                continue;
+            foreignKeys.push({
+                name: group[0].CONSTRAINT_NAME,
+                from: { table: from, columns: group.map((r) => r.COLUMN_NAME) },
+                to: { table: to, columns: group.map((r) => r.REFERENCED_COLUMN_NAME) },
+                onDelete: deleteRuleOf(group[0].DELETE_RULE),
+            });
+            for (const row of group) {
+                refByColumn.set(`${from}.${row.COLUMN_NAME}`, {
+                    table: to,
+                    column: row.REFERENCED_COLUMN_NAME,
+                });
+            }
+        }
+        const indexedByTable = new Map();
+        for (const row of indexRows.rows) {
+            const id = `${row.TABLE_SCHEMA}.${row.TABLE_NAME}`;
+            const set = indexedByTable.get(id) ?? new Set();
+            set.add(row.COLUMN_NAME);
+            indexedByTable.set(id, set);
+        }
+        const columnsByTable = new Map();
+        for (const row of columnRows.rows) {
+            const id = `${row.TABLE_SCHEMA}.${row.TABLE_NAME}`;
+            if (!wanted.has(id))
+                continue;
+            const list = columnsByTable.get(id) ?? [];
+            list.push(row);
+            columnsByTable.set(id, list);
+        }
+        const tables = tableRows.rows.map((t) => {
+            const id = `${t.TABLE_SCHEMA}.${t.TABLE_NAME}`;
+            const isView = t.TABLE_TYPE !== 'BASE TABLE';
+            const columns = (columnsByTable.get(id) ?? []).map((c) => ({
+                name: c.COLUMN_NAME,
+                /* The declared type verbatim, `tinyint(1)` included. MySQL has no
+                   boolean: BOOL and BOOLEAN are spellings of TINYINT(1), and the
+                   values really are 0 and 1. Rewriting the type to "boolean" would
+                   make `active = true` coerce to a JavaScript true and read as a
+                   promise the column does not make; left as declared, the same filter
+                   coerces to 1, which is what is stored. */
+                type: c.COLUMN_TYPE,
+                nullable: c.IS_NULLABLE === 'YES',
+                primaryKey: c.COLUMN_KEY === 'PRI',
+                references: refByColumn.get(`${id}.${c.COLUMN_NAME}`),
+                default: c.COLUMN_DEFAULT ?? undefined,
+                comment: c.COLUMN_COMMENT || undefined,
+                /* MySQL writes the vocabulary into the type itself — `enum('draft',
+                   'open')` — so the declared type already carries it. */
+                allowed: typeVocabulary(c.COLUMN_TYPE),
+            }));
+            return {
+                name: t.TABLE_NAME,
+                schema: t.TABLE_SCHEMA,
+                id,
+                columns,
+                /* InnoDB's TABLE_ROWS comes from a handful of random index dives, not
+                   a count: it is routinely out by a factor of two and can be out by an
+                   order of magnitude on a table with a long update history. Fine for
+                   "roughly how big is this" in a sidebar, wrong for anything a user
+                   would act on — which is why `count()` exists and this never feeds
+                   it. A view reports NULL, and stays undefined rather than becoming a
+                   confident zero. */
+                approxRows: t.TABLE_ROWS === null ? undefined : Math.max(0, Number(t.TABLE_ROWS) || 0),
+                /* MySQL puts the literal word VIEW in a view's TABLE_COMMENT rather
+                   than leaving it empty, so passing it through would caption every
+                   view in the sidebar with its own kind. */
+                comment: isView && t.TABLE_COMMENT === 'VIEW' ? undefined : t.TABLE_COMMENT || undefined,
+                isView,
+                // Always an array, because this always looked. Absent would mean the
+                // adapter did not, and the default order reads the difference.
+                indexed: [...(indexedByTable.get(id) ?? [])],
+            };
+        });
+        return {
+            label: this.label,
+            dialect: this.dialect,
+            tables,
+            foreignKeys,
+            readAt: new Date().toISOString(),
+        };
+    }
+    /*
+     * Why there is no `ddl()` here.
+     *
+     * MySQL has SHOW CREATE TABLE, and it is tempting: it includes indexes,
+     * foreign keys, the engine and the charset, all of which the catalog
+     * reconstruction leaves out. But it is the server re-rendering the data
+     * dictionary, not the statement its author wrote — comments are gone,
+     * type spellings are normalised, defaults are re-quoted — and the interface
+     * labels an adapter-supplied definition "the statement the database itself
+     * keeps, verbatim". Offering a faithful reconstruction under a promise of
+     * verbatim text would be a worse lie than the honest "Reconstructed" label
+     * the fallback already carries.
+     */
+    async query(request) {
+        const db = await this.conn();
+        const table = await this.assertTable(request.table);
+        const where = buildWhere(request.filter, MYSQL_STYLE);
+        const cols = request.columns?.length
+            ? request.columns.map((c) => MYSQL_STYLE.quote(c)).join(', ')
+            : '*';
+        const order = request.orderBy?.length
+            ? ' ORDER BY ' +
+                request.orderBy
+                    .map((o) => `${MYSQL_STYLE.quote(o.column)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`)
+                    .join(', ')
+            : '';
+        /* Every read is bounded. There is no code path that reaches the database
+           without a LIMIT, including one that forgot to ask for one. */
+        const limit = clampLimit(request.limit);
+        const text = `SELECT ${cols} FROM ${qualify(table)}${where.text}${order} LIMIT ? OFFSET ?`;
+        const params = [...where.params, rowCount(limit), rowCount(clampOffset(request.offset))];
+        const started = performance.now();
+        const result = await this.read(db, text, params);
+        const ms = Math.round(performance.now() - started);
+        return {
+            // From the field list rather than the first row, so an empty result
+            // still renders its headers instead of collapsing to nothing.
+            columns: result.fields.map((f) => f.name),
+            rows: result.rows.map(toJsonSafe),
+            ms,
+            sql: { text, params },
+        };
+    }
+    /**
+     * Run a compiled view.
+     *
+     * As in the other adapters, everything hard happened in `compileView`:
+     * paths resolved against the catalog, joins planned, values reduced to bound
+     * parameters. Nothing here needs to check that the tables exist, because the
+     * only identifiers that reach the quoting step are ones the catalog
+     * produced.
+     */
+    async runView(view, offset = 0) {
+        const db = await this.conn();
+        const schema = await this.schema();
+        /* Every read is bounded, views included: `compileView` runs the limit
+           through `clampLimit` and emits LIMIT unconditionally. */
+        const compiled = compileView(schema, view, MYSQL_STYLE, offset);
+        const params = bindRowCounts(compiled.text, compiled.params);
+        const started = performance.now();
+        const result = await this.read(db, compiled.text, params);
+        const ms = Math.round(performance.now() - started);
+        return {
+            columns: compiled.columns.map((c) => c.name),
+            rows: result.rows.map(toJsonSafe),
+            ms,
+            sql: { text: compiled.text, params },
+            resolved: compiled.columns,
+            joins: compiled.joins,
+        };
+    }
+    async runBreakdown(breakdown, offset = 0) {
+        const db = await this.conn();
+        const compiled = compileBreakdown(await this.schema(), breakdown, MYSQL_STYLE, offset);
+        /* The same treatment a view's LIMIT gets: mysql2 binds a number as a
+           string over the prepared protocol, and `LIMIT '20'` is a syntax error. */
+        const params = bindRowCounts(compiled.text, compiled.params);
+        const started = performance.now();
+        const result = await this.read(db, compiled.text, params);
+        return {
+            columns: compiled.columns.map((c) => c.name),
+            rows: result.rows.map(toJsonSafe),
+            ms: Math.round(performance.now() - started),
+            sql: { text: compiled.text, params },
+            resolved: compiled.columns,
+        };
+    }
+    async countBreakdown(breakdown) {
+        const db = await this.conn();
+        const compiled = compileBreakdownCount(await this.schema(), breakdown, MYSQL_STYLE);
+        const result = await this.read(db, compiled.text, compiled.params);
+        return Number(result.rows[0]?.n ?? 0);
+    }
+    async countView(view) {
+        const db = await this.conn();
+        const compiled = compileViewCount(await this.schema(), view, MYSQL_STYLE);
+        const result = await this.read(db, compiled.text, compiled.params);
+        return Number(result.rows[0]?.n ?? 0);
+    }
+    /* Introspection is four catalog queries; a view preview runs on every
+       keystroke. The registry refreshes by discarding the adapter, so a stale
+       cache cannot outlive an explicit reload. */
+    cachedSchema = null;
+    async schema() {
+        if (!this.cachedSchema)
+            this.cachedSchema = await this.introspect();
+        return this.cachedSchema;
+    }
+    /**
+     * `TABLE_ROWS` from `information_schema`.
+     *
+     * InnoDB computes this from a handful of index dives, so it can be out by a
+     * large factor — the manual says up to 50%, and in practice worse on a table
+     * with skewed key distribution. That is tolerable for "is this table big",
+     * which is the only question being asked of it, and it is why the number is
+     * labelled an estimate wherever it appears.
+     *
+     * NULL for a view, where it means "not applicable" rather than zero.
+     */
+    async estimateCount(table) {
+        const db = await this.conn();
+        const { schema, name } = await this.assertTable(table);
+        const { rows } = await this.read(db, `SELECT TABLE_ROWS FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`, [schema, name]);
+        const n = rows[0]?.TABLE_ROWS;
+        return n === null || n === undefined ? undefined : Math.max(0, Number(n));
+    }
+    async count(table, filter) {
+        const db = await this.conn();
+        const found = await this.assertTable(table);
+        const where = buildWhere(filter, MYSQL_STYLE);
+        const text = `SELECT COUNT(*) AS n FROM ${qualify(found)}${where.text}`;
+        const result = await this.read(db, text, where.params);
+        return Number(result.rows[0]?.n ?? 0);
+    }
+    /**
+     * The write path, on its own handle.
+     *
+     * `this.client` refuses writes for the life of the process, so browsing can
+     * never write no matter what the UI believes. A second connection — without
+     * the read-only session setting — is opened the first time an edit is
+     * actually applied.
+     *
+     * The guards are the SQLite adapter's, one for one, because an edit refused
+     * on SQLite and allowed on MySQL would mean the safety of a cell editor
+     * depended on which database it was pointed at.
+     */
+    async update(request) {
+        return this.writes.run(() => this.updateNow(request));
+    }
+    async updateNow(request) {
+        const db = await this.conn();
+        const table = await this.assertTable(request.table);
+        const id = `${table.schema}.${table.name}`;
+        /* MySQL will happily update through a simple view, and the update lands on
+           the table underneath. Refused here: what the editor showed and what
+           changed are then two different objects, and `isView` already tells the
+           interface this is read-only. */
+        if (table.isView) {
+            throw new Refusal(`${id} is a view, so no single row can be identified.`);
+        }
+        const meta = await this.read(db, `SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY
+         FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
+        ORDER BY ORDINAL_POSITION`, [table.schema, table.name]);
+        /* COLUMN_KEY is 'PRI' for primary key columns only — a unique index reads
+           'UNI' and a non-unique one 'MUL' — so this is the declared primary key
+           and not merely something unique-looking. An InnoDB table without one has
+           a hidden clustered key that cannot be named in a WHERE clause, which is
+           exactly the case this refuses. */
+        const pk = meta.rows.filter((c) => c.COLUMN_KEY === 'PRI').map((c) => c.COLUMN_NAME);
+        if (!pk.length)
+            throw new Refusal(`${id} has no primary key, so no single row can be identified.`);
+        const keyColumns = Object.keys(request.key);
+        /* The key must be the whole primary key and nothing else. Accepting a
+           partial key would let a two-column key match a whole group of rows,
+           and accepting extra columns would let the caller widen the match. */
+        const same = keyColumns.length === pk.length && pk.every((c) => keyColumns.includes(c));
+        if (!same) {
+            throw new Refusal(`Updating ${id} needs exactly its primary key (${pk.join(', ')}).`);
+        }
+        const entries = Object.entries(request.values ?? {});
+        if (!entries.length)
+            throw new Refusal('Nothing to update.');
+        const applied = {};
+        for (const [column, raw] of entries) {
+            const declared = meta.rows.find((c) => c.COLUMN_NAME === column);
+            if (!declared)
+                throw new Refusal(`${id} has no column called "${column}".`);
+            if (pk.includes(column)) {
+                // Editing a key in place silently repoints every row that referenced
+                // it, or fails on the constraint. Neither belongs behind an editor.
+                throw new Refusal(`"${column}" is part of the primary key and cannot be edited here.`);
+            }
+            /* Coerced against the declared type, because everything typed into a
+               text box arrives as a string — including "17901" for a DECIMAL. */
+            applied[column] = coerceForColumn(declared.COLUMN_TYPE || '', raw);
+            if (applied[column] === null && declared.IS_NULLABLE === 'NO') {
+                throw new Refusal(`"${column}" is NOT NULL and cannot be emptied.`);
+            }
+        }
+        const filter = {
+            groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
+        };
+        /* Pre-flight. The count runs on the read-only handle, so the check cannot
+           itself have side effects, and a filter matching anything other than one
+           row stops here rather than at the UPDATE. */
+        const matches = await this.count(id, filter);
+        if (matches !== 1) {
+            throw new Refusal(`Refused: that key matches ${matches} rows, not 1. An update is only allowed when it is certain which row it changes.`);
+        }
+        const where = buildWhere(filter, MYSQL_STYLE);
+        const assignments = Object.keys(applied).map((c) => `${MYSQL_STYLE.quote(c)} = ?`).join(', ');
+        const text = `UPDATE ${qualify(table)} SET ${assignments}${where.text}`;
+        const params = [...Object.values(applied), ...where.params];
+        const write = await this.writeHandle();
+        const [result] = await write.execute(text, params);
+        /* mysql2 connects with CLIENT_FOUND_ROWS, so `affectedRows` counts the
+           rows matched rather than the rows whose bytes changed. Without it,
+           saving a cell without changing its value would report zero rows and the
+           editor would tell the user the write failed. */
+        return {
+            affected: Number(result?.affectedRows ?? 0),
+            applied,
+            sql: { text, params },
+        };
+    }
+    /**
+     * Add one row.
+     *
+     * The guards are `update`'s where they apply, with the key rules inverted:
+     * a primary key may be supplied or left for AUTO_INCREMENT to assign.
+     * MySQL 8 has no RETURNING, so the stored row is read back by its key —
+     * `insertId` for an auto-assigned one, the supplied values otherwise. A
+     * table where neither identifies the row (a composite key only partly
+     * supplied) still inserts; it just cannot be read back, and the result
+     * says so by carrying no row rather than guessing at one.
+     */
+    async insert(request) {
+        return this.writes.run(() => this.insertNow(request));
+    }
+    async insertNow(request) {
+        const db = await this.conn();
+        const table = await this.assertTable(request.table);
+        const id = `${table.schema}.${table.name}`;
+        if (table.isView) {
+            throw new Refusal(`${id} is a view. Insert into the table underneath it.`);
+        }
+        const meta = await this.read(db, `SELECT COLUMN_NAME, COLUMN_TYPE, IS_NULLABLE, COLUMN_KEY
+         FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?
+        ORDER BY ORDINAL_POSITION`, [table.schema, table.name]);
+        const entries = Object.entries(request.values ?? {});
+        if (!entries.length)
+            throw new Refusal('Nothing to insert. Name at least one column.');
+        const applied = {};
+        for (const [column, raw] of entries) {
+            const declared = meta.rows.find((c) => c.COLUMN_NAME === column);
+            if (!declared)
+                throw new Refusal(`${id} has no column called "${column}".`);
+            applied[column] = coerceForColumn(declared.COLUMN_TYPE || '', raw);
+            if (applied[column] === null && declared.IS_NULLABLE === 'NO') {
+                throw new Refusal(`"${column}" is NOT NULL and cannot be null. Leave it out to use its default, if it has one.`);
+            }
+        }
+        const columns = Object.keys(applied);
+        const text = `INSERT INTO ${qualify(table)} (${columns.map((c) => MYSQL_STYLE.quote(c)).join(', ')})`
+            + ` VALUES (${columns.map(() => '?').join(', ')})`;
+        const params = Object.values(applied);
+        const write = await this.writeHandle();
+        const [result] = await write.execute(text, params);
+        const pk = meta.rows.filter((c) => c.COLUMN_KEY === 'PRI').map((c) => c.COLUMN_NAME);
+        const assigned = Number(result?.insertId ?? 0);
+        const key = {};
+        if (pk.every((c) => applied[c] !== undefined && applied[c] !== null)) {
+            for (const c of pk)
+                key[c] = applied[c];
+        }
+        else if (pk.length === 1 && assigned > 0) {
+            key[pk[0]] = assigned;
+        }
+        let row;
+        if (pk.length && pk.every((c) => key[c] !== undefined)) {
+            const where = buildWhere({ groups: [pk.map((column) => ({ column, op: '=', value: key[column] }))] }, MYSQL_STYLE);
+            const back = await this.read(db, `SELECT * FROM ${qualify(table)}${where.text}`, where.params);
+            row = back.rows[0];
+        }
+        return { key, row, applied, sql: { text, params } };
+    }
+    /**
+     * EXPLAIN, tabular, one line per row.
+     *
+     * Plain EXPLAIN rather than FORMAT=TREE, because MariaDB does not speak
+     * TREE and this adapter serves both. Each row becomes its columns said as
+     * `name=value` pairs with the empties dropped — not as pretty as the tree,
+     * and the same words on every engine this connects to. EXPLAIN plans and
+     * never executes, on the ordinary read connection.
+     */
+    async explainSql(request) {
+        const stacked = refuseStacked(request.text);
+        if (stacked)
+            throw new Error(stacked);
+        const db = await this.conn();
+        const started = performance.now();
+        const { rows } = await this.read(db, `EXPLAIN ${trimStatement(request.text)}`, (request.params ?? []));
+        const plan = rows.map((r) => Object.entries(r)
+            .filter(([, v]) => v !== null && v !== undefined && v !== '')
+            .map(([k, v]) => `${k}=${v}`)
+            .join('  '));
+        return { plan, ms: Math.round(performance.now() - started) };
+    }
+    /**
+     * What the columns hold, by looking.
+     *
+     * MySQL keeps index cardinality, not null shares — histograms exist but
+     * only where someone ran ANALYZE ... UPDATE HISTOGRAM — so this reads the
+     * table the way the SQLite adapter does, with the same escape hatch:
+     * above `scanAtMost` rows it samples every k-th row of a single integer
+     * key, or the first N where the key does not allow the arithmetic, and
+     * `source` says which happened.
+     */
+    async profile(table, limits) {
+        const db = await this.conn();
+        const found = await this.assertTable(table);
+        const id = `${found.schema}.${found.name}`;
+        const schema = await this.schema();
+        const meta = schema.tables.find((t) => t.id === id);
+        if (!meta)
+            throw new Error(`No table or view called "${id}" on this connection.`);
+        const q = (c) => MYSQL_STYLE.quote(c);
+        const scanAtMost = limits?.scanAtMost ?? 200_000;
+        const sampleSize = limits?.sampleSize ?? 100_000;
+        const started = performance.now();
+        const counted = await this.read(db, `SELECT COUNT(*) AS n FROM ${qualify(found)}`, []);
+        const total = Number(counted.rows[0]?.n ?? 0);
+        let from = qualify(found);
+        let source = 'scan';
+        if (total > scanAtMost) {
+            source = 'sample';
+            const k = Math.max(2, Math.ceil(total / sampleSize));
+            const pk = meta.columns.filter((c) => c.primaryKey);
+            // Hashed before the stride, for the reason the SQLite adapter gives:
+            // periodic data and a bare modulo sample each other.
+            from = pk.length === 1 && /int/i.test(pk[0].type)
+                ? `(SELECT * FROM ${qualify(found)} WHERE ((${q(pk[0].name)} * 2654435761) & 0x7fffffff) % ${k} = 0) AS sampled`
+                : `(SELECT * FROM ${qualify(found)} LIMIT ${sampleSize}) AS sampled`;
+        }
+        const aggs = meta.columns.map((c, i) => `COUNT(${q(c.name)}) AS n${i}, COUNT(DISTINCT ${q(c.name)}) AS d${i}, `
+            + `MIN(${q(c.name)}) AS mn${i}, MAX(${q(c.name)}) AS mx${i}`);
+        const row = (await this.read(db, `SELECT COUNT(*) AS total${aggs.length ? `, ${aggs.join(', ')}` : ''} FROM ${from}`, [])).rows[0] ?? {};
+        const basis = Number(row.total ?? 0);
+        const columns = [];
+        for (const [i, c] of meta.columns.entries()) {
+            const nonNull = Number(row[`n${i}`] ?? 0);
+            const distinct = Number(row[`d${i}`] ?? 0);
+            const profiled = {
+                column: c.name,
+                type: c.type,
+                nullFrac: basis ? (basis - nonNull) / basis : 0,
+                distinct,
+                min: row[`mn${i}`] ?? undefined,
+                max: row[`mx${i}`] ?? undefined,
+            };
+            if (nonNull > 0 && distinct < nonNull) {
+                const top = await this.read(db, `SELECT ${q(c.name)} AS v, COUNT(*) AS n FROM ${from} `
+                    + `WHERE ${q(c.name)} IS NOT NULL GROUP BY ${q(c.name)} ORDER BY n DESC, v LIMIT 5`, []);
+                profiled.common = top.rows.map((t) => ({ value: t.v, frac: Number(t.n) / basis }));
+            }
+            columns.push(profiled);
+        }
+        return {
+            table: id,
+            rows: total,
+            columns,
+            source,
+            ...(source === 'sample' ? { sampled: basis } : {}),
+            ms: Math.round(performance.now() - started),
+        };
+    }
+    /**
+     * Run a statement the user wrote.
+     *
+     * On a **connection of its own, thrown away afterwards** — which is a
+     * heavier answer than the other two adapters need, and MySQL earns it.
+     *
+     * The obvious approach was `START TRANSACTION READ ONLY`, the way the
+     * Postgres adapter does it. Testing it against MySQL 8.4 showed it does not
+     * hold, in two steps neither of which is exotic:
+     *
+     *   1. `SET SESSION TRANSACTION READ WRITE` succeeds and **persists**. MySQL
+     *      session variables are not transactional, so the `ROLLBACK` that
+     *      follows does not undo it — unlike Postgres, where a plain `SET` inside
+     *      a transaction is rolled back with everything else.
+     *   2. `DROP TABLE` then performs an *implicit commit*, ending the read-only
+     *      transaction before the statement runs, so the DDL executes under the
+     *      session mode the first step had just flipped.
+     *
+     * Two statements, two calls, and a dropped table — observed, not theorised.
+     *
+     * A connection per statement closes it without needing to know that story.
+     * Session state cannot outlive the run that set it, so no statement can
+     * arrange the conditions for the next one; and with autocommit and the
+     * session opened read-only, DDL is refused by the session mode rather than by
+     * a transaction that DDL can commit its way out of. The cost is a connection
+     * per run, which for a statement someone typed and is waiting on is nothing.
+     *
+     * Writes are the other path and keep the persistent write handle: it exists
+     * to write, and there is nothing to isolate it from.
+     */
+    async runSql(request) {
+        const stacked = refuseStacked(request.text);
+        if (stacked)
+            throw new Error(stacked);
+        const limit = clampLimit(request.limit);
+        const bounded = !request.write && looksWrappable(request.text);
+        const text = bounded ? boundStatement(request.text, limit) : trimStatement(request.text);
+        const started = performance.now();
+        if (request.write) {
+            const db = await this.writeHandle();
+            const [rows] = (await db.query({ sql: text }));
+            return {
+                columns: [], rows: [], ms: Math.round(performance.now() - started),
+                truncated: false, bounded: false,
+                affected: Number(rows?.affectedRows ?? 0),
+                sql: { text, params: [] },
+            };
+        }
+        const db = await this.open(true);
+        try {
+            /* `rowsAsArray` so two output columns of the same name keep both values;
+               the default object rows would let the second overwrite the first. */
+            let wrapped = bounded;
+            let [rows, fields] = (await db
+                .query({ sql: text, rowsAsArray: true })
+                .catch(async (err) => {
+                /* Not every legal statement survives being made a derived table.
+                   MySQL refuses one whose columns share a name — `select id, id` is
+                   fine on its own and not fine inside `FROM (…)` — and there are
+                   others. Rather than enumerate them, the wrap is treated as an
+                   optimisation that can fail: run the statement as written and say
+                   the limit was not applied.
+      
+                   Safe to run twice because this connection cannot write, and the
+                   second error is the better one to report anyway: it is about the
+                   statement someone typed rather than about our wrapper. */
+                if (!bounded)
+                    throw err;
+                wrapped = false;
+                return db.query({ sql: trimStatement(request.text), rowsAsArray: true });
+            }));
+            const all = Array.isArray(rows) ? rows : [];
+            const truncated = all.length > limit;
+            return {
+                columns: dedupe((fields ?? []).map((f) => f.name)),
+                rows: (truncated ? all.slice(0, limit) : all).map((row) => (Array.isArray(row) ? row : [row]).map(valueSafe)),
+                ms: Math.round(performance.now() - started),
+                truncated,
+                bounded: wrapped,
+                sql: { text: wrapped ? text : trimStatement(request.text), params: [] },
+            };
+        }
+        finally {
+            // Whatever the statement did to this session dies here.
+            await db.end().catch(() => { });
+        }
+    }
+    /**
+     * Delete one row. The guards are the SQLite adapter's, one for one.
+     *
+     * An edit refused on SQLite and allowed on MySQL would mean the safety of an
+     * editor depended on which database it was pointed at. The extra check here
+     * is the same one `update` carries: MySQL will delete *through* a simple view
+     * onto the table underneath, which is not what someone looking at a view
+     * expects to happen.
+     */
+    async remove(request) {
+        return this.writes.run(() => this.removeNow(request));
+    }
+    async removeNow(request) {
+        const found = await this.assertTable(request.table);
+        const { schema, name, isView } = found;
+        const id = `${schema}.${name}`;
+        if (isView)
+            throw new Refusal(`${id} is a view, so no single row can be identified.`);
+        const db = await this.conn();
+        const { rows: cols } = await this.read(db, `SELECT COLUMN_NAME, COLUMN_KEY FROM information_schema.COLUMNS
+        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`, [schema, name]);
+        const pk = cols.filter((c) => c.COLUMN_KEY === 'PRI').map((c) => c.COLUMN_NAME);
+        if (!pk.length)
+            throw new Refusal(`${id} has no primary key, so no single row can be identified.`);
+        const keyColumns = Object.keys(request.key);
+        const same = keyColumns.length === pk.length && pk.every((c) => keyColumns.includes(c));
+        if (!same) {
+            throw new Refusal(`Deleting from ${id} needs exactly its primary key (${pk.join(', ')}).`);
+        }
+        const filter = {
+            groups: [pk.map((column) => ({ column, op: '=', value: request.key[column] }))],
+        };
+        const matches = await this.count(request.table, filter);
+        if (matches !== 1) {
+            throw new Refusal(`Refused: that key matches ${matches} rows, not 1. A delete is only allowed when it is certain which row it removes.`);
+        }
+        const where = buildWhere(filter, MYSQL_STYLE);
+        const text = `DELETE FROM ${qualify(found)}${where.text}`;
+        const write = await this.writeHandle();
+        const [result] = (await write.execute(text, where.params));
+        return { affected: Number(result?.affectedRows ?? 0), sql: { text, params: where.params } };
+    }
+    async writeHandle() {
+        if (!this.writeClient)
+            this.writeClient = await this.open(false);
+        return this.writeClient;
+    }
+    /**
+     * Several writes as one, or none of them.
+     *
+     * `BEGIN` / `COMMIT` on the write connection, through `query` rather than
+     * `execute`: MySQL's prepared-statement protocol will not take a
+     * transaction-control statement, and these carry no parameters to prepare.
+     *
+     * Worth naming what this cannot promise on this engine: MySQL commits DDL
+     * implicitly, so a `CREATE TABLE` reached through raw SQL inside one of
+     * these ends the transaction where it stands. Nothing here issues DDL, and
+     * a caller who does through `sql` has left the guarantee behind.
+     */
+    async transaction(run) {
+        return this.writes.run(async () => {
+            const write = await this.writeHandle();
+            await write.query({ sql: 'BEGIN' });
+            try {
+                const out = await run({
+                    insert: (r) => this.insertNow(r),
+                    remove: (r) => this.removeNow(r),
+                    update: (r) => this.updateNow(r),
+                });
+                await write.query({ sql: 'COMMIT' });
+                return out;
+            }
+            catch (err) {
+                await write.query({ sql: 'ROLLBACK' }).catch(() => { });
+                throw err;
+            }
+        });
+    }
+    async close() {
+        const open = [this.client, this.writeClient].filter((c) => Boolean(c));
+        this.client = null;
+        this.writeClient = null;
+        await Promise.allSettled(open.map((c) => c.end()));
+    }
+    /**
+     * Identifiers cannot be bound, so a table name is checked against the
+     * catalog before it is quoted into a statement. The check is a parameterised
+     * query, which means the untrusted string never reaches SQL as syntax.
+     *
+     * An unqualified name means the database the connection is in, which is what
+     * `USE shop; SELECT * FROM invoice` means to anyone who has used MySQL.
+     */
+    async assertTable(id) {
+        const db = await this.conn();
+        const dot = id.indexOf('.');
+        const schema = dot === -1 ? (this.databases[0] ?? '') : id.slice(0, dot);
+        const name = dot === -1 ? id : id.slice(dot + 1);
+        const found = await this.read(db, `SELECT TABLE_TYPE FROM information_schema.TABLES
+        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = ?`, [schema, name]);
+        /* Restricted to the browsed set as well as to what exists: a server hosts
+           every database it has in one catalog, and a name typed into the URL bar
+           must not become a way to read one this session never opened. */
+        if (!found.rows.length || !this.databases.includes(schema)) {
+            throw new Error(`No table or view called "${id}" in this database.`);
+        }
+        return { schema, name, isView: found.rows[0].TABLE_TYPE !== 'BASE TABLE' };
+    }
+    /** One place that unwraps mysql2's `[rows, fields]` pair. */
+    async read(db, text, params = []) {
+        const [rows, fields] = await db.execute(text, params);
+        return {
+            rows: (Array.isArray(rows) ? rows : []),
+            fields: (Array.isArray(fields) ? fields : []),
+        };
+    }
+}
+/** `` `shop`.`invoice` `` — two identifiers, never one containing a dot. */
+function qualify(table) {
+    return `${MYSQL_STYLE.quote(table.schema)}.${MYSQL_STYLE.quote(table.name)}`;
+}
+/**
+ * A row count on its way into a placeholder, as digits rather than a number.
+ *
+ * mysql2 encodes every JavaScript number in the prepared-statement protocol as
+ * a DOUBLE, and MySQL refuses a DOUBLE where it wants a row count: `LIMIT ?`
+ * bound to 20 fails with ER_WRONG_ARGUMENTS (1210) instead of returning twenty
+ * rows. A decimal string is sent as VAR_STRING, which the server converts, and
+ * the alternative — writing the number into the statement text — would put a
+ * value in the SQL for the sake of a driver quirk.
+ *
+ * Safe by construction rather than by escaping: the only callers pass the
+ * output of `clampLimit` or `clampOffset`, which are integers this process
+ * computed and never anything a user typed.
+ */
+function rowCount(n) {
+    return String(Math.floor(n));
+}
+/**
+ * The same fix, applied to a statement `compileView` built.
+ *
+ * The view compiler ends every statement it produces with `LIMIT ? OFFSET ?`
+ * and pushes the two clamped integers last. Matching on the text rather than
+ * trusting that is what makes this exact: if the compiler ever stops emitting
+ * that tail, the parameters are left alone and the failure is a loud one from
+ * the server, not a filter value quietly changing type.
+ */
+function bindRowCounts(text, params) {
+    if (params.length < 2 || !/LIMIT \?\s+OFFSET \?\s*$/.test(text))
+        return params;
+    const out = [...params];
+    const tail = out.length - 2;
+    if (typeof out[tail] !== 'number' || typeof out[tail + 1] !== 'number')
+        return params;
+    out[tail] = rowCount(out[tail]);
+    out[tail + 1] = rowCount(out[tail + 1]);
+    return out;
+}
+/**
+ * Load `mysql2` on demand.
+ *
+ * Imported lazily, and through a variable, so the driver is only required when
+ * someone actually opens a MySQL URL. The indirection also stops the type
+ * checker demanding the package be installed to compile this file.
+ */
+async function driver() {
+    const specifier = 'mysql2/promise';
+    const mysql = (await import(specifier).catch(() => {
+        throw new Error('MySQL support needs the "mysql2" package. Install it with: npm install mysql2');
+    }));
+    const createConnection = mysql.createConnection ?? mysql.default?.createConnection;
+    if (!createConnection) {
+        throw new Error('Could not find a createConnection export in the "mysql2" package.');
+    }
+    return createConnection;
+}
+/** Keep the password out of the label, the logs and the UI. */
+function redact(connectionString) {
+    try {
+        const url = new URL(connectionString);
+        return `${url.hostname}${url.pathname}`;
+    }
+    catch {
+        return 'mysql';
+    }
+}
+/** BigInt and Buffer are common in drivers and neither survives JSON. */
+/** One value, made safe to send as JSON. See `toJsonSafe` for the row form. */
+function valueSafe(v) {
+    if (typeof v === 'bigint')
+        return v.toString();
+    if (v instanceof Uint8Array)
+        return `<${v.byteLength} bytes>`;
+    if (v instanceof Date)
+        return v.toISOString();
+    return v;
+}
+function toJsonSafe(row) {
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+        if (typeof v === 'bigint')
+            out[k] = v.toString();
+        else if (v instanceof Uint8Array)
+            out[k] = `<${v.byteLength} bytes>`;
+        else if (v instanceof Date)
+            out[k] = v.toISOString();
+        else
+            out[k] = v;
+    }
+    return out;
+}