@kazurolabs/psql-explorer 0.0.0-stage → 0.1.0

package/dist/environments.js

@@ -0,0 +1,137 @@
+// The environments a user can pick: those from the shared config file plus their local
+// connections, as one list. No Ink in here; screens reach it through Services.
+import { resolveEnvironment } from './config/resolve-environment.js';
+import { resolveValue, ResolveError } from './config/resolvers/index.js';
+import { refKinds, } from './config/schema.js';
+// A literal is shown as written; anything looked up elsewhere only by where it comes from.
+const display = (value) => {
+    if (typeof value !== 'object')
+        return String(value);
+    const kind = refKinds.find((k) => k in value);
+    return `‹${kind ?? '?'}›`;
+};
+export const sharedKey = (name) => `shared:${name}`;
+export const localKey = (id) => `local:${id}`;
+/** The red mark beside an environment's name, if it has one. */
+export const badgeOf = (entry) => entry.protected ? 'PROTECTED' : undefined;
+/** The colour a tier is shown in, so the riskier ones stand out. */
+export const tierColor = {
+    production: 'red',
+    reference: 'yellow',
+    demo: 'magenta',
+    development: 'green',
+    local: 'gray',
+};
+/** Marks a protected environment. */
+export const shield = '⛨';
+export const addressOf = (entry) => `${entry.user}@${entry.host}:${entry.port}/${entry.database}`;
+/** Shared environments by name, then local connections by name. May throw if the store fails. */
+export function listEnvironments(services) {
+    const shared = (services.config?.environments ?? []).map((config) => ({
+        key: sharedKey(config.name),
+        source: 'shared',
+        name: config.name,
+        tier: config.tier,
+        protected: config.protected,
+        readOnly: config.readOnly,
+        tlsMode: config.tls.mode,
+        user: config.username === undefined ? '‹vault›' : display(config.username),
+        host: display(config.host),
+        port: display(config.port),
+        database: display(config.database),
+        config,
+    }));
+    const local = services.store.list().map((connection) => ({
+        key: localKey(connection.id),
+        source: 'local',
+        name: connection.name,
+        // Local connections are the user's own, so they never get production guards.
+        tier: 'local',
+        protected: false,
+        readOnly: false,
+        tlsMode: connection.ssl ? 'require' : 'disable',
+        user: connection.username,
+        host: connection.host,
+        port: String(connection.port),
+        database: connection.database,
+        connection,
+    }));
+    return [...shared, ...local];
+}
+/** Looks up and validates everything needed to connect; may prompt, and may throw a ResolveError. */
+export async function resolveEntry(entry, services, 
+// `interactive: false` fails instead of asking, unless the answer is already known.
+options = {}) {
+    const { config, connection } = entry;
+    if (config) {
+        if (!services.config)
+            throw new Error('No shared config is loaded');
+        return resolveEnvironment(config, {
+            interactive: options.interactive ?? true,
+            registry: services.resolvers,
+            groups: services.groups,
+            signal: options.signal,
+        });
+    }
+    if (!connection)
+        throw new Error(`Environment ${entry.name} has no connection details`);
+    return {
+        name: connection.name,
+        tier: 'local',
+        protected: false,
+        readOnly: false,
+        host: connection.host,
+        port: connection.port,
+        database: connection.database,
+        username: connection.username,
+        password: connection.password,
+        schema: connection.schema,
+        tls: { mode: connection.ssl ? 'require' : 'disable' },
+    };
+}
+/**
+ * The environment a command names: a shared one of that name, else a local connection of that name
+ * in any letter case. A shared environment wins when both have it.
+ */
+export function findEnvironment(services, name) {
+    const entries = listEnvironments(services);
+    return (entries.find((entry) => entry.source === 'shared' && entry.name === name) ??
+        entries.find((entry) => entry.source === 'local' && entry.name.toLowerCase() === name.toLowerCase()));
+}
+/** Drops the answers typed for an environment, so the next attempt asks again (after a wrong password, say). */
+export function forgetAnswers(entry, services) {
+    services.resolvers.get('prompt')?.forget(entry.name);
+}
+const vaultValues = (config) => [
+    ['host', config.host],
+    ['port', config.port],
+    ['database', config.database],
+    ['schema', config.schema],
+    ['username', config.username],
+    ['password', config.password],
+    ['tls.ca', config.tls.ca],
+    ['tls.cert', config.tls.cert],
+    ['tls.key', config.tls.key],
+    ['tls.keyPassphrase', config.tls.keyPassphrase],
+].filter((pair) => typeof pair[1] === 'object' && 'vault' in pair[1]);
+/**
+ * Whether Vault lets this user read the secrets an environment refers to. Only `source: vault` values
+ * are read (a read changes nothing in Vault); issuing credentials or a certificate is left to the
+ * moment of connecting. Any other failure, such as Vault being unreachable, is not a refusal and
+ * counts as readable: connecting reports it.
+ */
+export async function credentialsReadable(entry, services, signal) {
+    const { config } = entry;
+    if (!config || !services.config)
+        return true;
+    for (const [field, value] of vaultValues(config)) {
+        try {
+            await resolveValue(value, { envName: config.name, field, configDir: config.dir, interactive: false, signal }, services.resolvers);
+        }
+        catch (error) {
+            if (error instanceof ResolveError && error.denied)
+                return false;
+        }
+    }
+    return true;
+}

package/dist/explorer/catalog.js

@@ -0,0 +1,383 @@
+// 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,
+			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 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),
+        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;
+}
+/** 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,31 @@
+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, ...) 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 resolved = await resolveEntry(entry, services, { signal: options.signal });
+    try {
+        return await services.openSession(resolved, {
+            readOnly: options.readOnly ?? resolved.readOnly,
+            ...(options.statementTimeoutMs === undefined
+                ? {}
+                : { statementTimeoutMs: options.statementTimeoutMs }),
+        });
+    }
+    catch (error) {
+        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);
+    }
+}

package/dist/explorer/explain.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export async function explainQuery(session, sql) {
+    const statement = sql.replace(/[\s;]+$/, '');
+    const [row] = await 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;
+}