@kazurolabs/psql-explorer 0.1.0 → 0.3.1

package/dist/explorer/gucs.js

@@ -0,0 +1,31 @@
+export class GucError extends Error {
+}
+// Plain (work_mem) or custom (app.tenant_id): words joined by dots.
+const validName = /^[a-z_][a-z0-9_$]*(?:\.[a-z_][a-z0-9_$]*)*$/i;
+// These would lift the read only protection of the environment.
+const readOnlySettings = new Set(['default_transaction_read_only', 'transaction_read_only']);
+/** The settings a request asked for, from `[{name, value}]`; throws a GucError for anything else. */
+export function parseGucs(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new GucError('settings is a list of {name, value}');
+    return raw.map((item) => {
+        if (typeof item?.name !== 'string' || typeof item.value !== 'string') {
+            throw new GucError('settings is a list of {name, value}');
+        }
+        const name = item.name.trim().toLowerCase();
+        if (!validName.test(name))
+            throw new GucError(`"${item.name}" is not a setting name`);
+        return { name, value: item.value };
+    });
+}
+/** Sets each setting for the rest of the session; the Postgres error says if one is unknown or refused. */
+export async function applyGucs(session, gucs) {
+    for (const { name, value } of gucs) {
+        if (session.readOnly && readOnlySettings.has(name)) {
+            throw new GucError(`${name} cannot be changed: this environment is read only`);
+        }
+        await session.rows('SELECT pg_catalog.set_config($1, $2, false)', [name, value]);
+    }
+}

package/dist/explorer/profile.js

