@kazurolabs/psql-explorer 0.0.0-stage → 0.1.0

package/dist/commands/configgen.js

@@ -0,0 +1,128 @@
+// `psql-explorer configgen:file` and `psql-explorer configgen:vault` print a fully commented
+// example environment file, ready to copy. Every key the loader accepts appears, optional ones
+// commented out.
+const sources = `A setting is plain text (\`host: db.prod.internal\`) or a source and a value:
+  source: plaintext | inline | env | file | stored | vault | prompt`;
+const access = `# production | reference | demo | development | local. Required.
+tier: production
+
+# Shown with a shield and in red. Optional, default: true for the production tier.
+protected: true
+
+# Open every session read only (default_transaction_read_only), so nothing run here can change
+# data. Optional, default: the value of protected.
+readOnly: true
+`;
+const fileEnvironment = `# One environment: <environment>/explorer.yaml below the base path.
+# Use with: psql-explorer --config <base path>   (or export PSQL_EXPLORER_ENVIRONMENTS=<base path>)
+# The environment is named after its folder: lower case letters, digits, - and _.
+# ${sources.replaceAll('\n', '\n# ')}
+# Unknown keys are an error.
+
+${access}
+# Where the database is. Required. Any of these can use a source instead of plain text.
+host: db.prod.internal
+port: 5432
+database: app
+
+# The schema browsing starts in. Optional, default: public
+# schema: app
+
+# Database login. username is required unless the login comes from Vault (see the vault example).
+username: readonly
+
+# password (default) needs a password; none means the database takes no password.
+auth: password
+
+# Required when auth is password. Left out when auth is none.
+password:
+  source: file
+  value: ./password.txt # relative to this file's folder; the whole content, trimmed
+# Other ways to supply it:
+# password: s3cret                       # plain text, in the file itself
+# password: {source: env, value: DB_PASSWORD}   # an environment variable
+# password: {source: stored, value: prod-password}   # a secret kept in the local store
+# password: {source: prompt}   # asked for when connecting
+# password: {source: vault, value: "secret/data/db/prod#password"}   # a key of a Vault KV v2 secret
+
+# TLS. Optional, default: mode disable
+tls:
+  # disable | require | verify-ca | verify-full
+  mode: verify-full
+  # CA certificate (PEM text). Required for verify-ca and verify-full.
+  ca:
+    source: file
+    value: ./certs/ca.pem
+  # Client certificate and its private key, for mutual TLS. Give both or neither.
+  # cert:
+  #   source: file
+  #   value: ./certs/client.pem
+  # key:
+  #   source: file
+  #   value: ./certs/client-key.pem
+  # Only when the key is encrypted.
+  # keyPassphrase:
+  #   source: file
+  #   value: ./certs/client-key.pass
+`;
+const vaultEnvironment = `# One environment, stored as the explorer.yaml key of a secret below the base path:
+#   vault kv put secret/psql-explorer/production explorer.yaml=@production.yaml
+# Use with: psql-explorer --config vault:secret/data/psql-explorer
+# The environment is named after the last part of the secret's path: lower case letters,
+# digits, - and _. Who can read the secret decides who sees the environment.
+# ${sources.replaceAll('\n', '\n# ')}
+# \`file\` values are relative to the working directory here, not to a folder.
+# Unknown keys are an error.
+
+${access}
+# Where the database is. Required. Any of these can use a source instead of plain text.
+host:
+  source: vault
+  value: secret/data/db/prod#host # "<KV v2 data path>#<key>"
+port: 5432
+database: app
+
+# The schema browsing starts in. Optional, default: public
+# schema: app
+
+# Short-lived login issued by Vault's database secrets engine on every connect, and revoked when
+# you leave the environment. It fills username and password: set neither, and auth must stay
+# password.
+credentials:
+  source: vault-database
+  value: database/creds/readonly
+# Or a fixed login instead of credentials:
+# username: readonly
+# auth: password          # password (default) | none
+# password:               # required when auth is password
+#   source: vault
+#   value: secret/data/db/prod#password
+
+# TLS. Optional, default: mode disable
+tls:
+  # disable | require | verify-ca | verify-full
+  mode: verify-full
+  # Client certificate issued by Vault's PKI engine. It fills cert and key (set neither),
+  # and ca too unless you give one. Has no effect with mode disable.
+  client:
+    source: vault-pki
+    value: pki/issue/psql-explorer
+    commonName: psql-explorer
+  # CA certificate (PEM text). Required for verify-ca and verify-full unless client is given.
+  # ca:
+  #   source: vault
+  #   value: secret/data/db/prod#ca
+  # A fixed client certificate and key instead of client. Give both or neither.
+  # cert:
+  #   source: vault
+  #   value: secret/data/db/prod#cert
+  # key:
+  #   source: vault
+  #   value: secret/data/db/prod#key
+  # keyPassphrase:        # only when the key is encrypted
+  #   source: vault
+  #   value: secret/data/db/prod#key-passphrase
+`;
+export function configgen(kind) {
+    return kind === 'file' ? fileEnvironment : vaultEnvironment;
+}

