@kazurolabs/psql-explorer 0.1.0 → 0.3.1

package/dist/explorer/explain.js

@@ -1,13 +1,54 @@
+// The planner's plan for a statement, as the web UI's Explain button shows it.
+import { trimStatement } from './rows.js';
+// Statements that only read, so that measuring them in a read only session is allowed. WITH is
+// among them because the transaction they run in is read only too, which refuses a CTE that writes.
+const onlyReads = /^(?:select|with|values|table)\b/i;
+/** Runs `work` in a transaction that is always rolled back, whatever it did. */
+async function rolledBack(session, begin, work) {
+    await session.run(begin);
+    try {
+        return await work();
+    }
+    finally {
+        await session.run('ROLLBACK').catch(() => undefined);
+    }
+}
 /**
  * The plan for a statement, with schemas and qualified column names so that advice can name them.
  * Without ANALYZE the statement is planned but never run, so explaining
- * an UPDATE or DELETE changes nothing.
+ * an UPDATE or DELETE changes nothing. It is planned in a read only transaction that is rolled
+ * back, and sent as one statement, so text after a `;` is refused rather than run.
  */
 export async function explainQuery(session, sql) {
-    const statement = sql.replace(/[\s;]+$/, '');
-    const [row] = await session.rows(`EXPLAIN (VERBOSE, FORMAT JSON) ${statement}`);
+    const statement = trimStatement(sql);
+    const [row] = await rolledBack(session, 'BEGIN READ ONLY', () => session.rows(`EXPLAIN (VERBOSE, FORMAT JSON) ${statement}`));
     const plan = JSON.parse(row?.['QUERY PLAN'] ?? '[]');
     if (!plan[0]?.Plan)
         throw new Error('Postgres did not return a plan');
     return plan[0].Plan;
 }
+/**
+ * Runs the statement to measure it (EXPLAIN ANALYZE), so every step of the plan has its actual
+ * time, rows and buffers next to the planner's estimates. It runs inside a transaction that is
+ * always rolled back (read only when the session is), and is sent as one statement so that no
+ * COMMIT can follow it; rows it inserts, updates or deletes are not kept, but what cannot be undone
+ * (a sequence's nextval, a NOTIFY sent by a trigger, ...) still happens. A read only session
+ * measures only queries.
+ */
+export async function explainAnalyze(session, sql) {
+    const statement = trimStatement(sql);
+    if (session.readOnly && !onlyReads.test(statement)) {
+        throw new Error('Only a query can be measured: this environment is read only');
+    }
+    return rolledBack(session, session.readOnly ? 'BEGIN READ ONLY' : 'BEGIN', async () => {
+        const [row] = await session.rows(`EXPLAIN (ANALYZE, BUFFERS, VERBOSE, FORMAT JSON) ${statement}`);
+        const plan = JSON.parse(row?.['QUERY PLAN'] ?? '[]');
+        if (!plan[0]?.Plan)
+            throw new Error('Postgres did not return a plan');
+        return {
+            plan: plan[0].Plan,
+            planningMs: plan[0]['Planning Time'] ?? null,
+            executionMs: plan[0]['Execution Time'] ?? null,
+        };
+    });
+}

package/dist/explorer/filter.js

@@ -0,0 +1,121 @@
+// Filters on the rows of a table, as the row grid of the web page sends them.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { escapeLike } from './search.js';
+export const FILTER_OPS = [
+    'eq',
+    'ne',
+    'contains',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'null',
+    'notnull',
+    'in',
+    'between',
+];
+export const MAX_IN_VALUES = 100;
+export class FilterError extends Error {
+}
+const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
+/** The values of an `in` list: commas separate them, a backslash escapes a comma or a backslash. */
+export function splitList(text) {
+    const values = [];
+    let current = '';
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === '\\' && i + 1 < text.length)
+            current += text[++i];
+        else if (char === ',') {
+            values.push(current.trim());
+            current = '';
+        }
+        else
+            current += char;
+    }
+    values.push(current.trim());
+    return values.filter((value) => value !== '');
+}
+const comparisons = {
+    eq: '=',
+    ne: '<>',
+    gt: '>',
+    gte: '>=',
+    lt: '<',
+    lte: '<=',
+};
+/**
+ * The WHERE clause for the filters. Columns must be ones of the table, and values are bound as
+ * parameters (or written as literals when `inline` is set, for showing the statement); a value is
+ * compared with the column's own type, so Postgres reads `2024-01-01` as a date for a date column.
+ */
+export function buildWhere(columns, filters, { inline = false } = {}) {
+    const params = [];
+    const bind = (value) => {
+        if (inline)
+            return quoteLiteral(value);
+        params.push(value);
+        return `$${params.length}`;
+    };
+    const known = new Set(columns.map((column) => column.name));
+    const conditions = filters.map((filter) => {
+        if (!known.has(filter.column))
+            throw new FilterError(`no column "${filter.column}"`);
+        if (!FILTER_OPS.includes(filter.op))
+            throw new FilterError(`unknown operator "${filter.op}"`);
+        const name = quoteIdentifier(filter.column);
+        const { op } = filter;
+        if (op === 'null')
+            return `${name} IS NULL`;
+        if (op === 'notnull')
+            return `${name} IS NOT NULL`;
+        const value = filter.value ?? '';
+        if (op === 'in') {
+            const values = splitList(value);
+            if (values.length === 0)
+                throw new FilterError(`"${filter.column}" in needs a value`);
+            if (values.length > MAX_IN_VALUES) {
+                throw new FilterError(`in takes at most ${MAX_IN_VALUES} values`);
+            }
+            return `${name} IN (${values.map(bind).join(', ')})`;
+        }
+        if (op === 'between') {
+            if (value === '' || (filter.value2 ?? '') === '') {
+                throw new FilterError(`"${filter.column}" between needs two values`);
+            }
+            const low = bind(value);
+            return `${name} BETWEEN ${low} AND ${bind(filter.value2)}`;
+        }
+        if (op === 'contains')
+            return `${name}::text ILIKE ${bind(`%${escapeLike(value)}%`)}`;
+        return `${name} ${comparisons[op]} ${bind(value)}`;
+    });
+    return {
+        sql: conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '',
+        params,
+    };
+}
+/** Reads the filters of a request, which are untrusted, as `Filter`s. */
+export function parseFilters(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new FilterError('filters must be a list');
+    if (raw.length > 50)
+        throw new FilterError('too many filters');
+    return raw.map((item) => {
+        const entry = item;
+        if (typeof entry?.column !== 'string' || typeof entry.op !== 'string') {
+            throw new FilterError('a filter is {column, op, value}');
+        }
+        const text = (field) => (typeof field === 'string' ? field : undefined);
+        const value = text(entry.value);
+        const value2 = text(entry.value2);
+        return {
+            column: entry.column,
+            op: entry.op,
+            ...(value === undefined ? {} : { value }),
+            ...(value2 === undefined ? {} : { value2 }),
+        };
+    });
+}