@@ -0,0 +1,102 @@
+// What a column holds, worked out from a sample so it stays fast on big tables.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { qualified } from './catalog.js';
+import { withStatementTimeout } from './timeout.js';
+export const SAMPLE_ROWS = 10_000;
+export const PROFILE_TIMEOUT_MS = 8000;
+export const HISTOGRAM_BUCKETS = 10;
+const numberType = /^(smallint|integer|bigint|numeric|decimal|real|double precision)\b/;
+const dateType = /^(date|timestamp)\b/;
+const errorCode = (error) => error?.code ?? '';
+/** The size of a sample that holds about SAMPLE_ROWS rows of a table of `estimated` rows, in percent. */
+export const samplePercent = (estimated) => Math.min(100, Math.max(0.0001, (SAMPLE_ROWS / estimated) * 100));
+const parse = (text) => (text === null ? [] : (JSON.parse(text) ?? []));
+/** Counts by bucket number (from 1), with the empty buckets filled in. */
+const bucketsOf = (found) => {
+    const counts = Array.from({ length: HISTOGRAM_BUCKETS }, () => 0);
+    for (const { bucket, count } of found)
+        counts[Number(bucket) - 1] = Number(count);
+    return counts;
+};
+/** Profiles one column of a table or view. Throws if the column does not exist. */
+export async function profileColumn(session, table, column) {
+    const [info] = await session.rows(`SELECT pg_catalog.format_type(a.atttypid, a.atttypmod) AS type, c.relkind AS kind,
+			c.reltuples::float8 AS tuples
+		FROM pg_catalog.pg_attribute a JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+		WHERE a.attrelid = $1::regclass AND a.attname = $2 AND a.attnum > 0 AND NOT a.attisdropped`, [qualified(table), column]);
+    if (!info)
+        throw new Error(`no column "${column}" in ${table.schema}.${table.name}`);
+    const type = info.type ?? '';
+    const tuples = Number(info.tuples ?? -1);
+    const estimatedRows = tuples >= 0 ? Math.round(tuples) : null;
+    // A table sampled by pages is random; a view, or a table nobody has analyzed, gives its first rows.
+    const sampleable = info.kind === 'r' || info.kind === 'm';
+    let source;
+    let from;
+    if (estimatedRows !== null && estimatedRows <= SAMPLE_ROWS * 2) {
+        source = 'all';
+        from = qualified(table);
+    }
+    else if (sampleable && estimatedRows !== null) {
+        source = 'sample';
+        from = `${qualified(table)} TABLESAMPLE SYSTEM (${samplePercent(estimatedRows).toFixed(4)})`;
+    }
+    else {
+        source = 'first';
+        from = `(SELECT * FROM ${qualified(table)} LIMIT ${SAMPLE_ROWS}) AS head`;
+    }
+    const name = quoteIdentifier(column);
+    // The first try compares the values themselves; types that cannot be compared (json, xml,
+    // point...) are compared as text instead, without min, max and a histogram.
+    const query = (orderable) => {
+        const value = orderable ? 'v' : 'v::text';
+        const number = numberType.test(type)
+            ? 'v::numeric'
+            : dateType.test(type)
+                ? 'extract(epoch from v)::numeric'
+                : null;
+        const histogram = orderable && number
+            ? `(SELECT json_agg(json_build_object('bucket', h.bucket, 'count', h.count)) FROM (
+					SELECT LEAST(width_bucket(${number}, r.lo, r.hi, ${HISTOGRAM_BUCKETS}), ${HISTOGRAM_BUCKETS}) AS bucket,
+						count(*) AS count
+					FROM s, (SELECT min(${number}) AS lo, max(${number}) AS hi FROM s WHERE v IS NOT NULL) r
+					WHERE v IS NOT NULL AND r.hi > r.lo GROUP BY 1) h)`
+            : 'NULL';
+        return `WITH s AS MATERIALIZED (SELECT ${name} AS v FROM ${from})
+			SELECT (SELECT count(*) FROM s) AS total,
+				(SELECT count(*) FROM s WHERE v IS NULL) AS nulls,
+				(SELECT count(DISTINCT ${value}) FROM s) AS distinct,
+				(SELECT json_agg(t) FROM (
+					SELECT ${value}::text AS value, count(*) AS count FROM s WHERE v IS NOT NULL
+					GROUP BY ${value} ORDER BY 2 DESC, 1 LIMIT 10) t) AS top,
+				${orderable ? '(SELECT min(v)::text FROM s)' : 'NULL'} AS min,
+				${orderable ? '(SELECT max(v)::text FROM s)' : 'NULL'} AS max,
+				${histogram} AS histogram`;
+    };
+    const [row] = await withStatementTimeout(session, PROFILE_TIMEOUT_MS, async () => {
+        try {
+            return await session.rows(query(true));
+        }
+        catch (error) {
+            // 42883: no operator or function for the type; 42804: the types do not match.
+            if (!['42883', '42804', '22003', '22P02'].includes(errorCode(error)))
+                throw error;
+            return session.rows(query(false));
+        }
+    });
+    const total = Number(row?.total ?? 0);
+    return {
+        source,
+        sampleRows: total,
+        estimatedRows,
+        nullFraction: total === 0 ? 0 : Number(row?.nulls ?? 0) / total,
+        distinct: Number(row?.distinct ?? 0),
+        top: parse(row?.top ?? null).map((entry) => ({
+            value: entry.value,
+            count: Number(entry.count),
+        })),
+        min: row?.min ?? null,
+        max: row?.max ?? null,
+        histogram: row?.histogram ? bucketsOf(parse(row.histogram)) : null,
+    };
+}

package/dist/explorer/references.js

