@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/explorer/search.js

@@ -0,0 +1,309 @@
+// Finding things in a database: a flat index of its object names for a search box, and a search for
+// a value through the text, uuid and integer columns of its tables.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { qualified } from './catalog.js';
+export const MAX_INDEXED_COLUMNS = 50_000;
+const relationKinds = {
+    r: 'table',
+    p: 'partitioned',
+    v: 'view',
+    m: 'materialized',
+    f: 'foreign',
+};
+// The schemas a person works with, as in listSchemas.
+const userSchema = `n.nspname !~ '^pg_' AND n.nspname <> 'information_schema'`;
+/**
+ * Every table, view, column, function, sequence, type and enum value of the schemas a person works
+ * with, with comments, for matching against what is typed in a search box.
+ */
+export async function buildSearchIndex(session) {
+    const entries = [];
+    const relations = await session.rows(`SELECT n.nspname AS schema, c.relname AS name, c.relkind AS kind,
+			pg_catalog.obj_description(c.oid, 'pg_class') AS comment
+		FROM pg_catalog.pg_class c
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		WHERE ${userSchema} AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
+		ORDER BY n.nspname, c.relname`);
+    for (const row of relations) {
+        entries.push({
+            kind: relationKinds[row.kind ?? ''] ?? 'table',
+            schema: row.schema ?? '',
+            name: row.name ?? '',
+            parent: null,
+            detail: null,
+            comment: row.comment,
+        });
+    }
+    const columns = await session.rows(`SELECT n.nspname AS schema, c.relname AS table, a.attname AS name,
+			pg_catalog.format_type(a.atttypid, a.atttypmod) AS type,
+			pg_catalog.col_description(a.attrelid, a.attnum) AS comment
+		FROM pg_catalog.pg_attribute a
+		JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		WHERE ${userSchema} AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
+			AND a.attnum > 0 AND NOT a.attisdropped
+		ORDER BY n.nspname, c.relname, a.attnum
+		LIMIT $1`, [MAX_INDEXED_COLUMNS + 1]);
+    const truncated = columns.length > MAX_INDEXED_COLUMNS;
+    for (const row of columns.slice(0, MAX_INDEXED_COLUMNS)) {
+        entries.push({
+            kind: 'column',
+            schema: row.schema ?? '',
+            name: row.name ?? '',
+            parent: row.table,
+            detail: row.type,
+            comment: row.comment,
+        });
+    }
+    const labels = await session.rows(`SELECT n.nspname AS schema, t.typname AS type, e.enumlabel AS label
+		FROM pg_catalog.pg_enum e
+		JOIN pg_catalog.pg_type t ON t.oid = e.enumtypid
+		JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+		WHERE ${userSchema}
+		ORDER BY n.nspname, t.typname, e.enumsortorder`);
+    for (const row of labels) {
+        entries.push({
+            kind: 'enum value',
+            schema: row.schema ?? '',
+            name: row.label ?? '',
+            parent: row.type,
+            detail: null,
+            comment: null,
+        });
+    }
+    const functions = await session.rows(`SELECT n.nspname AS schema, p.proname AS name,
+			pg_catalog.pg_get_function_identity_arguments(p.oid) AS args,
+			pg_catalog.obj_description(p.oid, 'pg_proc') AS comment
+		FROM pg_catalog.pg_proc p
+		JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+		WHERE ${userSchema}
+		ORDER BY n.nspname, p.proname, args`);
+    for (const row of functions) {
+        entries.push({
+            kind: 'function',
+            schema: row.schema ?? '',
+            name: row.name ?? '',
+            parent: null,
+            detail: row.args ?? '',
+            comment: row.comment,
+        });
+    }
+    const sequences = await session.rows(`SELECT schemaname AS schema, sequencename AS name FROM pg_catalog.pg_sequences
+		WHERE schemaname !~ '^pg_' AND schemaname <> 'information_schema'
+		ORDER BY schemaname, sequencename`);
+    for (const row of sequences) {
+        entries.push({
+            kind: 'sequence',
+            schema: row.schema ?? '',
+            name: row.name ?? '',
+            parent: null,
+            detail: null,
+            comment: null,
+        });
+    }
+    const types = await session.rows(`SELECT n.nspname AS schema, t.typname AS name, t.typtype AS kind,
+			pg_catalog.obj_description(t.oid, 'pg_type') AS comment
+		FROM pg_catalog.pg_type t
+		JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+		WHERE ${userSchema} AND t.typtype IN ('e', 'c', 'd', 'r', 'm')
+			AND (t.typtype <> 'c' OR EXISTS (
+				SELECT 1 FROM pg_catalog.pg_class c WHERE c.oid = t.typrelid AND c.relkind = 'c'))
+		ORDER BY n.nspname, t.typname`);
+    const typeKinds = {
+        e: 'enum',
+        c: 'composite',
+        d: 'domain',
+        r: 'range',
+        m: 'multirange',
+    };
+    for (const row of types) {
+        entries.push({
+            kind: 'type',
+            schema: row.schema ?? '',
+            name: row.name ?? '',
+            parent: null,
+            detail: typeKinds[row.kind ?? ''] ?? null,
+            comment: row.comment,
+        });
+    }
+    return { entries, truncated };
+}
+export const DEFAULT_TABLE_TIMEOUT_MS = 5_000;
+export const DEFAULT_DEADLINE_MS = 30_000;
+export const DEFAULT_MAX_TABLES = 200;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const integerPattern = /^[+-]?\d{1,18}$/;
+const valueKinds = {
+    text: 'text',
+    varchar: 'text',
+    bpchar: 'text',
+    name: 'text',
+    citext: 'text',
+    uuid: 'uuid',
+    int2: 'integer',
+    int4: 'integer',
+    int8: 'integer',
+};
+/** The column kinds a text can be compared with, e.g. a uuid is only compared with uuid columns. */
+export function comparableKinds(text) {
+    const kinds = new Set(['text']);
+    if (uuidPattern.test(text))
+        kinds.add('uuid');
+    if (integerPattern.test(text))
+        kinds.add('integer');
+    return kinds;
+}
+/** Escapes the characters that mean something to LIKE. */
+export const escapeLike = (text) => text.replace(/[\\%_]/g, (char) => `\\${char}`);
+const likePattern = (text) => `%${escapeLike(text)}%`;
+const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
+/**
+ * The condition that finds `text` in a column of the given kind. A text is compared by `$1`, which
+ * holds a LIKE pattern for it; a uuid and an integer are written out, which is safe because
+ * `comparableKinds` only lets through text of exactly their shape.
+ */
+const conditionFor = (column, kind, text) => kind === 'text'
+    ? `${column} ILIKE $1`
+    : kind === 'uuid'
+        ? `${column} = ${quoteLiteral(text)}::uuid`
+        : `${column} = ${text.replace(/^\+/, '')}`;
+/** A statement that lists the rows of a table holding the text in one column. */
+export function valueSql(table, column, kind, text) {
+    const name = quoteIdentifier(column);
+    const where = kind === 'text'
+        ? `${name} ILIKE ${quoteLiteral(likePattern(text))}`
+        : conditionFor(name, kind, text);
+    return `SELECT * FROM ${qualified(table)} WHERE ${where} LIMIT 100`;
+}
+const timedOut = (error) => error?.code === '57014';
+/**
+ * Looks for `text` in every text, uuid and integer column of the tables of a schema (or of all),
+ * reading each table once. Given several sessions, the tables are shared out over them, one table at a time on
+ * each, so more sessions read more tables side by side. The work is bounded: a table that takes
+ * longer than `tableTimeoutMs` is skipped, and so is everything left once `deadlineMs` has passed
+ * or `maxTables` are done, each with the reason in the result. Views are not read. Only SELECT
+ * statements are run.
+ */
+export async function searchValues(sessionOrSessions, { text, schema }, { tableTimeoutMs = DEFAULT_TABLE_TIMEOUT_MS, deadlineMs = DEFAULT_DEADLINE_MS, maxTables = DEFAULT_MAX_TABLES, } = {}) {
+    const sessions = Array.isArray(sessionOrSessions)
+        ? sessionOrSessions
+        : [sessionOrSessions];
+    const [first] = sessions;
+    if (!first)
+        throw new Error('searchValues needs a session');
+    const kinds = comparableKinds(text);
+    const found = await first.rows(`SELECT n.nspname AS schema, c.relname AS table, a.attname AS column,
+			pg_catalog.format_type(a.atttypid, a.atttypmod) AS type, t.typname AS udt
+		FROM pg_catalog.pg_attribute a
+		JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
+		WHERE ${userSchema} AND c.relkind IN ('r', 'p')
+			AND ($1::text IS NULL OR n.nspname = $1)
+			AND a.attnum > 0 AND NOT a.attisdropped
+			AND t.typname = ANY($2::text[])
+			AND pg_catalog.has_column_privilege(a.attrelid, a.attnum, 'SELECT')
+		ORDER BY n.nspname, c.relname, a.attnum`, [schema ?? null, Object.keys(valueKinds)]);
+    // Group the columns that can be compared with the text by table.
+    const tables = new Map();
+    for (const row of found) {
+        const kind = valueKinds[row.udt ?? ''];
+        if (!kind || !kinds.has(kind))
+            continue;
+        const table = { schema: row.schema ?? '', name: row.table ?? '' };
+        const key = `${table.schema}\0${table.name}`;
+        const entry = tables.get(key) ?? { table, columns: [] };
+        entry.columns.push({ name: row.column ?? '', type: row.type ?? '', kind });
+        tables.set(key, entry);
+    }
+    const started = Date.now();
+    const queue = [...tables.values()];
+    // One slot per table, so the result reads the same however the sessions interleave.
+    const outcomes = [];
+    let next = 0;
+    // Tables being read or read successfully, against maxTables.
+    let used = 0;
+    // The timeout belongs to the session, so put the old one back when done.
+    const worker = async (session) => {
+        const [before] = await session.rows("SELECT current_setting('statement_timeout') AS timeout");
+        await session.rows("SELECT pg_catalog.set_config('statement_timeout', $1, false)", [
+            String(tableTimeoutMs),
+        ]);
+        try {
+            for (;;) {
+                const index = next++;
+                const item = queue[index];
+                if (!item)
+                    return;
+                const { table, columns } = item;
+                if (used >= maxTables) {
+                    outcomes[index] = { skipped: `only ${maxTables} tables are searched at a time` };
+                    continue;
+                }
+                if (Date.now() - started > deadlineMs) {
+                    outcomes[index] = { skipped: 'ran out of time' };
+                    continue;
+                }
+                used++;
+                // One pass over the table counts the rows for every column at once.
+                const counts = columns
+                    .map((column, i) => {
+                    const condition = conditionFor(quoteIdentifier(column.name), column.kind, text);
+                    return `count(*) FILTER (WHERE ${condition}) AS c${i}`;
+                })
+                    .join(', ');
+                // A parameter nobody uses has no type, so it is only sent along with a text column.
+                const values = columns.some((column) => column.kind === 'text') ? [likePattern(text)] : [];
+                try {
+                    const [row] = await session.rows(`SELECT ${counts} FROM ${qualified(table)}`, values);
+                    outcomes[index] = {
+                        matches: columns.flatMap((column, i) => {
+                            const count = Number(row?.[`c${i}`] ?? 0);
+                            return count > 0
+                                ? [
+                                    {
+                                        ...table,
+                                        column: column.name,
+                                        type: column.type,
+                                        matches: count,
+                                        sql: valueSql(table, column.name, column.kind, text),
+                                    },
+                                ]
+                                : [];
+                        }),
+                    };
+                }
+                catch (error) {
+                    used--;
+                    outcomes[index] = {
+                        skipped: timedOut(error)
+                            ? `took longer than ${Math.round(tableTimeoutMs / 1000)}s`
+                            : error instanceof Error
+                                ? error.message
+                                : String(error),
+                    };
+                }
+            }
+        }
+        finally {
+            await session.rows("SELECT pg_catalog.set_config('statement_timeout', $1, false)", [
+                before?.timeout ?? '0',
+            ]);
+        }
+    };
+    await Promise.all(sessions.map(worker));
+    const matches = [];
+    const skipped = [];
+    let searched = 0;
+    outcomes.forEach((outcome, index) => {
+        if ('skipped' in outcome)
+            skipped.push({ table: queue[index].table, reason: outcome.skipped });
+        else {
+            searched++;
+            matches.push(...outcome.matches);
+        }
+    });
+    // Most matches first.
+    matches.sort((a, b) => b.matches - a.matches);
+    return { matches, searched, skipped };
+}

