hive-am 1.3.0 → 1.5.0

package/server/dist/objects/database.js

@@ -252,6 +252,69 @@ async function openMssql(cfg, database) {
                 r.query(sql);
             });
         },
+        /**
+         * The plan of a statement, without running it. SHOWPLAN is a setting of the connection that has to be switched on by a batch of its own (the driver
+         * sends an ordinary call inside sp_executesql, where the setting does not outlast the call and the statement would RUN). It is done inside a
+         * transaction that is always rolled back, so that nothing can stay changed even if the setting did not take.
+         */
+        async explain(statement, o) {
+            const tx = new mssql.Transaction(pool);
+            await tx.begin();
+            try {
+                const batch = (sql) => { const r = new mssql.Request(tx); r.arrayRowMode = true; return r.batch(sql); };
+                await batch('SET SHOWPLAN_TEXT ON');
+                let res;
+                try {
+                    res = await Promise.race([batch(statement), new Promise((_, no) => setTimeout(() => no(new Error(`The plan took more than ${Math.round(o.timeoutMs / 1000)} s`)), o.timeoutMs).unref())]);
+                }
+                finally {
+                    await batch('SET SHOWPLAN_TEXT OFF').catch(() => undefined);
+                }
+                const set = (res.recordset ?? []);
+                const cols = res.recordset?.columns ? Object.values(res.recordset.columns).sort((a, b) => a.index - b.index).map((x) => ({ name: x.name })) : [{ name: 'plan' }];
+                return { columns: cols, rows: set.slice(0, o.max), truncated: set.length > o.max };
+            }
+            finally {
+                try {
+                    await tx.rollback();
+                }
+                catch { /* nothing left to undo */ }
+            }
+        },
+        // The statements of a script run inside one transaction of the driver (a BEGIN sent as a statement would end with the batch that carries it).
+        async script(statements, o) {
+            const tx = new mssql.Transaction(pool);
+            await tx.begin();
+            const out = [];
+            try {
+                for (let i = 0; i < statements.length; i++) {
+                    try {
+                        const r = new mssql.Request(tx);
+                        r.arrayRowMode = true;
+                        const res = await Promise.race([r.query(statements[i]), new Promise((_, no) => setTimeout(() => { try {
+                                r.cancel();
+                            }
+                            catch { /* done */ } no(new Error(`The script took more than ${Math.round(o.timeoutMs / 1000)} s`)); }, o.timeoutMs).unref())]);
+                        const set = res.recordset;
+                        const cols = set ? Object.values(set.columns).sort((a, b) => a.index - b.index).map((x) => ({ name: x.name })) : [];
+                        const rows = set ?? [];
+                        out.push({ columns: cols, rows: rows.slice(0, o.max), truncated: rows.length > o.max, affected: cols.length === 0 ? res.rowsAffected.reduce((a, b) => a + b, 0) : undefined });
+                    }
+                    catch (e) {
+                        throw new Error(`Statement ${i + 1} failed and nothing was changed: ${e instanceof Error ? e.message : e}`);
+                    }
+                }
+                await tx.commit();
+            }
+            catch (e) {
+                try {
+                    await tx.rollback();
+                }
+                catch { /* already rolled back */ }
+                throw e;
+            }
+            return out;
+        },
         async close() { try {
             await pool.close();
         }
@@ -269,13 +332,22 @@ let db, out;
 try {
   db = new Database(w.file, { readonly: w.readOnly, fileMustExist: true, ...(w.timeout !== undefined ? { timeout: w.timeout } : {}) });
   for (const [k, v] of Object.entries(w.pragmas)) db.pragma(k + ' = ' + v);
-  const stmt = db.prepare(w.sql);
-  if (stmt.reader) {
-    const columns = stmt.columns().map((c) => ({ name: c.name })); stmt.raw(true);
-    const rows = []; let truncated = false;
-    for (const r of stmt.iterate()) { if (rows.length >= w.max) { truncated = true; break; } rows.push(r.map((v) => typeof v === 'bigint' ? v.toString() : (Buffer.isBuffer(v) ? { $blob: v.toString('base64') } : v))); }
-    out = { ok: true, columns, rows, truncated };
-  } else { const r = stmt.run(); out = { ok: true, columns: [], rows: [], truncated: false, affected: r.changes }; }
+  const one = (sql) => {
+    const stmt = db.prepare(sql);
+    if (stmt.reader) {
+      const columns = stmt.columns().map((c) => ({ name: c.name })); stmt.raw(true);
+      const rows = []; let truncated = false;
+      for (const r of stmt.iterate()) { if (rows.length >= w.max) { truncated = true; break; } rows.push(r.map((v) => typeof v === 'bigint' ? v.toString() : (Buffer.isBuffer(v) ? { $blob: v.toString('base64') } : v))); }
+      return { columns, rows, truncated };
+    }
+    const r = stmt.run(); return { columns: [], rows: [], truncated: false, affected: r.changes };
+  };
+  if (w.script) {
+    // All the statements in one transaction: one failing undoes the others.
+    db.exec('BEGIN'); const results = []; let at = 0;
+    try { for (; at < w.script.length; at++) results.push(one(w.script[at])); db.exec('COMMIT'); out = { ok: true, script: results }; }
+    catch (e) { try { db.exec('ROLLBACK'); } catch {} out = { ok: false, error: String(e && e.message || e), at: at + 1 }; }
+  } else out = { ok: true, ...one(w.sql) };
 } catch (e) { out = { ok: false, error: String(e && e.message || e) }; }
 try { db && db.close(); } catch {}
 process.stdout.write(JSON.stringify(out));
@@ -288,32 +360,42 @@ function openSqlite(cfg) {
     // The values were checked when the object was saved (a number, true/false or one of a few words), so they are safe in a PRAGMA.
     const { timeout, ...rest } = plain(propValues('sqlite', cfg.props));
     const pragmas = Object.fromEntries(Object.entries(rest).map(([k, v]) => [k, typeof v === 'boolean' ? (v ? 1 : 0) : v]));
+    const blobs = (r) => r.map((v) => (v && typeof v === 'object' && '$blob' in v ? Buffer.from(v.$blob, 'base64') : v));
+    const shape = (m) => ({ columns: m.columns, rows: m.rows.map(blobs), truncated: m.truncated, affected: m.affected });
+    /** One run of the child process: the message it printed, or an error when it ended without one, took too long or printed too much. */
+    const call = (payload, o) => new Promise((ok, no) => {
+        const child = spawn(process.execPath, ['-e', SQLITE_CHILD], { stdio: ['pipe', 'pipe', 'ignore'] });
+        const chunks = [];
+        let size = 0, done = false;
+        const finish = (err, v) => { if (done)
+            return; done = true; clearTimeout(timer); child.kill('SIGKILL'); err ? no(err) : ok(v); };
+        const timer = setTimeout(() => finish(new Error(`The query took more than ${Math.round(o.timeoutMs / 1000)} s`)), o.timeoutMs);
+        child.stdout.on('data', (c) => { size += c.length; if (size > SQLITE_MAX_OUT)
+            finish(new Error('The result is too big: use fewer rows or columns'));
+        else
+            chunks.push(c); });
+        child.once('error', (e) => finish(e));
+        child.once('close', () => {
+            if (done)
+                return;
+            try {
+                finish(undefined, JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            }
+            catch {
+                finish(new Error('The SQLite process ended without an answer'));
+            }
+        });
+        child.stdin.end(JSON.stringify({ mod, file: cfg.file, max: o.max, readOnly: o.readOnly, timeout, pragmas, ...payload }));
+    });
     return {
-        run: (sql, o) => new Promise((ok, no) => {
-            const child = spawn(process.execPath, ['-e', SQLITE_CHILD], { stdio: ['pipe', 'pipe', 'ignore'] });
-            const chunks = [];
-            let size = 0, done = false;
-            const finish = (err, v) => { if (done)
-                return; done = true; clearTimeout(timer); child.kill('SIGKILL'); err ? no(err) : ok(v); };
-            const timer = setTimeout(() => finish(new Error(`The query took more than ${Math.round(o.timeoutMs / 1000)} s`)), o.timeoutMs);
-            child.stdout.on('data', (c) => { size += c.length; if (size > SQLITE_MAX_OUT)
-                finish(new Error('The result is too big: use fewer rows or columns'));
-            else
-                chunks.push(c); });
-            child.once('error', (e) => finish(e));
-            child.once('close', () => {
-                if (done)
-                    return;
-                try {
-                    const m = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-                    m.ok ? finish(undefined, { columns: m.columns, rows: m.rows.map((r) => r.map((v) => (v && typeof v === 'object' && '$blob' in v ? Buffer.from(v.$blob, 'base64') : v))), truncated: m.truncated, affected: m.affected }) : finish(new Error(m.error));
-                }
-                catch {
-                    finish(new Error('The SQLite process ended without an answer'));
-                }
-            });
-            child.stdin.end(JSON.stringify({ mod, file: cfg.file, sql, max: o.max, readOnly: o.readOnly, timeout, pragmas }));
-        }),
+        run: async (sql, o) => { const m = await call({ sql }, o); if (!m.ok)
+            throw new Error(m.error); return shape(m); },
+        script: async (statements, o) => {
+            const m = await call({ script: statements }, o);
+            if (!m.ok)
+                throw new Error(m.at ? `Statement ${m.at} failed and nothing was changed: ${m.error}` : m.error);
+            return m.script.map(shape);
+        },
         close: async () => undefined,
     };
 }
@@ -423,8 +505,11 @@ export async function dbColumns(cfg, p) {
         FROM information_schema.columns c WHERE c.table_schema = ${lit(schema)} AND c.table_name = ${lit(table)} ORDER BY c.ordinal_position`))
                 .map((r) => ({ name: String(r[0]), type: String(r[1]), nullable: r[2] === 'YES', key: r[3] ? String(r[3]) : undefined, default: r[4] === null ? null : String(r[4]) }));
         }
-        return (await q(`SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_DEFAULT FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = ${lit(schema)} AND TABLE_NAME = ${lit(table)} ORDER BY ORDINAL_POSITION`))
-            .map((r) => ({ name: String(r[0]), type: String(r[1]), nullable: r[2] === 'YES', default: r[3] === null ? null : String(r[3]) }));
+        return (await q(`SELECT c.COLUMN_NAME, c.DATA_TYPE, c.IS_NULLABLE, c.COLUMN_DEFAULT,
+      (SELECT TOP 1 'PRI' FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS tc JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE k ON k.CONSTRAINT_NAME = tc.CONSTRAINT_NAME AND k.TABLE_SCHEMA = tc.TABLE_SCHEMA
+        WHERE tc.CONSTRAINT_TYPE = 'PRIMARY KEY' AND tc.TABLE_SCHEMA = c.TABLE_SCHEMA AND tc.TABLE_NAME = c.TABLE_NAME AND k.COLUMN_NAME = c.COLUMN_NAME)
+      FROM INFORMATION_SCHEMA.COLUMNS c WHERE c.TABLE_SCHEMA = ${lit(schema)} AND c.TABLE_NAME = ${lit(table)} ORDER BY c.ORDINAL_POSITION`))
+            .map((r) => ({ name: String(r[0]), type: String(r[1]), nullable: r[2] === 'YES', key: r[4] ? String(r[4]) : undefined, default: r[3] === null ? null : String(r[3]) }));
     });
 }
 // ---- state -----------------------------------------------------------------------------------------------------------------------------
@@ -449,3 +534,380 @@ export async function dbState(id, cfg) {
     seen.set(id, { at: Date.now(), state });
     return state;
 }
+// ---- what an agent needs on top of that ------------------------------------------------------------------------------------------------
+/** Splits a script into its statements, the way the engine would read it: a `;` inside a quote, a comment or a dollar-quoted body does not end one. */
+export function splitStatements(sql, engine) {
+    const out = [];
+    let cur = '', i = 0;
+    const push = () => { const t = cur.trim(); if (t)
+        out.push(t); cur = ''; };
+    while (i < sql.length) {
+        const c = sql[i], n = sql[i + 1];
+        if (c === '-' && n === '-') {
+            const e = sql.indexOf('\n', i);
+            const j = e < 0 ? sql.length : e;
+            cur += sql.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (c === '#' && engine === 'mysql') {
+            const e = sql.indexOf('\n', i);
+            const j = e < 0 ? sql.length : e;
+            cur += sql.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (c === '/' && n === '*') {
+            const e = sql.indexOf('*/', i + 2);
+            const j = e < 0 ? sql.length : e + 2;
+            cur += sql.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (c === '$' && engine === 'postgresql') {
+            const tag = /^\$[A-Za-z_]*\$/.exec(sql.slice(i))?.[0];
+            if (tag) {
+                const e = sql.indexOf(tag, i + tag.length);
+                const j = e < 0 ? sql.length : e + tag.length;
+                cur += sql.slice(i, j);
+                i = j;
+                continue;
+            }
+        }
+        if (c === "'" || c === '"' || c === '`') {
+            const q = c;
+            let j = i + 1;
+            while (j < sql.length) {
+                if (sql[j] === '\\' && q !== '`' && engine === 'mysql') {
+                    j += 2;
+                    continue;
+                }
+                if (sql[j] === q) {
+                    if (sql[j + 1] === q) {
+                        j += 2;
+                        continue;
+                    }
+                    break;
+                }
+                j++;
+            }
+            cur += sql.slice(i, j + 1);
+            i = j + 1;
+            continue;
+        }
+        if (c === '[' && engine === 'mssql') {
+            const e = sql.indexOf(']', i);
+            const j = e < 0 ? sql.length : e + 1;
+            cur += sql.slice(i, j);
+            i = j;
+            continue;
+        }
+        if (c === ';') {
+            push();
+            i++;
+            continue;
+        }
+        cur += c;
+        i++;
+    }
+    push();
+    return out;
+}
+/**
+ * True when the text has a statement that starts with DROP or TRUNCATE, or an `ALTER ... DROP ...`. Comments and what is inside quotes are
+ * ignored. It is a guardrail, not a sandbox: a DELETE without a WHERE, a CALL, a PostgreSQL DO block or a stored procedure are not seen.
+ */
+export function isDestructive(sql) {
+    return bare(sql).split(';').some((st) => {
+        const t = st.trim().toLowerCase();
+        return /^(drop|truncate)\b/.test(t) || (/^alter\b/.test(t) && /\bdrop\b/.test(t));
+    });
+}
+/** The text with the literal of a password in it replaced by `***` (CREATE USER … IDENTIFIED BY '…', ALTER USER … PASSWORD '…', WITH PASSWORD = '…'). */
+export function maskSecretsInSql(sql) {
+    const lit = `('(?:[^'\\\\]|\\\\.|'')*'|"(?:[^"\\\\]|\\\\.|"")*")`;
+    return String(sql)
+        .replace(new RegExp(`(\\bidentified\\s+(?:with\\s+\\w+\\s+)?by\\s+(?:password\\s+)?)${lit}`, 'gi'), "$1'***'")
+        .replace(new RegExp(`(\\b(?:encrypted\\s+|unencrypted\\s+)?password\\s*(?:=\\s*|\\(\\s*)?(?:password\\s*\\(\\s*)?)${lit}`, 'gi'), "$1'***'")
+        .replace(new RegExp(`(\\bpwdencrypt\\s*\\(\\s*)${lit}`, 'gi'), "$1'***'");
+}
+/** Quotes a table or schema name for the engine. */
+export const quoteIdent = (engine, id) => engine === 'mysql' ? `\`${id.replace(/`/g, '``')}\`` : engine === 'mssql' ? `[${id.replace(/]/g, ']]')}]` : `"${id.replace(/"/g, '""')}"`;
+const qualified = (cfg, schema, table) => `${quoteIdent(cfg.engine, schema)}.${quoteIdent(cfg.engine, table)}`;
+const MAX_STATEMENTS = 100;
+/**
+ * Several statements as one unit: all of them are applied or none (MySQL commits by itself on a DDL statement, so a CREATE or ALTER in the
+ * middle of a script cannot be undone there). A failure says which statement it was.
+ */
+export async function dbExec(cfg, p) {
+    if (typeof p.sql !== 'string' || !p.sql.trim())
+        throw new ObjectError('Write some SQL');
+    if (p.sql.length > 200_000)
+        throw new ObjectError('The script is too long');
+    if (p.database !== undefined)
+        name(p.database, 'The database');
+    const statements = splitStatements(p.sql, cfg.engine);
+    if (!statements.length)
+        throw new ObjectError('Write some SQL');
+    if (statements.length > MAX_STATEMENTS)
+        throw new ObjectError(`A script has at most ${MAX_STATEMENTS} statements`);
+    const readOnly = p.readOnly ?? cfg.readOnly !== false;
+    if (readOnly)
+        for (const st of statements)
+            assertReadOnly(st);
+    const o = optsOf(cfg, readOnly);
+    const t0 = Date.now();
+    const raw = await withConn(cfg, p.database, async (c) => {
+        if (c.script)
+            return c.script(statements, o);
+        const begin = cfg.engine === 'mssql' ? 'BEGIN TRANSACTION' : cfg.engine === 'mysql' ? 'START TRANSACTION' : 'BEGIN';
+        const results = [];
+        await c.run(begin, { ...o, readOnly: false });
+        try {
+            for (let i = 0; i < statements.length; i++) {
+                try {
+                    results.push(await c.run(statements[i], { ...o, readOnly: false }));
+                }
+                catch (e) {
+                    throw new Error(`Statement ${i + 1} failed and nothing was changed: ${e instanceof Error ? e.message : e}`);
+                }
+            }
+            await c.run(cfg.engine === 'mssql' ? 'COMMIT TRANSACTION' : 'COMMIT', { ...o, readOnly: false });
+        }
+        catch (e) {
+            await c.run(cfg.engine === 'mssql' ? 'ROLLBACK TRANSACTION' : 'ROLLBACK', { ...o, readOnly: false }).catch(() => undefined);
+            throw e;
+        }
+        return results;
+    });
+    return { results: raw.map((r, i) => ({ ...r, rows: r.rows.map((row) => row.map(cell)), statement: statements[i] })), ms: Date.now() - t0 };
+}
+/** Groups rows `[name, …, column]` that arrive ordered by name into `{ name, columns[] }`. */
+function grouped(rows, make, col) {
+    const out = [];
+    for (const r of rows) {
+        const n = String(r[0]);
+        const cur = out.find((x) => x.name === n);
+        if (cur)
+            cur.columns.push(col(r));
+        else
+            out.push(make(r));
+    }
+    return out;
+}
+export async function dbDescribe(cfg, p) {
+    const schema = name(p.schema, 'The schema'), table = name(p.table, 'The table');
+    const columns = await dbColumns(cfg, p);
+    return withConn(cfg, p.database, async (c) => {
+        const q = async (sql) => (await c.run(sql, internal(cfg))).rows;
+        let indexes = [], foreignKeys = [];
+        if (cfg.engine === 'sqlite') {
+            for (const r of await q(`PRAGMA index_list(${lit(table)})`)) {
+                const cols = (await q(`PRAGMA index_info(${lit(String(r[1]))})`)).map((x) => String(x[2]));
+                indexes.push({ name: String(r[1]), unique: !!r[2], columns: cols });
+            }
+            const fk = await q(`PRAGMA foreign_key_list(${lit(table)})`);
+            foreignKeys = [];
+            for (const id of [...new Set(fk.map((r) => String(r[0])))]) {
+                const part = fk.filter((r) => String(r[0]) === id);
+                foreignKeys.push({ name: `fk_${table}_${id}`, columns: part.map((r) => String(r[3])), refTable: String(part[0][2]), refColumns: part.map((r) => String(r[4])) });
+            }
+        }
+        else if (cfg.engine === 'mysql') {
+            indexes = grouped(await q(`SELECT index_name, non_unique, column_name FROM information_schema.statistics WHERE table_schema = ${lit(schema)} AND table_name = ${lit(table)} ORDER BY index_name, seq_in_index`), (r) => ({ name: String(r[0]), unique: !Number(r[1]), columns: [String(r[2])] }), (r) => String(r[2]));
+            foreignKeys = grouped(await q(`SELECT constraint_name, referenced_table_schema, referenced_table_name, column_name, referenced_column_name FROM information_schema.key_column_usage WHERE table_schema = ${lit(schema)} AND table_name = ${lit(table)} AND referenced_table_name IS NOT NULL ORDER BY constraint_name, ordinal_position`), (r) => ({ name: String(r[0]), columns: [String(r[3])], refSchema: String(r[1]), refTable: String(r[2]), refColumns: [String(r[4])] }), (r) => String(r[3]));
+            for (const f of foreignKeys)
+                f.refColumns = (await q(`SELECT referenced_column_name FROM information_schema.key_column_usage WHERE table_schema = ${lit(schema)} AND table_name = ${lit(table)} AND constraint_name = ${lit(f.name)} ORDER BY ordinal_position`)).map((r) => String(r[0]));
+        }
+        else if (cfg.engine === 'postgresql') {
+            indexes = grouped(await q(`SELECT i.relname, ix.indisunique, a.attname FROM pg_index ix JOIN pg_class t ON t.oid = ix.indrelid JOIN pg_class i ON i.oid = ix.indexrelid JOIN pg_namespace n ON n.oid = t.relnamespace
+        JOIN LATERAL unnest(ix.indkey) WITH ORDINALITY AS k(attnum, ord) ON true JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
+        WHERE n.nspname = ${lit(schema)} AND t.relname = ${lit(table)} ORDER BY i.relname, k.ord`), (r) => ({ name: String(r[0]), unique: !!r[1], columns: [String(r[2])] }), (r) => String(r[2]));
+            const fk = await q(`SELECT con.conname, rn.nspname, rt.relname, a.attname, ra.attname FROM pg_constraint con JOIN pg_class t ON t.oid = con.conrelid JOIN pg_namespace n ON n.oid = t.relnamespace
+        JOIN pg_class rt ON rt.oid = con.confrelid JOIN pg_namespace rn ON rn.oid = rt.relnamespace
+        JOIN LATERAL unnest(con.conkey, con.confkey) WITH ORDINALITY AS u(ck, fk, ord) ON true JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = u.ck JOIN pg_attribute ra ON ra.attrelid = rt.oid AND ra.attnum = u.fk
+        WHERE con.contype = 'f' AND n.nspname = ${lit(schema)} AND t.relname = ${lit(table)} ORDER BY con.conname, u.ord`);
+            foreignKeys = [];
+            for (const r of fk) {
+                const cur = foreignKeys.find((x) => x.name === String(r[0]));
+                if (cur) {
+                    cur.columns.push(String(r[3]));
+                    cur.refColumns.push(String(r[4]));
+                }
+                else
+                    foreignKeys.push({ name: String(r[0]), columns: [String(r[3])], refSchema: String(r[1]), refTable: String(r[2]), refColumns: [String(r[4])] });
+            }
+        }
+        else {
+            const obj = lit(`${quoteIdent('mssql', schema)}.${quoteIdent('mssql', table)}`);
+            indexes = grouped(await q(`SELECT i.name, i.is_unique, c.name FROM sys.indexes i JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
+        JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id WHERE i.object_id = OBJECT_ID(${obj}) AND i.name IS NOT NULL ORDER BY i.name, ic.key_ordinal`), (r) => ({ name: String(r[0]), unique: !!r[1], columns: [String(r[2])] }), (r) => String(r[2]));
+            const fk = await q(`SELECT fk.name, rs.name, rt.name, pc.name, rc.name FROM sys.foreign_keys fk JOIN sys.foreign_key_columns fkc ON fkc.constraint_object_id = fk.object_id
+        JOIN sys.columns pc ON pc.object_id = fkc.parent_object_id AND pc.column_id = fkc.parent_column_id JOIN sys.tables rt ON rt.object_id = fkc.referenced_object_id
+        JOIN sys.schemas rs ON rs.schema_id = rt.schema_id JOIN sys.columns rc ON rc.object_id = fkc.referenced_object_id AND rc.column_id = fkc.referenced_column_id
+        WHERE fk.parent_object_id = OBJECT_ID(${obj}) ORDER BY fk.name, fkc.constraint_column_id`);
+            foreignKeys = [];
+            for (const r of fk) {
+                const cur = foreignKeys.find((x) => x.name === String(r[0]));
+                if (cur) {
+                    cur.columns.push(String(r[3]));
+                    cur.refColumns.push(String(r[4]));
+                }
+                else
+                    foreignKeys.push({ name: String(r[0]), columns: [String(r[3])], refSchema: String(r[1]), refTable: String(r[2]), refColumns: [String(r[4])] });
+            }
+        }
+        let rowCount = null;
+        try {
+            rowCount = Number((await q(`SELECT COUNT(*) FROM ${qualified(cfg, schema, table)}`))[0]?.[0]);
+        }
+        catch { /* a view that cannot be counted */ }
+        return { schema, table, columns, primaryKey: columns.filter((x) => x.key === 'PRI').map((x) => x.name), indexes, foreignKeys, rowCount };
+    });
+}
+/** Tables and columns whose name contains `text`, across everything the connection can see (or the file, for SQLite). */
+export async function dbSearch(cfg, p) {
+    const text = typeof p.query === 'string' ? p.query.trim() : '';
+    if (!text || text.length > 100)
+        throw new ObjectError('Give a name to look for (up to 100 characters)');
+    if (p.database !== undefined)
+        name(p.database, 'The database');
+    const like = lit(`%${text.replace(/[!%_]/g, '!$&')}%`) + " ESCAPE '!'";
+    const LIMIT = 200;
+    return withConn(cfg, p.database, async (c) => {
+        const q = async (sql) => (await c.run(sql, internal(cfg))).rows;
+        if (cfg.engine === 'sqlite') {
+            const tables = await q("SELECT name, type FROM sqlite_master WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%' ORDER BY name");
+            const out = [], needle = text.toLowerCase();
+            for (const t of tables) {
+                const tn = String(t[0]), kind = t[1] === 'view' ? 'view' : 'table';
+                if (tn.toLowerCase().includes(needle))
+                    out.push({ schema: 'main', table: tn, type: kind });
+                for (const col of await q(`PRAGMA table_info(${lit(tn)})`))
+                    if (String(col[1]).toLowerCase().includes(needle))
+                        out.push({ schema: 'main', table: tn, column: String(col[1]), type: 'column' });
+                if (out.length >= LIMIT)
+                    break;
+            }
+            return out.slice(0, LIMIT);
+        }
+        const sys = cfg.engine === 'mysql' ? "('information_schema','mysql','performance_schema','sys')" : cfg.engine === 'postgresql' ? "('pg_catalog','information_schema')" : "('INFORMATION_SCHEMA','sys')";
+        const top = cfg.engine === 'mssql' ? `TOP ${LIMIT} ` : '', limit = cfg.engine === 'mssql' ? '' : ` LIMIT ${LIMIT}`;
+        const tables = await q(`SELECT ${top}table_schema, table_name, table_type FROM information_schema.tables WHERE table_schema NOT IN ${sys} AND table_name LIKE ${like} ORDER BY 1, 2${limit}`);
+        const cols = await q(`SELECT ${top}table_schema, table_name, column_name FROM information_schema.columns WHERE table_schema NOT IN ${sys} AND column_name LIKE ${like} ORDER BY 1, 2, 3${limit}`);
+        return [
+            ...tables.map((r) => ({ schema: String(r[0]), table: String(r[1]), type: /view/i.test(String(r[2])) ? 'view' : 'table' })),
+            ...cols.map((r) => ({ schema: String(r[0]), table: String(r[1]), column: String(r[2]), type: 'column' })),
+        ].slice(0, LIMIT);
+    });
+}
+/** The statement that creates a table. MySQL and SQLite keep it; for PostgreSQL and SQL Server it is put together from the catalog. */
+export async function dbDdl(cfg, p) {
+    const schema = name(p.schema, 'The schema'), table = name(p.table, 'The table');
+    if (p.database !== undefined)
+        name(p.database, 'The database');
+    if (cfg.engine === 'postgresql') {
+        return withConn(cfg, p.database, async (c) => {
+            const q = async (sql) => (await c.run(sql, internal(cfg))).rows;
+            const cols = await q(`SELECT a.attname, format_type(a.atttypid, a.atttypmod), a.attnotnull, pg_get_expr(d.adbin, d.adrelid) FROM pg_attribute a JOIN pg_class t ON t.oid = a.attrelid JOIN pg_namespace n ON n.oid = t.relnamespace
+        LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum WHERE n.nspname = ${lit(schema)} AND t.relname = ${lit(table)} AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`);
+            if (!cols.length)
+                throw new ObjectError('That table does not exist');
+            const cons = await q(`SELECT con.conname, pg_get_constraintdef(con.oid) FROM pg_constraint con JOIN pg_class t ON t.oid = con.conrelid JOIN pg_namespace n ON n.oid = t.relnamespace WHERE n.nspname = ${lit(schema)} AND t.relname = ${lit(table)} ORDER BY con.contype, con.conname`);
+            const idx = await q(`SELECT indexdef FROM pg_indexes WHERE schemaname = ${lit(schema)} AND tablename = ${lit(table)} AND indexname NOT IN (SELECT conname FROM pg_constraint WHERE contype IN ('p','u'))`);
+            const lines = [...cols.map((r) => `  ${quoteIdent('postgresql', String(r[0]))} ${r[1]}${r[2] ? ' NOT NULL' : ''}${r[3] !== null ? ` DEFAULT ${r[3]}` : ''}`), ...cons.map((r) => `  CONSTRAINT ${quoteIdent('postgresql', String(r[0]))} ${r[1]}`)];
+            return [`CREATE TABLE ${qualified(cfg, schema, table)} (\n${lines.join(',\n')}\n);`, ...idx.map((r) => `${r[0]};`)].join('\n');
+        });
+    }
+    if (cfg.engine === 'mssql') {
+        const d = await dbDescribe(cfg, p);
+        return withConn(cfg, p.database, async (c) => {
+            const rows = (await c.run(`SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, NUMERIC_PRECISION, NUMERIC_SCALE, IS_NULLABLE, COLUMN_DEFAULT FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = ${lit(schema)} AND TABLE_NAME = ${lit(table)} ORDER BY ORDINAL_POSITION`, internal(cfg))).rows;
+            if (!rows.length)
+                throw new ObjectError('That table does not exist');
+            const type = (r) => { const t = String(r[1]); return /char|binary/i.test(t) ? `${t}(${Number(r[2]) < 0 ? 'max' : r[2]})` : /decimal|numeric/i.test(t) ? `${t}(${r[3]},${r[4]})` : t; };
+            const lines = rows.map((r) => `  ${quoteIdent('mssql', String(r[0]))} ${type(r)}${r[5] === 'YES' ? ' NULL' : ' NOT NULL'}${r[6] !== null ? ` DEFAULT ${r[6]}` : ''}`);
+            if (d.primaryKey.length)
+                lines.push(`  PRIMARY KEY (${d.primaryKey.map((x) => quoteIdent('mssql', x)).join(', ')})`);
+            for (const f of d.foreignKeys)
+                lines.push(`  CONSTRAINT ${quoteIdent('mssql', f.name)} FOREIGN KEY (${f.columns.map((x) => quoteIdent('mssql', x)).join(', ')}) REFERENCES ${qualified(cfg, f.refSchema ?? schema, f.refTable)} (${f.refColumns.map((x) => quoteIdent('mssql', x)).join(', ')})`);
+            const idx = d.indexes.filter((i) => !(d.primaryKey.length && i.columns.join() === d.primaryKey.join() && i.unique)).map((i) => `CREATE ${i.unique ? 'UNIQUE ' : ''}INDEX ${quoteIdent('mssql', i.name)} ON ${qualified(cfg, schema, table)} (${i.columns.map((x) => quoteIdent('mssql', x)).join(', ')});`);
+            return [`CREATE TABLE ${qualified(cfg, schema, table)} (\n${lines.join(',\n')}\n);`, ...idx].join('\n');
+        });
+    }
+    return withConn(cfg, p.database, async (c) => {
+        const q = async (sql) => (await c.run(sql, internal(cfg))).rows;
+        if (cfg.engine === 'sqlite') {
+            const rows = await q(`SELECT sql FROM sqlite_master WHERE tbl_name = ${lit(table)} AND sql IS NOT NULL ORDER BY CASE type WHEN 'table' THEN 0 WHEN 'view' THEN 0 ELSE 1 END, name`);
+            if (!rows.length)
+                throw new ObjectError('That table does not exist');
+            return rows.map((r) => `${String(r[0]).replace(/;\s*$/, '')};`).join('\n');
+        }
+        const r = (await q(`SHOW CREATE TABLE ${qualified(cfg, schema, table)}`))[0];
+        if (!r)
+            throw new ObjectError('That table does not exist');
+        return `${String(r[1])};`;
+    });
+}
+/** The first rows of a table, without writing SQL. */
+export async function dbSample(cfg, p) {
+    const schema = name(p.schema, 'The schema'), table = name(p.table, 'The table');
+    const n = Math.max(1, Math.min(Number.isFinite(Number(p.limit)) ? Math.floor(Number(p.limit)) : 10, cfg.maxRows ?? DEFAULT_ROWS));
+    const from = qualified(cfg, schema, table);
+    const sql = cfg.engine === 'mssql' ? `SELECT TOP (${n}) * FROM ${from}` : `SELECT * FROM ${from} LIMIT ${n}`;
+    return dbQuery(cfg, { sql, database: p.database, readOnly: true });
+}
+/** The plan the engine would follow, without running the statement. */
+export async function dbExplain(cfg, p) {
+    if (typeof p.sql !== 'string' || !p.sql.trim())
+        throw new ObjectError('Write a query');
+    if (p.database !== undefined)
+        name(p.database, 'The database');
+    const statements = splitStatements(p.sql, cfg.engine);
+    if (statements.length !== 1)
+        throw new ObjectError('Explain takes one statement');
+    // EXPLAIN ANALYZE (and ANALYZE) run the statement to measure it: only the plain plan is offered.
+    if (/^\s*(explain|analy[sz]e|describe|desc)\b/i.test(bare(statements[0])))
+        throw new ObjectError('Give the statement itself, not an EXPLAIN or ANALYZE of it.');
+    const t0 = Date.now();
+    const r = await withConn(cfg, p.database, async (c) => {
+        const o = internal(cfg);
+        if (c.explain)
+            return c.explain(statements[0], o);
+        // MySQL refuses EXPLAIN of a write on a read-only connection although it does not run it.
+        return c.run(`${cfg.engine === 'sqlite' ? 'EXPLAIN QUERY PLAN' : 'EXPLAIN'} ${statements[0]}`, cfg.engine === 'mysql' ? { ...o, readOnly: false } : o);
+    });
+    return { ...r, rows: r.rows.map((row) => row.map(cell)), ms: Date.now() - t0 };
+}
+/** Who is connected and what they are running. */
+export async function dbSessions(cfg) {
+    if (cfg.engine === 'sqlite')
+        throw new ObjectError('SQLite has no sessions: it is a file, not a server.');
+    const sql = cfg.engine === 'mysql' ? 'SHOW FULL PROCESSLIST'
+        : cfg.engine === 'postgresql' ? "SELECT pid, usename, datname, state, now() - query_start AS running, left(query, 200) AS query FROM pg_stat_activity WHERE pid <> pg_backend_pid() AND backend_type = 'client backend' ORDER BY query_start NULLS LAST"
+            : "SELECT s.session_id, s.login_name, s.host_name, DB_NAME(s.database_id) AS db, s.status, r.command, r.total_elapsed_time / 1000 AS seconds, SUBSTRING(t.text, 1, 200) AS query FROM sys.dm_exec_sessions s LEFT JOIN sys.dm_exec_requests r ON r.session_id = s.session_id OUTER APPLY sys.dm_exec_sql_text(r.sql_handle) t WHERE s.is_user_process = 1 AND s.session_id <> @@SPID";
+    const t0 = Date.now();
+    const r = await withConn(cfg, undefined, (c) => c.run(sql, internal(cfg)));
+    return { ...r, rows: r.rows.map((row) => row.map(cell)), ms: Date.now() - t0 };
+}
+/** Cancels what a session is running (MySQL, PostgreSQL) or ends the session (SQL Server). */
+export async function dbKill(cfg, id) {
+    if (cfg.engine === 'sqlite')
+        throw new ObjectError('SQLite has no sessions to cancel.');
+    const n = Number(id);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new ObjectError('The id must be a session number from object_db_sessions');
+    await withConn(cfg, undefined, async (c) => {
+        const o = { ...internal(cfg), readOnly: false };
+        if (cfg.engine === 'mysql')
+            await c.run(`KILL QUERY ${n}`, o);
+        else if (cfg.engine === 'postgresql') {
+            const r = await c.run(`SELECT pg_cancel_backend(${n})`, o);
+            if (r.rows[0]?.[0] === false)
+                throw new ObjectError(`There is no running query for session ${n}`);
+        }
+        else
+            await c.run(`KILL ${n}`, o);
+    });
+    return cfg.engine === 'mssql' ? `Session ${n} was ended.` : `The query of session ${n} was cancelled.`;
+}