@@ -0,0 +1,95 @@
+// Foreign keys between tables: where a row points, and which rows point at it.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { qualified } from './catalog.js';
+import { withStatementTimeout } from './timeout.js';
+const KEY_COLUMNS = `c.conname AS name, fn.nspname AS from_schema, fc.relname AS from_table,
+			tn.nspname AS to_schema, tc.relname AS to_table,
+			(SELECT json_agg(a.attname ORDER BY k.ord)
+				FROM unnest(c.conkey) WITH ORDINALITY AS k(attnum, ord)
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = k.attnum) AS from_columns,
+			(SELECT json_agg(a.attname ORDER BY k.ord)
+				FROM unnest(c.confkey) WITH ORDINALITY AS k(attnum, ord)
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = c.confrelid AND a.attnum = k.attnum) AS to_columns`;
+const KEY_FROM = `FROM pg_catalog.pg_constraint c
+		JOIN pg_catalog.pg_class fc ON fc.oid = c.conrelid
+		JOIN pg_catalog.pg_namespace fn ON fn.oid = fc.relnamespace
+		JOIN pg_catalog.pg_class tc ON tc.oid = c.confrelid
+		JOIN pg_catalog.pg_namespace tn ON tn.oid = tc.relnamespace`;
+const keyOf = (row) => ({
+    name: row.name ?? '',
+    from: { schema: row.from_schema ?? '', name: row.from_table ?? '' },
+    to: { schema: row.to_schema ?? '', name: row.to_table ?? '' },
+    fromColumns: JSON.parse(row.from_columns ?? '[]'),
+    toColumns: JSON.parse(row.to_columns ?? '[]'),
+});
+/** Names a foreign key across the database (constraint names are only unique within a table). */
+export const foreignKeyId = (key) => JSON.stringify([key.from.schema, key.from.name, key.name]);
+/** Foreign keys of the table, and those of other tables that point at it. */
+export async function listForeignKeys(session, table) {
+    const rows = await session.rows(`SELECT ${KEY_COLUMNS}, c.conrelid = $1::regclass AS outgoing
+		${KEY_FROM}
+		WHERE c.contype = 'f' AND (c.conrelid = $1::regclass OR c.confrelid = $1::regclass)
+		ORDER BY fn.nspname, fc.relname, c.conname`, [qualified(table)]);
+    const outgoing = [];
+    const incoming = [];
+    for (const row of rows) {
+        const key = keyOf(row);
+        // A table that points at itself is both.
+        if (row.outgoing === 't' || row.outgoing === 'true')
+            outgoing.push(key);
+        if (key.to.schema === table.schema && key.to.name === table.name)
+            incoming.push(key);
+    }
+    return { outgoing, incoming };
+}
+/** Every foreign key that starts or ends in the schema. */
+export async function listSchemaForeignKeys(session, schema) {
+    const rows = await session.rows(`SELECT ${KEY_COLUMNS}
+		${KEY_FROM}
+		WHERE c.contype = 'f' AND (fn.nspname = $1 OR tn.nspname = $1)
+		ORDER BY fn.nspname, fc.relname, c.conname`, [schema]);
+    return rows.map(keyOf);
+}
+export const DEFAULT_COUNT_CAP = 1000;
+export const COUNT_TIMEOUT_MS = 3000;
+const timedOut = (error) => error?.code === '57014';
+/**
+ * How many rows of each referencing table point at the row of `table` with these values (by
+ * column name). Counting stops at `cap` per table, and a count that takes longer than
+ * COUNT_TIMEOUT_MS is given up, so a row in a huge child table cannot hang the page.
+ */
+export async function countReferences(session, table, values, { cap = DEFAULT_COUNT_CAP } = {}) {
+    const { incoming } = await listForeignKeys(session, table);
+    return withStatementTimeout(session, COUNT_TIMEOUT_MS, async () => {
+        const counts = [];
+        for (const key of incoming) {
+            const parameters = key.toColumns.map((column) => values[column]);
+            // A null never matches a foreign key, so a row without the value has no children.
+            if (parameters.some((value) => value === undefined || value === null)) {
+                counts.push({ key, count: 0, more: false });
+                continue;
+            }
+            const where = key.fromColumns
+                .map((column, i) => `${quoteIdentifier(column)} = $${i + 1}`)
+                .join(' AND ');
+            try {
+                const [row] = await session.rows(`SELECT count(*) AS n FROM (SELECT 1 FROM ${qualified(key.from)} WHERE ${where} LIMIT ${cap + 1}) AS limited`, parameters);
+                const n = Number(row?.n ?? 0);
+                counts.push({ key, count: Math.min(n, cap), more: n > cap });
+            }
+            catch (error) {
+                counts.push({
+                    key,
+                    count: null,
+                    more: false,
+                    error: timedOut(error)
+                        ? `took longer than ${COUNT_TIMEOUT_MS / 1000}s`
+                        : error instanceof Error
+                            ? error.message
+                            : String(error),
+                });
+            }
+        }
+        return counts;
+    });
+}

