@kazurolabs/psql-explorer 0.1.0 → 0.3.0

package/dist/explorer/alter.js

@@ -0,0 +1,493 @@
+// Turns the difference between a table as it is and as it was edited into ALTER statements. Pure:
+// rows of the two designs are matched by id, so a renamed column is a RENAME and not a drop and an
+// add. Each statement carries what the page needs to warn about it and to offer a safer way.
+import { quoteIdentifier } from '../db/identifiers.js';
+import { columnSql, constraintSql, DdlError, indexSql, literal, suggestConstraintName, typeSql, } from './ddl.js';
+export class AlterError extends DdlError {
+}
+/** A table with more rows than this gets a warning where a statement has to read all of them. */
+export const BIG_TABLE_ROWS = 10_000;
+const same = (a, b) => (a ?? '').trim() === (b ?? '').trim();
+function rowId(kind, row) {
+    const id = row.id ?? (row.name ? `name:${row.name}` : undefined);
+    if (id === undefined)
+        throw new AlterError(`A ${kind} has neither an id nor a name`);
+    return id;
+}
+const rows = (estimate) => estimate === null || estimate === undefined
+    ? 'a table never analyzed, so of unknown size'
+    : `about ${estimate.toLocaleString('en-US')} rows`;
+const big = (estimate) => estimate === null || estimate === undefined || estimate >= BIG_TABLE_ROWS;
+const qualified = (table) => `${quoteIdentifier(table.schema)}.${quoteIdentifier(table.name)}`;
+/** Whether changing a column from one type to the other has to rewrite every row. */
+export function rewritesTable(from, to) {
+    if (typeSql(from) === typeSql(to))
+        return false;
+    if (from.schema !== undefined || to.schema !== undefined)
+        return true;
+    if ((from.array ?? 0) !== (to.array ?? 0))
+        return true;
+    // A longer or no limit on varchar, and varchar to text, leave the stored values as they are.
+    if (from.name === 'varchar' && to.name === 'text')
+        return false;
+    if (from.name === 'varchar' && to.name === 'varchar') {
+        return to.length !== undefined && (from.length === undefined || to.length < from.length);
+    }
+    if (from.name === 'numeric' && to.name === 'numeric') {
+        const wider = from.precision !== undefined &&
+            (to.precision === undefined ||
+                (to.precision >= from.precision && (to.scale ?? 0) === (from.scale ?? 0)));
+        return !wider && !(from.precision === undefined && to.precision === undefined);
+    }
+    return true;
+}
+function resolve(design) {
+    const columns = new Map();
+    const names = new Map();
+    for (const column of design.columns) {
+        const id = rowId('column', column);
+        if (columns.has(id))
+            throw new AlterError(`Two columns share the id "${id}"`);
+        columns.set(id, column);
+        names.set(column.name, id);
+    }
+    return { columns, names };
+}
+/** A constraint's meaning with columns as ids, so a rename of a column does not change it. */
+function constraintShape(design, resolved, constraint) {
+    const ids = (columns) => columns.map((name) => resolved.names.get(name) ?? name);
+    switch (constraint.kind) {
+        case 'primary':
+            return { kind: 'primary', columns: ids(constraint.columns) };
+        case 'unique':
+            return {
+                kind: 'unique',
+                columns: ids(constraint.columns),
+                nulls: !!constraint.nullsNotDistinct,
+            };
+        case 'check':
+            return { kind: 'check', expression: constraint.expression.trim() };
+        case 'foreign': {
+            const target = constraint.references;
+            const self = target.schema === design.schema && target.table === design.name;
+            return {
+                kind: 'foreign',
+                columns: ids(constraint.columns),
+                target: self ? 'self' : `${target.schema}.${target.table}`,
+                targetColumns: self ? ids(target.columns) : target.columns,
+                onDelete: constraint.onDelete ?? 'no action',
+                onUpdate: constraint.onUpdate ?? 'no action',
+                full: !!constraint.matchFull,
+                deferrable: !!constraint.deferrable,
+                deferred: !!constraint.initiallyDeferred,
+            };
+        }
+    }
+}
+function indexShape(resolved, index) {
+    return {
+        unique: !!index.unique,
+        method: index.method ?? 'btree',
+        items: index.items.map((item) => [
+            'column' in item ? (resolved.names.get(item.column) ?? item.column) : item.expression.trim(),
+            'column' in item,
+            !!item.descending,
+        ]),
+        include: (index.include ?? []).map((name) => resolved.names.get(name) ?? name),
+        where: (index.where ?? '').trim(),
+    };
+}
+const shapeKey = (shape) => JSON.stringify(shape);
+function checkUnique(what, ids) {
+    if (new Set(ids).size !== ids.length)
+        throw new AlterError(`Two ${what}s share an id`);
+}
+/**
+ * The statements that change `before` into `after`, in an order that works: what goes first, then
+ * columns, constraints and indexes, then the table itself (so every statement but the last names the
+ * table as it is now). The first statement sets `lock_timeout`; the caller adds it.
+ */
+export function diffDesigns(before, after, options = {}) {
+    const old = resolve(before);
+    const next = resolve(after);
+    if (!after.schema)
+        throw new AlterError('The table needs a schema');
+    if (!after.name)
+        throw new AlterError('The table needs a name');
+    if (after.columns.length === 0)
+        throw new AlterError('The table needs a column');
+    for (const column of after.columns) {
+        if (!column.name)
+            throw new AlterError('A column needs a name');
+    }
+    const partitionId = (design, resolved) => design.partition ? resolved.names.get(design.partition.column) : undefined;
+    if (before.partition?.method !== after.partition?.method ||
+        partitionId(before, old) !== partitionId(after, next)) {
+        throw new AlterError('How a table is partitioned cannot be changed: make a new table');
+    }
+    const serverMajor = options.serverMajor ?? 99;
+    const table = qualified(before);
+    const estimate = options.estimatedRows;
+    const out = [];
+    const chosen = (list, key) => !!list?.includes(key);
+    const add = (statement) => out.push({ warnings: [], offers: [], ...statement });
+    const afterConstraints = (after.constraints ?? []).map((c) => ({
+        row: c,
+        id: rowId('constraint', c),
+    }));
+    const beforeConstraints = (before.constraints ?? []).map((c) => ({
+        row: c,
+        id: rowId('constraint', c),
+    }));
+    const afterIndexes = (after.indexes ?? []).map((i) => ({ row: i, id: rowId('index', i) }));
+    const beforeIndexes = (before.indexes ?? []).map((i) => ({ row: i, id: rowId('index', i) }));
+    checkUnique('constraint', afterConstraints.map((c) => c.id));
+    checkUnique('index', afterIndexes.map((i) => i.id));
+    // --- What changed, constraints and indexes
+    const dropConstraints = [];
+    const addConstraints = [];
+    const renameConstraints = [];
+    for (const was of beforeConstraints) {
+        const is = afterConstraints.find((c) => c.id === was.id);
+        if (!is) {
+            dropConstraints.push(was);
+            continue;
+        }
+        const wasShape = shapeKey(constraintShape(before, old, was.row));
+        const isShape = shapeKey(constraintShape(after, next, is.row));
+        if (wasShape !== isShape) {
+            dropConstraints.push(was);
+            addConstraints.push(is);
+        }
+        else if (is.row.name && was.row.name !== is.row.name) {
+            renameConstraints.push({ from: was.row.name ?? '', to: is.row.name, id: was.id });
+        }
+    }
+    for (const is of afterConstraints) {
+        if (!beforeConstraints.some((c) => c.id === is.id))
+            addConstraints.push(is);
+    }
+    const dropIndexes = [];
+    const addIndexes = [];
+    const renameIndexes = [];
+    for (const was of beforeIndexes) {
+        const is = afterIndexes.find((i) => i.id === was.id);
+        if (!is) {
+            dropIndexes.push(was);
+            continue;
+        }
+        if (shapeKey(indexShape(old, was.row)) !== shapeKey(indexShape(next, is.row))) {
+            dropIndexes.push(was);
+            addIndexes.push(is);
+        }
+        else if (is.row.name && was.row.name !== is.row.name) {
+            renameIndexes.push({ from: was.row.name ?? '', to: is.row.name, id: was.id });
+        }
+    }
+    for (const is of afterIndexes) {
+        if (!beforeIndexes.some((i) => i.id === is.id))
+            addIndexes.push(is);
+    }
+    // --- 1. Drop constraints and indexes that go or change
+    for (const { row, id } of dropConstraints) {
+        if (!row.name)
+            throw new AlterError('A constraint to drop has no name');
+        const key = `drop-constraint:${id}`;
+        add({
+            key,
+            sql: `ALTER TABLE ${table} DROP CONSTRAINT ${quoteIdentifier(row.name)}${chosen(options.cascade, key) ? ' CASCADE' : ''}`,
+            drop: { kind: 'constraint', schema: before.schema, name: before.name, detail: row.name },
+            offers: ['cascade'],
+        });
+    }
+    for (const { row, id } of dropIndexes) {
+        if (!row.name)
+            throw new AlterError('An index to drop has no name');
+        const key = `drop-index:${id}`;
+        add({
+            key,
+            sql: `DROP INDEX ${quoteIdentifier(before.schema)}.${quoteIdentifier(row.name)}${chosen(options.cascade, key) ? ' CASCADE' : ''}`,
+            drop: { kind: 'index', schema: before.schema, name: row.name },
+            offers: ['cascade'],
+        });
+    }
+    // --- 2. Drop columns
+    for (const [id, column] of old.columns) {
+        if (next.columns.has(id))
+            continue;
+        const key = `drop-column:${id}`;
+        add({
+            key,
+            sql: `ALTER TABLE ${table} DROP COLUMN ${quoteIdentifier(column.name)}${chosen(options.cascade, key) ? ' CASCADE' : ''}`,
+            drop: { kind: 'column', schema: before.schema, name: before.name, detail: column.name },
+            offers: ['cascade'],
+        });
+    }
+    // --- 3. Rename columns
+    for (const [id, column] of old.columns) {
+        const edited = next.columns.get(id);
+        if (edited && edited.name !== column.name) {
+            add({
+                key: `rename-column:${id}`,
+                sql: `ALTER TABLE ${table} RENAME COLUMN ${quoteIdentifier(column.name)} TO ${quoteIdentifier(edited.name)}`,
+            });
+        }
+    }
+    // --- 4. Add columns
+    const tableBefore = { schema: before.schema, name: before.name };
+    for (const [id, column] of next.columns) {
+        if (old.columns.has(id))
+            continue;
+        const warnings = [];
+        if (column.notNull &&
+            !column.default &&
+            !column.identity &&
+            !column.generated &&
+            big(estimate)) {
+            warnings.push(`NOT NULL without a default fails if the table has any rows (${rows(estimate)}).`);
+        }
+        if ((column.default || column.generated || column.identity) && big(estimate)) {
+            warnings.push(`A default that is not constant, or a generated column, rewrites the table (${rows(estimate)}) while it holds a lock.`);
+        }
+        add({
+            key: `add-column:${id}`,
+            sql: `ALTER TABLE ${table} ADD COLUMN ${columnSql(column)}`,
+            warnings,
+        });
+    }
+    // --- 5. Change columns that stay
+    for (const [id, was] of old.columns) {
+        const is = next.columns.get(id);
+        if (!is)
+            continue;
+        const column = `ALTER TABLE ${table} ALTER COLUMN ${quoteIdentifier(is.name)}`;
+        const wasGenerated = was.generated !== undefined;
+        const isGenerated = is.generated !== undefined;
+        if (!wasGenerated && isGenerated) {
+            throw new AlterError(`"${is.name}" cannot become a generated column in place: add a new column and drop this one`);
+        }
+        if (was.identity && !is.identity) {
+            add({ key: `identity:${id}`, sql: `${column} DROP IDENTITY` });
+        }
+        if (wasGenerated && !isGenerated) {
+            add({ key: `generated:${id}`, sql: `${column} DROP EXPRESSION` });
+        }
+        else if (wasGenerated && isGenerated && !same(was.generated, is.generated)) {
+            if (serverMajor < 17) {
+                throw new AlterError(`Changing the expression of "${is.name}" needs PostgreSQL 17 or later`);
+            }
+            add({
+                key: `generated:${id}`,
+                sql: `${column} SET EXPRESSION AS (${is.generated.trim()})`,
+                warnings: big(estimate) ? [`Recomputes every row (${rows(estimate)}).`] : [],
+            });
+        }
+        if (typeSql(was.type) !== typeSql(is.type)) {
+            const using = options.using?.[id]?.trim();
+            add({
+                key: `type:${id}`,
+                sql: `${column} TYPE ${typeSql(is.type)}${using ? ` USING ${using}` : ''}`,
+                warnings: rewritesTable(was.type, is.type)
+                    ? [
+                        `Changing the type rewrites the table (${rows(estimate)}), holding a lock that blocks reads and writes meanwhile.`,
+                    ]
+                    : [],
+                offers: ['using'],
+            });
+        }
+        if (!isGenerated && !is.identity && !same(was.default, is.default)) {
+            add({
+                key: `default:${id}`,
+                sql: is.default?.trim()
+                    ? `${column} SET DEFAULT ${is.default.trim()}`
+                    : `${column} DROP DEFAULT`,
+            });
+        }
+        if (!!was.notNull !== !!is.notNull) {
+            add({
+                key: `not-null:${id}`,
+                sql: `${column} ${is.notNull ? 'SET' : 'DROP'} NOT NULL`,
+                warnings: is.notNull && big(estimate)
+                    ? [`Checks every row for nulls (${rows(estimate)}) while holding a lock.`]
+                    : [],
+            });
+        }
+        if (is.identity && was.identity !== is.identity) {
+            const kind = is.identity === 'always' ? 'ALWAYS' : 'BY DEFAULT';
+            add({
+                key: `identity:${id}`,
+                sql: was.identity
+                    ? `${column} SET GENERATED ${kind}`
+                    : `${column} ADD GENERATED ${kind} AS IDENTITY`,
+            });
+        }
+    }
+    // --- 6. Rename constraints and indexes that otherwise stay
+    for (const { from, to, id } of renameConstraints) {
+        add({
+            key: `rename-constraint:${id}`,
+            sql: `ALTER TABLE ${table} RENAME CONSTRAINT ${quoteIdentifier(from)} TO ${quoteIdentifier(to)}`,
+        });
+    }
+    for (const { from, to, id } of renameIndexes) {
+        add({
+            key: `rename-index:${id}`,
+            sql: `ALTER INDEX ${quoteIdentifier(before.schema)}.${quoteIdentifier(from)} RENAME TO ${quoteIdentifier(to)}`,
+        });
+    }
+    // --- 7. Add constraints
+    const stub = { ...after, ...tableBefore };
+    const columnNames = new Set(after.columns.map((column) => column.name));
+    for (const { row, id } of addConstraints) {
+        const key = `add-constraint:${id}`;
+        const checked = row.kind === 'foreign' || row.kind === 'check';
+        const notValid = checked && chosen(options.notValid, key);
+        // The table is renamed last, so a key to itself still names the table as it is now.
+        const aimed = row.kind === 'foreign' &&
+            row.references.schema === after.schema &&
+            row.references.table === after.name
+            ? {
+                ...row,
+                references: {
+                    ...row.references,
+                    ...tableBefore,
+                    table: before.name,
+                    schema: before.schema,
+                },
+            }
+            : row;
+        const name = notValid ? (row.name ?? suggestConstraintName(before.name, row)) : row.name;
+        const withName = name === undefined ? aimed : { ...aimed, name };
+        const sql = `ALTER TABLE ${table} ADD ${constraintSql(withName, { serverMajor: options.serverMajor }, columnNames)}${notValid ? ' NOT VALID' : ''}`;
+        const warnings = [];
+        const offers = [];
+        if (checked) {
+            if (big(estimate) && !notValid) {
+                warnings.push(`Checks every existing row (${rows(estimate)}) while holding a lock: it can be added NOT VALID and validated afterwards.`);
+            }
+            offers.push('notValid');
+        }
+        else if (big(estimate)) {
+            warnings.push(`Builds an index over the table (${rows(estimate)}), blocking writes meanwhile.`);
+        }
+        add({ key, sql, warnings, offers });
+        if (notValid) {
+            add({
+                key: `${key}:validate`,
+                sql: `ALTER TABLE ${table} VALIDATE CONSTRAINT ${quoteIdentifier(name)}`,
+            });
+        }
+    }
+    // --- 8. Create indexes
+    for (const { row, id } of addIndexes) {
+        const key = `add-index:${id}`;
+        const concurrent = !after.partition && chosen(options.concurrently, key);
+        let sql = indexSql(stub, row, columnNames);
+        if (concurrent)
+            sql = sql.replace(/^CREATE (UNIQUE )?INDEX /, 'CREATE $1INDEX CONCURRENTLY ');
+        add({
+            key,
+            sql,
+            concurrent,
+            warnings: big(estimate) && !concurrent
+                ? [`Builds an index over the table (${rows(estimate)}), blocking writes meanwhile.`]
+                : [],
+            offers: after.partition ? [] : ['concurrently'],
+        });
+    }
+    // --- 9. Comments
+    const comment = (target, text) => `COMMENT ON ${target} IS ${text ? literal(text) : 'NULL'}`;
+    if (!same(before.comment, after.comment)) {
+        add({ key: 'comment:table', sql: comment(`TABLE ${table}`, after.comment) });
+    }
+    for (const [id, is] of next.columns) {
+        const was = old.columns.get(id);
+        if (!same(was?.comment, is.comment)) {
+            add({
+                key: `comment:${id}`,
+                sql: comment(`COLUMN ${table}.${quoteIdentifier(is.name)}`, is.comment),
+            });
+        }
+    }
+    // --- 10. The table itself
+    if (!!before.unlogged !== !!after.unlogged) {
+        add({
+            key: 'logged',
+            sql: `ALTER TABLE ${table} SET ${after.unlogged ? 'UNLOGGED' : 'LOGGED'}`,
+            warnings: [`Rewrites the table (${rows(estimate)}) while holding a lock.`],
+        });
+    }
+    let current = { ...tableBefore };
+    if (after.schema !== before.schema) {
+        add({
+            key: 'schema',
+            sql: `ALTER TABLE ${qualified(current)} SET SCHEMA ${quoteIdentifier(after.schema)}`,
+            warnings: ['Code and views that name the table by its old schema stop finding it.'],
+        });
+        current = { schema: after.schema, name: current.name };
+    }
+    if (after.name !== before.name) {
+        add({
+            key: 'rename',
+            sql: `ALTER TABLE ${qualified(current)} RENAME TO ${quoteIdentifier(after.name)}`,
+            warnings: ['Code and views that use the old name stop finding the table.'],
+        });
+    }
+    return out;
+}
+/** `DROP TABLE`, as a statement of its own. */
+export function dropTableStatement(table, cascade) {
+    return {
+        key: 'drop-table',
+        sql: `DROP TABLE ${qualified(table)}${cascade ? ' CASCADE' : ''}`,
+        drop: { kind: 'table', schema: table.schema, name: table.name },
+        warnings: [],
+        offers: ['cascade'],
+    };
+}
+/** The statements that run in the transaction, with `lock_timeout` first, and those that run apart. */
+export function splitPlan(statements, lockTimeoutMs) {
+    if (!Number.isInteger(lockTimeoutMs) || lockTimeoutMs < 0) {
+        throw new AlterError('The lock timeout is a number of milliseconds');
+    }
+    const transactional = statements.filter((statement) => !statement.concurrent).map((s) => s.sql);
+    return {
+        transactional: transactional.length > 0
+            ? [`SET LOCAL lock_timeout = '${lockTimeoutMs}ms'`, ...transactional]
+            : [],
+        concurrent: statements.filter((statement) => statement.concurrent).map((s) => s.sql),
+    };
+}
+const stringList = (value, what) => {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new AlterError(`${what} must be a list of text`);
+    }
+    return value;
+};
+/** Reads the options sent with an edit, refusing anything that is not what they should be. */
+export function parseAlterOptions(value) {
+    if (value === undefined || value === null)
+        return {};
+    if (typeof value !== 'object' || Array.isArray(value))
+        throw new AlterError('options must be an object');
+    const raw = value;
+    const using = {};
+    if (raw.using !== undefined && raw.using !== null) {
+        if (typeof raw.using !== 'object' || Array.isArray(raw.using)) {
+            throw new AlterError('using must be an object');
+        }
+        for (const [id, text] of Object.entries(raw.using)) {
+            if (typeof text !== 'string')
+                throw new AlterError('A USING expression must be text');
+            using[id] = text;
+        }
+    }
+    return {
+        using,
+        notValid: stringList(raw.notValid, 'notValid'),
+        concurrently: stringList(raw.concurrently, 'concurrently'),
+        cascade: stringList(raw.cascade, 'cascade'),
+    };
+}

package/dist/explorer/catalog.js

@@ -62,9 +62,14 @@ export async function listTables(session, schema, name) {
 				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]);
@@ -74,6 +79,8 @@ export async function listTables(session, schema, 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,
     }));
 }
@@ -233,6 +240,30 @@ export async function describeCatalog(session) {
     }
     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);

package/dist/explorer/connect-entry.js

@@ -5,27 +5,38 @@ import { resolveEntry } from '../environments.js';
 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 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);
-    }
+    const [session] = await connectEntries(entry, services, 1, options);
+    return session;
 }