package/dist/commands/explore.js

@@ -0,0 +1,306 @@
+// The commands that work without the TUI: list environments, look at what is in a database, page
+// through a table and run SQL. Each prints its result on stdout (as a table, CSV or JSON) and
+// returns the exit code; what went wrong goes to stderr.
+import { addressOf, findEnvironment, listEnvironments, } from '../environments.js';
+import { describeTable, listSchemas, listTables, parseTableRef, serverInfo, tableLabel, } from '../explorer/catalog.js';
+import { commandSummary, formatBytes, formatDuration, formatEstimate, formatResult, outputFormats, } from '../explorer/format.js';
+import { browseRows, DEFAULT_PAGE_SIZE } from '../explorer/rows.js';
+import { DEFAULT_MAX_ROWS, describeQueryError, } from '../explorer/session.js';
+import { connectEntry } from '../explorer/connect-entry.js';
+export const commandNames = [
+    'envs',
+    'schemas',
+    'tables',
+    'describe',
+    'rows',
+    'query',
+    'info',
+    'history',
+];
+export const isCommand = (name) => commandNames.includes(name);
+/** Thrown for a wrong command line: exit code 2. */
+class UsageError extends Error {
+}
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+// A listing of the explorer's own (not a query's), where nothing is shown for a missing value.
+const result = (columns, rows) => ({
+    command: 'SELECT',
+    columns: columns.map((name) => ({ name, type: 'text' })),
+    rows: rows.map((row) => row.map((value) => value ?? '')),
+    rowCount: rows.length,
+    truncated: false,
+    durationMs: 0,
+});
+const text = (value) => value === null || value === undefined ? null : String(value);
+function formatOf(flags) {
+    if (flags.json)
+        return 'json';
+    const format = flags.format ?? 'table';
+    if (!outputFormats.includes(format)) {
+        throw new UsageError(`--format must be one of: ${outputFormats.join(', ')}`);
+    }
+    return format;
+}
+function environmentFor(options) {
+    const { env } = options.flags;
+    if (!env)
+        throw new UsageError(`${options.command} needs --env <name>`);
+    const entry = findEnvironment(options.services, env);
+    if (entry)
+        return entry;
+    const names = listEnvironments(options.services).map((candidate) => candidate.name);
+    throw new Error(`no environment named "${env}"${names.length > 0 ? `; there are: ${names.join(', ')}` : ''}`);
+}
+/** Looks up the environment's settings (Vault, prompts, ...) and connects. */
+function connect(options, entry) {
+    const { timeout } = options.flags;
+    return connectEntry(entry, options.services, {
+        ...(timeout === undefined ? {} : { statementTimeoutMs: timeout === 0 ? null : timeout * 1000 }),
+    });
+}
+async function withSession(options, work) {
+    const entry = environmentFor(options);
+    const session = await connect(options, entry);
+    try {
+        return await work(session, entry);
+    }
+    finally {
+        await session.close();
+        // Credentials issued for this command end with it.
+        await options.services.groups?.release(entry.name);
+    }
+}
+function envs(options) {
+    const format = formatOf(options.flags);
+    const entries = listEnvironments(options.services);
+    if (format === 'json') {
+        options.out(`${JSON.stringify(entries.map((entry) => ({
+            name: entry.name,
+            source: entry.source,
+            tier: entry.tier,
+            protected: entry.protected,
+            readOnly: entry.readOnly,
+            address: addressOf(entry),
+            tls: entry.tlsMode,
+        })), null, 2)}\n`);
+    }
+    else {
+        options.out(formatResult(result(['name', 'source', 'tier', 'access', 'address'], entries.map((entry) => [
+            entry.name,
+            entry.source,
+            entry.tier,
+            entry.readOnly ? 'read only' : 'read write',
+            addressOf(entry),
+        ])), format));
+    }
+    const error = options.services.configError;
+    if (error)
+        options.err(`psql-explorer: ${error.message}\n`);
+    return 0;
+}
+const json = (options, value) => {
+    options.out(`${JSON.stringify(value, null, 2)}\n`);
+};
+async function schemas(options, session) {
+    const format = formatOf(options.flags);
+    const found = await listSchemas(session);
+    if (format === 'json')
+        json(options, found);
+    else {
+        options.out(formatResult(result(['name', 'owner', 'tables'], found.map((schema) => [schema.name, schema.owner, String(schema.tables)])), format));
+    }
+    return 0;
+}
+async function tables(options, session) {
+    const format = formatOf(options.flags);
+    const schema = options.flags.schema ?? session.params.schema;
+    const found = await listTables(session, schema);
+    if (format === 'json')
+        json(options, found);
+    else {
+        options.out(formatResult(result(['name', 'kind', 'rows', 'size', 'comment'], found.map((table) => [
+            table.name,
+            table.kind,
+            format === 'table' ? formatEstimate(table.estimatedRows) : text(table.estimatedRows),
+            format === 'table' ? formatBytes(table.totalBytes) : text(table.totalBytes),
+            table.comment,
+        ])), format));
+    }
+    if (found.length === 0)
+        options.err(`psql-explorer: schema ${schema} has no tables\n`);
+    return 0;
+}
+const tableArgument = (options, session) => {
+    const [name] = options.args;
+    if (!name)
+        throw new UsageError(`${options.command} needs a table, e.g. users or app.users`);
+    return parseTableRef(name, options.flags.schema ?? session.params.schema);
+};
+async function describe(options, session) {
+    const format = formatOf(options.flags);
+    const details = await describeTable(session, tableArgument(options, session));
+    if (format === 'json') {
+        json(options, details);
+        return 0;
+    }
+    const columns = result(['column', 'type', 'nullable', 'default', 'key', 'comment'], details.columns.map((column) => [
+        column.name,
+        column.type,
+        column.nullable ? 'yes' : 'no',
+        column.default,
+        column.primaryKey ? 'PK' : null,
+        column.comment,
+    ]));
+    const indexes = result(['index', 'definition', 'size'], details.indexes.map((index) => [index.name, index.definition, formatBytes(index.bytes)]));
+    const constraints = result(['constraint', 'kind', 'definition'], details.constraints.map((constraint) => [
+        constraint.name,
+        constraint.kind,
+        constraint.definition,
+    ]));
+    if (format === 'csv') {
+        options.out(formatResult(columns, 'csv'));
+        return 0;
+    }
+    options.out(`Table ${tableLabel(details.table)}\n\n${formatResult(columns, 'table')}`);
+    if (details.indexes.length > 0)
+        options.out(`\nIndexes\n${formatResult(indexes, 'table')}`);
+    if (details.constraints.length > 0) {
+        options.out(`\nConstraints\n${formatResult(constraints, 'table')}`);
+    }
+    return 0;
+}
+const orderOf = (flags) => flags.order
+    ? flags.order
+        .split(',')
+        .map((column) => ({ column: column.trim(), descending: flags.desc ?? false }))
+    : [];
+async function rows(options, session) {
+    const format = formatOf(options.flags);
+    const table = tableArgument(options, session);
+    const limit = options.flags.limit ?? DEFAULT_PAGE_SIZE;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new UsageError('--limit must be at least 1');
+    const offset = options.flags.offset ?? 0;
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new UsageError('--offset must be 0 or more');
+    const page = await browseRows(session, table, { limit, offset, orderBy: orderOf(options.flags) });
+    options.out(formatResult(page, format));
+    return 0;
+}
+async function sqlOf(options) {
+    const [given] = options.args;
+    if (given !== undefined && given !== '-')
+        return given;
+    if (given === undefined && options.stdinIsTTY) {
+        throw new UsageError('query needs SQL: query --env <name> "<sql>", or pipe it in');
+    }
+    return options.readStdin();
+}
+async function query(options, session, entry, sql) {
+    const format = formatOf(options.flags);
+    const maxRows = options.flags.maxRows ?? DEFAULT_MAX_ROWS;
+    const started = performance.now();
+    let ran;
+    try {
+        ran = await session.run(sql, [], { maxRows });
+    }
+    catch (error) {
+        const message = describeQueryError(error);
+        options.services.store.recordQuery({
+            envName: entry.name,
+            sql,
+            durationMs: performance.now() - started,
+            error: message,
+        });
+        options.err(`psql-explorer: ${message}\n`);
+        return 1;
+    }
+    options.services.store.recordQuery({
+        envName: entry.name,
+        sql,
+        durationMs: ran.durationMs,
+        rowCount: ran.rowCount ?? ran.rows.length,
+    });
+    if (ran.columns.length > 0)
+        options.out(formatResult(ran, format));
+    else if (format === 'json')
+        json(options, { command: ran.command, rowCount: ran.rowCount });
+    else if (format === 'table')
+        options.out(`${commandSummary(ran)}\n`);
+    if (ran.truncated) {
+        options.err(`psql-explorer: showing the first ${ran.rows.length} rows; raise --max-rows for more\n`);
+    }
+    return 0;
+}
+async function info(options, session, entry) {
+    const format = formatOf(options.flags);
+    const server = await serverInfo(session);
+    if (format === 'json') {
+        json(options, { environment: entry.name, ...server });
+        return 0;
+    }
+    options.out(formatResult(result(['setting', 'value'], [
+        ['environment', entry.name],
+        ['server', server.version],
+        ['database', server.database],
+        ['user', server.user],
+        ['size', formatBytes(server.databaseBytes)],
+        ['started', server.startedAt],
+        ['read only', server.readOnly ? 'yes' : 'no'],
+        ['time zone', server.timeZone],
+        ['search path', server.searchPath],
+        ['encoding', server.encoding],
+    ]), format));
+    return 0;
+}
+function history(options) {
+    const format = formatOf(options.flags);
+    const entry = environmentFor(options);
+    const records = options.services.store.historyFor(entry.name, options.flags.limit ?? 50);
+    if (format === 'json')
+        json(options, records);
+    else {
+        options.out(formatResult(result(['at', 'duration', 'rows', 'sql', 'error'], records.map((record) => [
+            record.at.slice(0, 19).replace('T', ' '),
+            formatDuration(record.durationMs),
+            text(record.rowCount),
+            record.sql,
+            record.error,
+        ])), format));
+    }
+    return 0;
+}
+/** Runs one command; never throws. 0 done, 1 failed, 2 wrong command line. */
+export async function runCommand(options) {
+    try {
+        switch (options.command) {
+            case 'envs':
+                return envs(options);
+            case 'history':
+                return history(options);
+            case 'schemas':
+                return await withSession(options, (session) => schemas(options, session));
+            case 'tables':
+                return await withSession(options, (session) => tables(options, session));
+            case 'describe':
+                return await withSession(options, (session) => describe(options, session));
+            case 'rows':
+                return await withSession(options, (session) => rows(options, session));
+            case 'query': {
+                // Read before connecting, so a wrong command line costs no login.
+                formatOf(options.flags);
+                const sql = (await sqlOf(options)).trim();
+                if (!sql)
+                    throw new UsageError('the SQL is empty');
+                return await withSession(options, (session, entry) => query(options, session, entry, sql));
+            }
+            case 'info':
+                return await withSession(options, (session, entry) => info(options, session, entry));
+        }
+    }
+    catch (error) {
+        const message = error instanceof UsageError ? error.message : describeQueryError(error);
+        options.err(`psql-explorer: ${message || messageOf(error)}\n`);
+        return error instanceof UsageError ? 2 : 1;
+    }
+}

