@kazurolabs/psql-explorer 0.0.0-stage → 0.3.0

package/dist/explorer/catalog.js

@@ -0,0 +1,414 @@
+// What is in a database, read from the system catalogs: schemas, their tables, and each table's
+// columns, indexes and constraints. Every name from outside is passed as a parameter or quoted.
+import { quoteIdentifier } from '../db/identifiers.js';
+const kinds = {
+    r: 'table',
+    p: 'partitioned',
+    v: 'view',
+    m: 'materialized',
+    f: 'foreign',
+};
+export const qualified = (table) => `${quoteIdentifier(table.schema)}.${quoteIdentifier(table.name)}`;
+export const tableLabel = (table) => `${table.schema}.${table.name}`;
+/** "users" → in the default schema; "app.users" → in app. */
+export function parseTableRef(text, defaultSchema) {
+    const at = text.indexOf('.');
+    if (at <= 0 || at === text.length - 1)
+        return { schema: defaultSchema, name: text };
+    return { schema: text.slice(0, at), name: text.slice(at + 1) };
+}
+const constraintKinds = {
+    p: 'primary key',
+    f: 'foreign key',
+    u: 'unique',
+    c: 'check',
+    x: 'exclusion',
+    n: 'not null',
+    t: 'trigger',
+};
+const functionKinds = {
+    f: 'function',
+    p: 'procedure',
+    a: 'aggregate',
+    w: 'window',
+};
+const typeKinds = {
+    e: 'enum',
+    c: 'composite',
+    d: 'domain',
+    r: 'range',
+    m: 'multirange',
+};
+const count = (value) => (value === null ? null : Number(value));
+const flag = (value) => value === 't';
+/** The schemas a person works with: not pg_catalog, information_schema or pg_toast and the like. */
+export async function listSchemas(session) {
+    const rows = await session.rows(`SELECT n.nspname AS name, pg_catalog.pg_get_userbyid(n.nspowner) AS owner,
+			(SELECT count(*) FROM pg_catalog.pg_class c
+				WHERE c.relnamespace = n.oid AND c.relkind IN ('r', 'p', 'v', 'm', 'f')) AS tables
+		FROM pg_catalog.pg_namespace n
+		WHERE n.nspname !~ '^pg_' AND n.nspname <> 'information_schema'
+		ORDER BY n.nspname`);
+    return rows.map((row) => ({
+        name: row.name ?? '',
+        owner: row.owner ?? '',
+        tables: Number(row.tables),
+    }));
+}
+/** Tables, views, materialized views and foreign tables of a schema, by name (or just `name`). */
+export async function listTables(session, schema, name) {
+    const rows = await session.rows(`SELECT c.relname AS name, c.relkind AS kind,
+			CASE WHEN c.reltuples < 0 OR c.relkind IN ('v', 'f') THEN NULL
+				ELSE c.reltuples::int8 END AS estimated_rows,
+			CASE WHEN c.relkind IN ('r', 'p', 'm') THEN pg_catalog.pg_total_relation_size(c.oid)
+				END AS total_bytes,
+			to_char(greatest(s.last_vacuum, s.last_autovacuum) AT TIME ZONE 'UTC',
+				'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS last_vacuum,
+			to_char(greatest(s.last_analyze, s.last_autoanalyze) AT TIME ZONE 'UTC',
+				'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS last_analyze,
+			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
+		LEFT JOIN pg_catalog.pg_stat_all_tables s ON s.relid = c.oid
+		WHERE n.nspname = $1 AND c.relkind IN ('r', 'p', 'v', 'm', 'f')
+			AND ($2::text IS NULL OR c.relname = $2)
+		ORDER BY c.relname`, [schema, name ?? null]);
+    return rows.map((row) => ({
+        schema,
+        name: row.name ?? '',
+        kind: kinds[row.kind ?? ''] ?? 'table',
+        estimatedRows: count(row.estimated_rows),
+        totalBytes: count(row.total_bytes),
+        lastVacuum: row.last_vacuum,
+        lastAnalyze: row.last_analyze,
+        comment: row.comment,
+    }));
+}
+export async function listColumns(session, table) {
+    const rows = await session.rows(`SELECT a.attname AS name, pg_catalog.format_type(a.atttypid, a.atttypmod) AS type,
+			NOT a.attnotnull AS nullable,
+			pg_catalog.pg_get_expr(d.adbin, d.adrelid) AS default,
+			EXISTS (SELECT 1 FROM pg_catalog.pg_index i
+				WHERE i.indrelid = a.attrelid AND i.indisprimary AND a.attnum = ANY (i.indkey)) AS primary_key,
+			EXISTS (SELECT 1 FROM pg_catalog.pg_index i
+				WHERE i.indrelid = a.attrelid AND i.indisunique AND i.indnkeyatts = 1
+					AND i.indpred IS NULL AND i.indkey[0] = a.attnum) AS is_unique,
+			fk.ref_schema, fk.ref_table, fk.ref_column,
+			pg_catalog.col_description(a.attrelid, a.attnum) AS comment
+		FROM pg_catalog.pg_attribute a
+		LEFT JOIN pg_catalog.pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+		LEFT JOIN LATERAL (
+			SELECT rn.nspname AS ref_schema, rc.relname AS ref_table, ra.attname AS ref_column
+			FROM pg_catalog.pg_constraint c
+			CROSS JOIN LATERAL unnest(c.conkey, c.confkey) AS k(attnum, refattnum)
+			JOIN pg_catalog.pg_class rc ON rc.oid = c.confrelid
+			JOIN pg_catalog.pg_namespace rn ON rn.oid = rc.relnamespace
+			JOIN pg_catalog.pg_attribute ra ON ra.attrelid = c.confrelid AND ra.attnum = k.refattnum
+			WHERE c.conrelid = a.attrelid AND c.contype = 'f' AND k.attnum = a.attnum
+			ORDER BY c.conname
+			LIMIT 1
+		) fk ON true
+		WHERE a.attrelid = $1::regclass AND a.attnum > 0 AND NOT a.attisdropped
+		ORDER BY a.attnum`, [qualified(table)]);
+    return rows.map((row) => ({
+        name: row.name ?? '',
+        type: row.type ?? '',
+        nullable: flag(row.nullable),
+        default: row.default,
+        primaryKey: flag(row.primary_key),
+        unique: flag(row.is_unique),
+        references: row.ref_table === null
+            ? null
+            : { schema: row.ref_schema ?? '', table: row.ref_table ?? '', column: row.ref_column ?? '' },
+        comment: row.comment,
+    }));
+}
+export async function listIndexes(session, table) {
+    const rows = await session.rows(`SELECT i.relname AS name, pg_catalog.pg_get_indexdef(ix.indexrelid) AS definition,
+			ix.indisprimary AS primary, ix.indisunique AS unique,
+			pg_catalog.pg_relation_size(ix.indexrelid) AS bytes
+		FROM pg_catalog.pg_index ix
+		JOIN pg_catalog.pg_class i ON i.oid = ix.indexrelid
+		WHERE ix.indrelid = $1::regclass
+		ORDER BY ix.indisprimary DESC, i.relname`, [qualified(table)]);
+    return rows.map((row) => ({
+        name: row.name ?? '',
+        definition: row.definition ?? '',
+        primary: flag(row.primary),
+        unique: flag(row.unique),
+        bytes: Number(row.bytes),
+    }));
+}
+export async function listConstraints(session, table) {
+    const rows = await session.rows(`SELECT conname AS name, contype AS kind, pg_catalog.pg_get_constraintdef(oid, true) AS definition
+		FROM pg_catalog.pg_constraint
+		WHERE conrelid = $1::regclass
+		ORDER BY array_position(ARRAY['p', 'u', 'f', 'c', 'x', 'n', 't']::"char"[], contype), conname`, [qualified(table)]);
+    return rows.map((row) => ({
+        name: row.name ?? '',
+        kind: constraintKinds[row.kind ?? ''] ?? 'check',
+        definition: row.definition ?? '',
+    }));
+}
+/** Columns, indexes and constraints of one table. Throws when there is no such table. */
+export async function describeTable(session, table) {
+    const columns = await listColumns(session, table);
+    const indexes = await listIndexes(session, table);
+    const constraints = await listConstraints(session, table);
+    return { table, columns, indexes, constraints };
+}
+export async function listFunctions(session, schema) {
+    const rows = await session.rows(`SELECT p.proname AS name, pg_catalog.pg_get_function_identity_arguments(p.oid) AS args,
+			p.prokind AS kind,
+			CASE WHEN p.prokind = 'p' THEN NULL ELSE pg_catalog.pg_get_function_result(p.oid) END AS returns,
+			l.lanname AS language, 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
+		JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+		WHERE n.nspname = $1
+		ORDER BY p.proname, args`, [schema]);
+    return rows.map((row) => ({
+        schema,
+        name: row.name ?? '',
+        args: row.args ?? '',
+        kind: functionKinds[row.kind ?? ''] ?? 'function',
+        returns: row.returns,
+        language: row.language ?? '',
+        comment: row.comment,
+    }));
+}
+export async function listSequences(session, schema) {
+    const rows = await session.rows(`SELECT s.sequencename AS name, s.data_type::text AS data_type,
+			(SELECT r.relname || '.' || a.attname
+				FROM pg_catalog.pg_depend d
+				JOIN pg_catalog.pg_class r ON r.oid = d.refobjid
+				JOIN pg_catalog.pg_attribute a ON a.attrelid = d.refobjid AND a.attnum = d.refobjsubid
+				WHERE d.objid = c.oid AND d.classid = 'pg_catalog.pg_class'::regclass
+					AND d.refclassid = 'pg_catalog.pg_class'::regclass AND d.deptype IN ('a', 'i')
+				LIMIT 1) AS owned_by
+		FROM pg_catalog.pg_sequences s
+		JOIN pg_catalog.pg_namespace n ON n.nspname = s.schemaname
+		JOIN pg_catalog.pg_class c ON c.relname = s.sequencename AND c.relnamespace = n.oid
+		WHERE s.schemaname = $1
+		ORDER BY s.sequencename`, [schema]);
+    return rows.map((row) => ({
+        schema,
+        name: row.name ?? '',
+        dataType: row.data_type ?? '',
+        ownedBy: row.owned_by,
+    }));
+}
+/** Enums, composite types, domains and ranges; not the row types that tables and views bring. */
+export async function listTypes(session, schema) {
+    const rows = await session.rows(`SELECT 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 n.nspname = $1 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 t.typname`, [schema]);
+    return rows.map((row) => ({
+        schema,
+        name: row.name ?? '',
+        kind: typeKinds[row.kind ?? ''] ?? 'composite',
+        comment: row.comment,
+    }));
+}
+/** Tables, functions, sequences and types of one schema. */
+export async function listObjects(session, schema) {
+    const tables = await listTables(session, schema);
+    const functions = await listFunctions(session, schema);
+    const sequences = await listSequences(session, schema);
+    const types = await listTypes(session, schema);
+    return { tables, functions, sequences, types };
+}
+/** The tables of a schema with their columns, whose foreign keys are the relations of an ERD. */
+export async function describeErd(session, schema) {
+    const tables = (await listTables(session, schema)).filter((table) => table.kind === 'table' || table.kind === 'partitioned');
+    const erd = [];
+    for (const table of tables)
+        erd.push({ ...table, columns: await listColumns(session, table) });
+    return erd;
+}
+/** Every table, view, ... of every schema with its columns, for completing and explaining SQL. */
+export async function describeCatalog(session) {
+    const catalog = [];
+    for (const schema of await listSchemas(session)) {
+        for (const table of await listTables(session, schema.name)) {
+            catalog.push({ ...table, columns: await listColumns(session, table) });
+        }
+    }
+    return catalog;
+}
+/** Every function of every user schema with its declared arguments, for explaining calls in SQL. */
+export async function describeFunctionCatalog(session) {
+    const rows = 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.pg_get_function_arguments(p.oid) AS signature, p.prokind AS kind,
+			CASE WHEN p.prokind = 'p' THEN NULL ELSE pg_catalog.pg_get_function_result(p.oid) END AS returns,
+			l.lanname AS language, 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
+		JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+		WHERE n.nspname !~ '^pg_' AND n.nspname <> 'information_schema'
+			OR n.nspname = 'pg_catalog' AND p.prokind IN ('f', 'a', 'w') AND p.proname !~ '^_'
+		ORDER BY n.nspname, p.proname, args`);
+    return rows.map((row) => ({
+        schema: row.schema ?? '',
+        name: row.name ?? '',
+        args: row.args ?? '',
+        signature: row.signature ?? '',
+        kind: functionKinds[row.kind ?? ''] ?? 'function',
+        returns: row.returns,
+        language: row.language ?? '',
+        comment: row.comment,
+    }));
+}
+/** A table, view, ... with its columns, indexes and constraints. Null when there is no such one. */
+export async function describeRelation(session, table) {
+    const [info] = await listTables(session, table.schema, table.name);
+    if (!info)
+        return null;
+    const details = await describeTable(session, table);
+    let definition = null;
+    if (info.kind === 'view' || info.kind === 'materialized') {
+        const [row] = await session.rows('SELECT pg_catalog.pg_get_viewdef($1::regclass, true) AS definition', [qualified(table)]);
+        definition = row?.definition ?? null;
+    }
+    return { ...info, ...details, definition };
+}
+/** Null when there is no function of that name with those argument types. */
+export async function describeFunction(session, ref) {
+    const [row] = await session.rows(`SELECT p.prokind AS kind,
+			CASE WHEN p.prokind = 'p' THEN NULL ELSE pg_catalog.pg_get_function_result(p.oid) END AS returns,
+			l.lanname AS language, pg_catalog.obj_description(p.oid, 'pg_proc') AS comment,
+			pg_catalog.pg_get_userbyid(p.proowner) AS owner, p.provolatile AS volatility,
+			p.proisstrict AS strict, p.prosecdef AS security_definer,
+			CASE WHEN p.prokind = 'a' THEN NULL ELSE pg_catalog.pg_get_functiondef(p.oid) END AS definition
+		FROM pg_catalog.pg_proc p
+		JOIN pg_catalog.pg_namespace n ON n.oid = p.pronamespace
+		JOIN pg_catalog.pg_language l ON l.oid = p.prolang
+		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 (!row)
+        return null;
+    return {
+        ...ref,
+        kind: functionKinds[row.kind ?? ''] ?? 'function',
+        returns: row.returns,
+        language: row.language ?? '',
+        comment: row.comment,
+        owner: row.owner ?? '',
+        volatility: row.volatility === 'i' ? 'immutable' : row.volatility === 's' ? 'stable' : 'volatile',
+        strict: flag(row.strict),
+        securityDefiner: flag(row.security_definer),
+        definition: row.definition,
+    };
+}
+export async function describeSequence(session, ref) {
+    const [info] = (await listSequences(session, ref.schema)).filter((s) => s.name === ref.name);
+    if (!info)
+        return null;
+    const [row] = await session.rows(`SELECT sequenceowner AS owner, start_value::text AS start, min_value::text AS min,
+			max_value::text AS max, increment_by::text AS increment, cache_size::text AS cache,
+			cycle, last_value::text AS last_value
+		FROM pg_catalog.pg_sequences WHERE schemaname = $1 AND sequencename = $2`, [ref.schema, ref.name]);
+    return {
+        ...info,
+        owner: row?.owner ?? '',
+        start: row?.start ?? '',
+        min: row?.min ?? '',
+        max: row?.max ?? '',
+        increment: row?.increment ?? '',
+        cache: row?.cache ?? '',
+        cycle: flag(row?.cycle ?? null),
+        lastValue: row?.last_value ?? null,
+    };
+}
+export async function describeType(session, ref) {
+    const [row] = await session.rows(`SELECT t.oid::text AS oid, t.typtype AS kind, pg_catalog.obj_description(t.oid, 'pg_type') AS comment,
+			pg_catalog.pg_get_userbyid(t.typowner) AS owner,
+			CASE t.typtype
+				WHEN 'd' THEN pg_catalog.format_type(t.typbasetype, t.typtypmod)
+				WHEN 'r' THEN (SELECT pg_catalog.format_type(r.rngsubtype, NULL)
+					FROM pg_catalog.pg_range r WHERE r.rngtypid = t.oid)
+			END AS base_type,
+			t.typdefault AS default, t.typnotnull AS not_null
+		FROM pg_catalog.pg_type t
+		JOIN pg_catalog.pg_namespace n ON n.oid = t.typnamespace
+		WHERE n.nspname = $1 AND t.typname = $2 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'))`, [ref.schema, ref.name]);
+    if (!row)
+        return null;
+    const oid = row.oid ?? '0';
+    const kind = typeKinds[row.kind ?? ''] ?? 'composite';
+    const labels = kind === 'enum'
+        ? (await session.rows('SELECT enumlabel AS label FROM pg_catalog.pg_enum WHERE enumtypid = $1::oid ORDER BY enumsortorder', [oid])).map((r) => r.label ?? '')
+        : [];
+    const attributes = kind === 'composite'
+        ? (await session.rows(`SELECT a.attname AS name, pg_catalog.format_type(a.atttypid, a.atttypmod) AS type
+						FROM pg_catalog.pg_type t
+						JOIN pg_catalog.pg_attribute a ON a.attrelid = t.typrelid
+						WHERE t.oid = $1::oid AND a.attnum > 0 AND NOT a.attisdropped
+						ORDER BY a.attnum`, [oid])).map((r) => ({ name: r.name ?? '', type: r.type ?? '' }))
+        : [];
+    const constraints = kind === 'domain'
+        ? (await session.rows(`SELECT conname AS name, pg_catalog.pg_get_constraintdef(oid, true) AS definition
+						FROM pg_catalog.pg_constraint WHERE contypid = $1::oid ORDER BY conname`, [oid])).map((r) => ({
+            name: r.name ?? '',
+            kind: 'check',
+            definition: r.definition ?? '',
+        }))
+        : [];
+    return {
+        ...ref,
+        kind,
+        comment: row.comment,
+        owner: row.owner ?? '',
+        labels,
+        attributes,
+        baseType: row.base_type,
+        default: row.default,
+        notNull: flag(row.not_null),
+        constraints,
+    };
+}
+export async function serverInfo(session) {
+    const [row] = await session.rows(`SELECT pg_catalog.version() AS version, current_database() AS database, current_user AS user,
+			pg_catalog.pg_database_size(current_database()) AS "databaseBytes",
+			pg_catalog.pg_postmaster_start_time()::text AS "startedAt",
+			current_setting('default_transaction_read_only') AS "readOnly",
+			current_setting('TimeZone') AS "timeZone",
+			current_setting('search_path') AS "searchPath",
+			current_setting('server_encoding') AS encoding`);
+    return {
+        version: row?.version ?? '',
+        database: row?.database ?? '',
+        user: row?.user ?? '',
+        databaseBytes: Number(row?.databaseBytes ?? 0),
+        startedAt: row?.startedAt ?? '',
+        readOnly: row?.readOnly === 'on',
+        timeZone: row?.timeZone ?? '',
+        searchPath: row?.searchPath ?? '',
+        encoding: row?.encoding ?? '',
+    };
+}
+/** The other connections to this database, longest running first. */
+export async function listActivity(session) {
+    const rows = await session.rows(`SELECT pid, usename AS user, application_name AS application,
+			host(client_addr) AS client, state,
+			(now() - query_start)::text AS duration, left(query, 500) AS query
+		FROM pg_catalog.pg_stat_activity
+		WHERE datname = current_database() AND pid <> pg_backend_pid()
+		ORDER BY query_start NULLS LAST`);
+    return rows.map((row) => ({
+        pid: Number(row.pid),
+        user: row.user,
+        application: row.application,
+        client: row.client,
+        state: row.state,
+        duration: row.duration,
+        query: row.query,
+    }));
+}