package/dist/explorer/rows.js

@@ -2,17 +2,18 @@
 import { quoteIdentifier } from '../db/identifiers.js';
 import { qualified } from './catalog.js';
 export const DEFAULT_PAGE_SIZE = 100;
-export function browseSql(table, { orderBy = [] }) {
+export function browseSql(table, { orderBy = [], where }) {
     const order = orderBy
         .map(({ column, descending }) => `${quoteIdentifier(column)} ${descending ? 'DESC NULLS LAST' : 'ASC NULLS FIRST'}`)
         .join(', ');
-    return `SELECT * FROM ${qualified(table)}${order ? ` ORDER BY ${order}` : ''} LIMIT $1 OFFSET $2`;
+    const n = where?.params.length ?? 0;
+    return `SELECT * FROM ${qualified(table)}${where?.sql ?? ''}${order ? ` ORDER BY ${order}` : ''} LIMIT $${n + 1} OFFSET $${n + 2}`;
 }
 /** One page of a table's rows. */
 export function browseRows(session, table, options) {
-    return session.run(browseSql(table, options), [options.limit, options.offset ?? 0], {
-        maxRows: options.limit,
-    });
+    return session.run(browseSql(table, options), 
+    // One more row than wanted, which says whether there is a next page.
+    [...(options.where?.params ?? []), options.limit + 1, options.offset ?? 0], { maxRows: options.limit });
 }
 /** The exact number of rows; this reads the whole table, so the statement timeout bounds it. */
 export async function countRows(session, table) {
@@ -23,17 +24,88 @@ export async function countRows(session, table) {
 const readsRows = /^(?:select|with|values|table)\b/i;
 // SQLSTATE 42601 (syntax error) and 0A000 (not supported): the statement cannot be wrapped.
 const cannotWrap = (error) => ['42601', '0A000'].includes(error?.code ?? '');
-/** The statement without its leading comments and trailing semicolons. */
-const trimStatement = (sql) => sql
-    .replace(/^(?:\s+|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/, '')
-    .replace(/[\s;]+$/, '');
+const identifierChar = /[\p{L}\p{N}_$]/u;
+const dollarTag = /\$(?:[\p{L}_][\p{L}\p{N}_]*)?\$/uy;
+/** Where the string, quoted name or dollar-quoted body that opens at `i` ends. */
+function quotedEnd(sql, i) {
+    const quote = sql[i];
+    if (quote === '$') {
+        dollarTag.lastIndex = i;
+        const tag = dollarTag.exec(sql)[0];
+        const close = sql.indexOf(tag, i + tag.length);
+        return close < 0 ? sql.length : close + tag.length;
+    }
+    // E'...' takes backslash escapes; every string and quoted name doubles its quote.
+    const escapes = quote === "'" && /[eE]/.test(sql[i - 1] ?? '') && !identifierChar.test(sql[i - 2] ?? '');
+    for (let j = i + 1; j < sql.length; j++) {
+        if (escapes && sql[j] === '\\')
+            j++;
+        else if (sql[j] === quote && sql[j + 1] === quote)
+            j++;
+        else if (sql[j] === quote)
+            return j + 1;
+    }
+    return sql.length;
+}
+/** Where the comment that opens at `i` ends; block comments nest in Postgres. */
+function commentEnd(sql, i) {
+    if (sql.startsWith('--', i)) {
+        const newline = sql.indexOf('\n', i);
+        return newline < 0 ? sql.length : newline + 1;
+    }
+    let depth = 0;
+    do {
+        if (sql.startsWith('/*', i))
+            depth++;
+        else if (sql.startsWith('*/', i))
+            depth--;
+        else {
+            i++;
+            continue;
+        }
+        i += 2;
+    } while (depth > 0 && i < sql.length);
+    return i;
+}
+/**
+ * The statement without the whitespace, comments and semicolons around it. Strings are read the
+ * way Postgres reads them ('...', E'...', "...", $tag$...$tag$), so a `;` or `--` in one is kept.
+ */
+export function trimStatement(sql) {
+    let start = -1;
+    let end = 0;
+    for (let i = 0; i < sql.length;) {
+        const c = sql[i];
+        if (/[\s;]/.test(c)) {
+            i++;
+            continue;
+        }
+        if (sql.startsWith('--', i) || sql.startsWith('/*', i)) {
+            i = commentEnd(sql, i);
+            continue;
+        }
+        dollarTag.lastIndex = i;
+        const quoted = c === "'" ||
+            c === '"' ||
+            (c === '$' && !identifierChar.test(sql[i - 1] ?? '') && dollarTag.test(sql));
+        const next = quoted ? quotedEnd(sql, i) : i + 1;
+        if (start < 0)
+            start = i;
+        end = next;
+        i = next;
+    }
+    return start < 0 ? '' : sql.slice(start, end);
+}
 /**
  * One page of any statement's rows, without the statement needing a LIMIT of its own. A query is
  * wrapped in `SELECT * FROM (...) LIMIT OFFSET`, so the planner knows that few rows are wanted and
- * starts returning them early, as it does for an explicit LIMIT. Other statements, and queries that
- * cannot be wrapped, run as they are and give their first rows.
+ * starts returning them early, as it does for an explicit LIMIT. Other statements run as they are
+ * and give their first rows. A query that cannot be wrapped runs as it is only when `asWritten`
+ * says the person asked for exactly that text: Postgres refusing the wrapper often means the
+ * statement writes (SELECT ... INTO, a WITH that deletes), so a caller that only lets queries
+ * through (the Build page) can count on nothing else running.
  */
-export async function runPage(session, sql, { limit, offset = 0 }) {
+export async function runPage(session, sql, { limit, offset = 0, asWritten = false }) {
     const statement = trimStatement(sql);
     if (!readsRows.test(statement))
         return session.run(sql, [], { maxRows: limit });
@@ -43,8 +115,23 @@ export async function runPage(session, sql, { limit, offset = 0 }) {
         return await session.run(wrapped, [], { maxRows: limit });
     }
     catch (error) {
-        if (!cannotWrap(error))
+        if (!asWritten || !cannotWrap(error))
             throw error;
         return session.run(sql, [], { maxRows: limit });
     }
 }
+/** The most rows an export reads; more than this is cut off and says so. */
+export const EXPORT_MAX_ROWS = 100_000;
+/** Whether a statement is one that `exportRows` can read all of. */
+export const canExport = (sql) => readsRows.test(trimStatement(sql));
+/**
+ * Up to EXPORT_MAX_ROWS rows of a query, from its first. The statement is always wrapped, so an
+ * export can never run anything that is not a query, and never falls back to running it as it is.
+ */
+export function exportRows(session, sql) {
+    const statement = trimStatement(sql);
+    if (!readsRows.test(statement)) {
+        throw new Error('Only a query that returns rows can be exported');
+    }
+    return session.run(`SELECT * FROM (\n${statement}\n) AS export LIMIT ${EXPORT_MAX_ROWS + 1}`, [], { maxRows: EXPORT_MAX_ROWS });
+}