package/dist/commands/terminal-prompt.js

@@ -0,0 +1,68 @@
+import { ResolveError } from '../config/resolvers/index.js';
+/**
+ * Asks on the terminal, for commands run by a person: the question goes to stderr so stdout stays
+ * the command's output, and a secret is read without echo. One question at a time.
+ */
+export function createTerminalPrompter(input = process.stdin, output = process.stderr) {
+    let queue = Promise.resolve();
+    const ask = ({ envName, field, masked, challenge, signal }) => new Promise((resolve, reject) => {
+        let answer = '';
+        const wasRaw = input.isRaw;
+        const finish = (error) => {
+            input.off('data', onData);
+            signal?.removeEventListener('abort', onAbort);
+            input.setRawMode?.(wasRaw);
+            input.pause();
+            output.write('\n');
+            if (error)
+                reject(error);
+            else
+                resolve(answer);
+        };
+        const onAbort = () => {
+            finish(new ResolveError(envName, field, 'cancelled'));
+        };
+        const onData = (chunk) => {
+            for (const char of chunk.toString('utf8')) {
+                if (char === '\r' || char === '\n') {
+                    if (answer)
+                        finish();
+                    return;
+                }
+                if (char === '\u0003' || char === '\u001b') {
+                    finish(new ResolveError(envName, field, 'cancelled'));
+                    return;
+                }
+                if (char === '\u007f' || char === '\b') {
+                    if (answer) {
+                        answer = [...answer].slice(0, -1).join('');
+                        output.write('\b \b');
+                    }
+                    continue;
+                }
+                if (char < ' ')
+                    continue;
+                answer += char;
+                output.write(masked ? '*' : char);
+            }
+        };
+        if (signal?.aborted) {
+            reject(new ResolveError(envName, field, 'cancelled'));
+            return;
+        }
+        output.write(challenge === undefined
+            ? `${envName}.${field} (${masked ? 'secret' : 'value'}): `
+            : `${envName} is protected. Type "${challenge}" to continue: `);
+        input.setRawMode?.(true);
+        input.resume();
+        input.on('data', onData);
+        signal?.addEventListener('abort', onAbort);
+    });
+    return {
+        ask(request) {
+            const next = queue.then(() => ask(request), () => ask(request));
+            queue = next.catch(() => undefined);
+            return next;
+        },
+    };
+}