package/dist/explorer/connect-entry.js

@@ -0,0 +1,42 @@
+import { DEFAULT_TIMEOUT_MS } from '../db/connect.js';
+import { describeError } from '../db/tester.js';
+import { resolveEntry } from '../environments.js';
+/** The driver refused the login, so what was typed for it was probably wrong. */
+export class LoginError extends Error {
+    name = 'LoginError';
+}
+/**
+ * Looks up everything an environment needs (from Vault, a prompt, ...) once and opens up to `count`
+ * connections with it, read only when the environment says so, so a batch of queries can run side
+ * by side without asking for anything twice. Connections beyond the first that the server refuses
+ * (too many clients, say) are left out; the first failing is an Error with a plain-English message.
+ */
+export async function connectEntries(entry, services, count, options = {}) {
+    const resolved = await resolveEntry(entry, services, { signal: options.signal });
+    const open = () => services.openSession(resolved, {
+        readOnly: options.readOnly ?? resolved.readOnly,
+        ...(options.statementTimeoutMs === undefined
+            ? {}
+            : { statementTimeoutMs: options.statementTimeoutMs }),
+    });
+    const attempts = await Promise.allSettled(Array.from({ length: Math.max(count, 1) }, open));
+    const sessions = attempts.flatMap((attempt) => attempt.status === 'fulfilled' ? [attempt.value] : []);
+    if (sessions.length > 0)
+        return sessions;
+    const error = attempts[0].reason;
+    const failure = describeError(error, resolved, DEFAULT_TIMEOUT_MS);
+    if (failure.ok)
+        throw error;
+    const message = failure.detail && failure.detail !== failure.reason
+        ? `${failure.reason} (${failure.detail})`
+        : failure.reason;
+    throw failure.kind === 'auth' ? new LoginError(message) : new Error(message);
+}
+/**
+ * Looks up everything an environment needs (from Vault, a prompt, ...) and connects, read only when
+ * the environment says so. A connection failure is an Error with a plain-English message.
+ */
+export async function connectEntry(entry, services, options = {}) {
+    const [session] = await connectEntries(entry, services, 1, options);
+    return session;
+}