package/dist/explorer/security.js

@@ -0,0 +1,152 @@
+const flag = (value) => value === 't';
+const commands = {
+    '*': 'ALL',
+    r: 'SELECT',
+    a: 'INSERT',
+    w: 'UPDATE',
+    d: 'DELETE',
+};
+/** Roles of the server that skip row level security: superusers and those with BYPASSRLS. */
+async function bypassRoles(session) {
+    const rows = await session.rows(`SELECT rolname AS name FROM pg_catalog.pg_roles
+		WHERE (rolsuper OR rolbypassrls) AND rolname !~ '^pg_' ORDER BY rolname`);
+    return rows.map((row) => row.name ?? '');
+}
+const relationKinds = {
+    r: 'table',
+    p: 'partitioned',
+    v: 'view',
+    m: 'materialized',
+    f: 'foreign',
+};
+/** RLS state, policies and grants of a table or view; null when there is no such relation. */
+export async function describeSecurity(session, table) {
+    const [relation] = await session.rows(`SELECT c.oid::text AS oid, c.relkind AS kind, pg_catalog.pg_get_userbyid(c.relowner) AS owner,
+			c.relrowsecurity AS enabled, c.relforcerowsecurity AS forced,
+			coalesce(c.reloptions::text[] && ARRAY['security_invoker=true', 'security_invoker=on',
+				'security_invoker=1', 'security_invoker=yes'], false) AS invoker
+		FROM pg_catalog.pg_class c
+		JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+		WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind IN ('r', 'p', 'v', 'm', 'f')`, [table.schema, table.name]);
+    if (!relation?.oid)
+        return null;
+    const policies = await session.rows(`SELECT p.polname AS name, p.polcmd AS command, p.polpermissive AS permissive,
+			(SELECT coalesce(json_agg(CASE WHEN r = 0 THEN 'public'
+				ELSE pg_catalog.pg_get_userbyid(r) END), '[]')::text
+				FROM unnest(p.polroles) AS r) AS roles,
+			pg_catalog.pg_get_expr(p.polqual, p.polrelid) AS qual,
+			pg_catalog.pg_get_expr(p.polwithcheck, p.polrelid) AS with_check
+		FROM pg_catalog.pg_policy p
+		WHERE p.polrelid = $1::oid
+		ORDER BY p.polname`, [relation.oid]);
+    const grants = await session.rows(`SELECT CASE WHEN a.grantee = 0 THEN 'public' ELSE pg_catalog.pg_get_userbyid(a.grantee) END
+				AS grantee,
+			json_agg(a.privilege_type ORDER BY a.privilege_type)::text AS privileges
+		FROM pg_catalog.pg_class c,
+			LATERAL aclexplode(coalesce(c.relacl, acldefault('r', c.relowner))) AS a
+		WHERE c.oid = $1::oid
+		GROUP BY a.grantee
+		ORDER BY a.grantee = 0 DESC, 1`, [relation.oid]);
+    const kind = relationKinds[relation.kind ?? ''] ?? 'table';
+    const sources = kind === 'view' || kind === 'materialized'
+        ? await session.rows(`SELECT DISTINCT n.nspname AS schema, t.relname AS name,
+						pg_catalog.pg_get_userbyid(t.relowner) AS owner,
+						t.relrowsecurity AS enabled, t.relforcerowsecurity AS forced,
+						(SELECT count(*) FROM pg_catalog.pg_policy p WHERE p.polrelid = t.oid) AS policies
+					FROM pg_catalog.pg_rewrite rw
+					JOIN pg_catalog.pg_depend d ON d.classid = 'pg_catalog.pg_rewrite'::regclass
+						AND d.objid = rw.oid AND d.refclassid = 'pg_catalog.pg_class'::regclass
+					JOIN pg_catalog.pg_class t ON t.oid = d.refobjid AND t.relkind IN ('r', 'p')
+					JOIN pg_catalog.pg_namespace n ON n.oid = t.relnamespace
+					WHERE rw.ev_class = $1::oid AND t.oid <> rw.ev_class
+					ORDER BY 1, 2`, [relation.oid])
+        : [];
+    return {
+        kind,
+        owner: relation.owner ?? '',
+        securityInvoker: flag(relation.invoker),
+        sources: sources.map((row) => ({
+            schema: row.schema ?? '',
+            name: row.name ?? '',
+            owner: row.owner ?? '',
+            rlsEnabled: flag(row.enabled),
+            rlsForced: flag(row.forced),
+            policies: Number(row.policies),
+        })),
+        rlsEnabled: flag(relation.enabled),
+        rlsForced: flag(relation.forced),
+        policies: policies.map((row) => ({
+            name: row.name ?? '',
+            command: commands[row.command ?? ''] ?? 'ALL',
+            permissive: flag(row.permissive),
+            roles: JSON.parse(row.roles ?? '[]'),
+            using: row.qual,
+            withCheck: row.with_check,
+        })),
+        grants: grants.map((row) => ({
+            grantee: row.grantee ?? '',
+            privileges: JSON.parse(row.privileges ?? '[]'),
+        })),
+        bypassRoles: await bypassRoles(session).catch(() => []),
+    };
+}
+/** Who a function runs as and may be run by; null when there is no such function. */
+export async function describeFunctionSecurity(session, ref) {
+    const [fn] = await session.rows(`SELECT p.oid::text AS oid, pg_catalog.pg_get_userbyid(p.proowner) AS owner,
+			p.prosecdef AS definer, p.proleakproof AS leakproof,
+			to_json(coalesce(p.proconfig, '{}'::text[]))::text AS config
+		FROM pg_catalog.pg_proc p
+		JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+		WHERE n.nspname = $1 AND p.proname = $2
+			AND pg_catalog.pg_get_function_identity_arguments(p.oid) = $3`, [ref.schema, ref.name, ref.args]);
+    if (!fn?.oid)
+        return null;
+    const grants = await session.rows(`SELECT CASE WHEN a.grantee = 0 THEN 'public' ELSE pg_catalog.pg_get_userbyid(a.grantee) END
+				AS grantee,
+			json_agg(a.privilege_type ORDER BY a.privilege_type)::text AS privileges
+		FROM pg_catalog.pg_proc p,
+			LATERAL aclexplode(coalesce(p.proacl, acldefault('f', p.proowner))) AS a
+		WHERE p.oid = $1::oid
+		GROUP BY a.grantee
+		ORDER BY a.grantee = 0 DESC, 1`, [fn.oid]);
+    return {
+        owner: fn.owner ?? '',
+        securityDefiner: flag(fn.definer),
+        leakproof: flag(fn.leakproof),
+        config: JSON.parse(fn.config ?? '[]'),
+        grants: grants.map((row) => ({
+            grantee: row.grantee ?? '',
+            privileges: JSON.parse(row.privileges ?? '[]'),
+        })),
+        bypassRoles: await bypassRoles(session).catch(() => []),
+    };
+}
+/** The roles of the server (not the built in pg_ ones) and how each stands against RLS. */
+export async function listRoles(session) {
+    const rows = await session.rows(`SELECT r.rolname AS name, r.rolsuper AS superuser, r.rolcanlogin AS can_login,
+			r.rolcreaterole AS create_role, r.rolcreatedb AS create_db,
+			r.rolreplication AS replication, r.rolbypassrls AS bypass_rls,
+			r.rolconnlimit AS connection_limit,
+			(SELECT count(*) FROM pg_catalog.pg_policy p WHERE r.oid = ANY (p.polroles)) AS policies,
+			(SELECT count(*) FROM pg_catalog.pg_class c
+				WHERE c.relowner = r.oid AND c.relkind IN ('r', 'p') AND c.relrowsecurity) AS owned_rls,
+			(SELECT count(*) FROM pg_catalog.pg_class c
+				WHERE c.relowner = r.oid AND c.relkind IN ('r', 'p') AND c.relforcerowsecurity)
+				AS owned_forced
+		FROM pg_catalog.pg_roles r
+		WHERE r.rolname !~ '^pg_'
+		ORDER BY r.rolsuper DESC, r.rolname`);
+    return rows.map((row) => ({
+        name: row.name ?? '',
+        superuser: flag(row.superuser),
+        canLogin: flag(row.can_login),
+        createRole: flag(row.create_role),
+        createDb: flag(row.create_db),
+        replication: flag(row.replication),
+        bypassRls: flag(row.bypass_rls),
+        connectionLimit: Number(row.connection_limit),
+        policies: Number(row.policies),
+        ownedRlsTables: Number(row.owned_rls),
+        ownedForcedTables: Number(row.owned_forced),
+    }));
+}