neonctl 2.35.1 → 2.36.0

package/dist/commands/index.js

@@ -14,6 +14,7 @@ import * as diff from "./diff.js";
 import * as env from "./env.js";
 import * as functions from "./functions.js";
 import * as init from "./init.js";
+import * as inspect from "./inspect.js";
 import * as ipAllow from "./ip_allow.js";
 import * as link from "./link.js";
 import * as neonAuth from "./neon_auth.js";
@@ -41,6 +42,7 @@ export default [
     roles,
     operations,
     snapshots,
+    inspect,
     cs,
     psql,
     setContext,

package/dist/commands/inspect.js

@@ -0,0 +1,65 @@
+import { fillSingleProject } from "../utils/enrichers.js";
+import { resolveConnectionUri, runInspectQuery } from "../utils/inspect_db.js";
+import { INSPECT_QUERIES, } from "../utils/inspect_queries.js";
+import { writer } from "../writer.js";
+export const command = "inspect";
+export const describe = "Inspect a database's health and configuration";
+export const aliases = ["inspection"];
+/**
+ * `fillSingleProject` hits the API to auto-resolve a project. When the user
+ * passes `--db-url` we bypass the Neon API entirely, so skip it.
+ */
+const fillSingleProjectUnlessDbUrl = async (props) => {
+    if (props.dbUrl) {
+        return props;
+    }
+    return fillSingleProject(props);
+};
+const runSubcommand = async (name, props) => {
+    const query = INSPECT_QUERIES[name];
+    const connectionUri = props.dbUrl ?? (await resolveConnectionUri(props)).connectionUri;
+    const rows = await runInspectQuery(connectionUri, query.sql, {
+        requiresExtension: query.requiresExtension,
+    });
+    writer(props).end(rows, {
+        fields: query.fields,
+        emptyMessage: query.emptyMessage,
+    });
+};
+const dbBuilder = (argv) => {
+    let builder = argv
+        .usage("$0 inspect db <sub-command> [options]")
+        .options({
+        "project-id": {
+            describe: "Project ID",
+            type: "string",
+        },
+        branch: {
+            describe: "Branch ID or name",
+            type: "string",
+        },
+        "database-name": {
+            describe: "Database name",
+            type: "string",
+        },
+        "role-name": {
+            describe: "Role name",
+            type: "string",
+        },
+        "db-url": {
+            describe: "Inspect any Postgres via a connection string, bypassing the Neon API (project/branch resolution is skipped)",
+            type: "string",
+        },
+    })
+        .middleware(fillSingleProjectUnlessDbUrl);
+    for (const name of Object.keys(INSPECT_QUERIES)) {
+        builder = builder.command(name, INSPECT_QUERIES[name].describe, (yargs) => yargs, (args) => runSubcommand(name, args));
+    }
+    return builder;
+};
+export const builder = (argv) => argv
+    .usage("$0 inspect <sub-command> [options]")
+    .command("db", "Run a diagnostic query against a branch's Postgres", dbBuilder);
+export const handler = (args) => {
+    return args;
+};

package/dist/utils/inspect_db.js

@@ -0,0 +1,153 @@
+import { parseConnectionUri } from "../psql/index.js";
+import { PgConnection } from "../psql/wire/connection.js";
+import { EndpointType } from "./api_enums.js";
+import { branchIdFromProps } from "./enrichers.js";
+import { parsePITBranch } from "./point_in_time.js";
+export const SSL_MODES = [
+    "require",
+    "verify-ca",
+    "verify-full",
+    "omit",
+];
+/**
+ * Resolve a branch's live Postgres connection details via the Neon API
+ * (endpoint → role → password → database → URL, honoring point-in-time,
+ * pooling, prisma tuning, and SSL mode). Mirrors how `connection-string`
+ * resolves a branch so `inspect db` connects the same way.
+ */
+export const resolveConnectionUri = async (props) => {
+    const projectId = props.projectId;
+    const parsedPIT = props.branch
+        ? parsePITBranch(props.branch)
+        : { tag: "head", branch: "" };
+    if (props.branch) {
+        props.branch = parsedPIT.branch;
+    }
+    const branchId = await branchIdFromProps(props);
+    const { data: { endpoints }, } = await props.apiClient.listProjectBranchEndpoints(projectId, branchId);
+    const matchEndpointType = props.endpointType ?? EndpointType.ReadWrite;
+    let endpoint = endpoints.find((e) => e.type === matchEndpointType);
+    if (!endpoint && props.endpointType == null) {
+        endpoint = endpoints[0];
+    }
+    if (!endpoint) {
+        throw new Error(`No ${props.endpointType ?? ""} endpoint found for the branch: ${branchId}`);
+    }
+    const role = props.roleName ||
+        (await props.apiClient
+            .listProjectBranchRoles(projectId, branchId)
+            .then(({ data }) => {
+            if (data.roles.length === 0) {
+                throw new Error(`No roles found for the branch: ${branchId}`);
+            }
+            if (data.roles.length === 1) {
+                return data.roles[0].name;
+            }
+            throw new Error(`Multiple roles found for the branch, please provide one with the --role-name option: ${data.roles
+                .map((r) => r.name)
+                .join(", ")}`);
+        }));
+    const { data: { databases: branchDatabases }, } = await props.apiClient.listProjectBranchDatabases(projectId, branchId);
+    const database = props.databaseName ||
+        (() => {
+            if (branchDatabases.length === 0) {
+                throw new Error(`No databases found for the branch: ${branchId}`);
+            }
+            if (branchDatabases.length === 1) {
+                return branchDatabases[0].name;
+            }
+            throw new Error(`Multiple databases found for the branch, please provide one with the --database-name option: ${branchDatabases
+                .map((d) => d.name)
+                .join(", ")}`);
+        })();
+    if (!branchDatabases.find((d) => d.name === database)) {
+        throw new Error(`Database not found: ${database}`);
+    }
+    const { data: { password }, } = await props.apiClient.getProjectBranchRolePassword(props.projectId, endpoint.branch_id, role);
+    let host = props.pooled
+        ? endpoint.host.replace(endpoint.id, `${endpoint.id}-pooler`)
+        : endpoint.host;
+    if (parsedPIT.tag !== "head") {
+        host = endpoint.host.replace(endpoint.id, endpoint.branch_id);
+    }
+    const connectionString = new URL(`postgresql://${host}`);
+    connectionString.pathname = database;
+    connectionString.username = role;
+    connectionString.password = password;
+    if (props.prisma) {
+        connectionString.searchParams.set("connect_timeout", "30");
+        if (props.pooled) {
+            connectionString.searchParams.set("pool_timeout", "30");
+            connectionString.searchParams.set("pgbouncer", "true");
+        }
+    }
+    const ssl = props.ssl ?? "require";
+    if (ssl !== "omit") {
+        connectionString.searchParams.set("sslmode", ssl);
+        connectionString.searchParams.set("channel_binding", "require");
+    }
+    if (parsedPIT.tag === "lsn") {
+        connectionString.searchParams.set("options", `neon_lsn:${parsedPIT.lsn}`);
+    }
+    else if (parsedPIT.tag === "timestamp") {
+        connectionString.searchParams.set("options", `neon_timestamp:${parsedPIT.timestamp}`);
+    }
+    return {
+        connectionUri: connectionString.toString(),
+        host,
+        role,
+        password,
+        database,
+        options: connectionString.searchParams.toString(),
+    };
+};
+const rowsFrom = (result) => {
+    const names = result.fields.map((f) => f.name);
+    return result.rows.map((row) => {
+        const obj = {};
+        names.forEach((name, i) => {
+            obj[name] = row[i];
+        });
+        return obj;
+    });
+};
+/**
+ * Connect to `connectionUri` with the embedded wire client, run a single
+ * read-only `sql`, and return the rows as objects keyed by column name (so the
+ * shared `writer` can render them by field). The connection is always closed,
+ * even on error.
+ */
+export const runInspectQuery = async (connectionUri, sql, options = {}) => {
+    const opts = parseConnectionUri(connectionUri);
+    let connection;
+    try {
+        connection = await PgConnection.connect(opts);
+    }
+    catch (err) {
+        // Give the failure a Postgres-specific message. The raw socket error
+        // (e.g. ECONNREFUSED) would otherwise be mislabeled by the top-level
+        // `isNetworkError` handler as a "Could not reach the Neon API" hint —
+        // misleading for `inspect db`, which talks to Postgres, not the API.
+        // We intentionally do not chain `cause` so that classifier can't match
+        // the socket `code`; the underlying reason is preserved in the message.
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not connect to Postgres at ${opts.host}:${opts.port}: ${reason}`);
+    }
+    try {
+        const ext = options.requiresExtension;
+        if (ext) {
+            // `ext` is an internal constant from INSPECT_QUERIES, never user input,
+            // so interpolating it into the literal is safe.
+            const check = await connection.query(`SELECT 1 FROM pg_extension WHERE extname = '${ext}';`);
+            if (check.rows.length === 0) {
+                throw new Error(`This query needs the "${ext}" extension, which is not installed. ` +
+                    `Enable it with: CREATE EXTENSION ${ext};`);
+            }
+        }
+        const result = await connection.query(sql);
+        return rowsFrom(result);
+    }
+    finally {
+        await connection.close();
+    }
+};

package/dist/utils/inspect_queries.js

@@ -0,0 +1,372 @@
+/**
+ * Diagnostic SQL for `neon inspect db`. Each entry is a read-only query against
+ * Postgres' own statistics/catalog views plus the output columns (in display
+ * order) the table/json/yaml formatter should show.
+ *
+ * Most queries need no extra extension. The few that do (currently `outliers`
+ * and `calls`, which read `pg_stat_statements`) declare it via
+ * `requiresExtension`; the runner checks for it and fails with an actionable
+ * hint when it's missing.
+ */
+export const INSPECT_QUERIES = {
+    "table-sizes": {
+        describe: "Size of each table (including TOAST), largest first (pg_table_size)",
+        fields: ["schema", "name", "size"],
+        emptyMessage: "No user tables found.",
+        sql: /* sql */ `
+			SELECT
+				n.nspname AS schema,
+				c.relname AS name,
+				pg_size_pretty(pg_table_size(c.oid)) AS size
+			FROM pg_class c
+			LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
+			WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+				AND n.nspname !~ '^pg_toast'
+				AND c.relkind = 'r'
+			ORDER BY pg_table_size(c.oid) DESC;
+		`,
+    },
+    "index-sizes": {
+        describe: "Size of each index, largest first (pg_relation_size)",
+        fields: ["schema", "name", "size"],
+        emptyMessage: "No indexes found.",
+        sql: /* sql */ `
+			SELECT
+				n.nspname AS schema,
+				c.relname AS name,
+				pg_size_pretty(pg_relation_size(c.oid)) AS size
+			FROM pg_class c
+			LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
+			WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+				AND n.nspname !~ '^pg_toast'
+				AND c.relkind = 'i'
+			ORDER BY pg_relation_size(c.oid) DESC;
+		`,
+    },
+    "unused-indexes": {
+        describe: "Non-unique indexes with few scans — candidates for removal (pg_stat_user_indexes)",
+        fields: ["table", "index", "index_size", "index_scans"],
+        emptyMessage: "No unused indexes detected.",
+        sql: /* sql */ `
+			SELECT
+				s.schemaname || '.' || s.relname AS "table",
+				s.indexrelname AS index,
+				pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size,
+				s.idx_scan AS index_scans
+			FROM pg_stat_user_indexes s
+			JOIN pg_index i ON i.indexrelid = s.indexrelid
+			WHERE NOT i.indisunique
+				AND NOT i.indisprimary
+				AND s.idx_scan < 50
+			ORDER BY pg_relation_size(s.indexrelid) DESC, s.idx_scan ASC;
+		`,
+    },
+    "seq-scans": {
+        describe: "Number of sequential scans recorded against each table (pg_stat_user_tables)",
+        fields: ["schema", "name", "count"],
+        emptyMessage: "No user tables found.",
+        sql: /* sql */ `
+			SELECT
+				schemaname AS schema,
+				relname AS name,
+				seq_scan AS count
+			FROM pg_stat_user_tables
+			ORDER BY seq_scan DESC;
+		`,
+    },
+    "long-running-queries": {
+        describe: "Queries running longer than 5 minutes (pg_stat_activity)",
+        fields: ["pid", "duration", "state", "query"],
+        emptyMessage: "No long-running queries.",
+        sql: /* sql */ `
+			SELECT
+				pid,
+				(now() - query_start)::text AS duration,
+				state,
+				query
+			FROM pg_stat_activity
+			WHERE state <> 'idle'
+				AND query NOT ILIKE '%pg_stat_activity%'
+				AND now() - query_start > interval '5 minutes'
+			ORDER BY now() - query_start DESC;
+		`,
+    },
+    locks: {
+        describe: "Locks held with the acquiring query and its age (pg_locks + pg_stat_activity)",
+        fields: [
+            "pid",
+            "relname",
+            "mode",
+            "locktype",
+            "granted",
+            "age",
+            "query",
+        ],
+        emptyMessage: "No locks held.",
+        sql: /* sql */ `
+			SELECT
+				a.pid,
+				c.relname,
+				l.mode,
+				l.locktype,
+				l.granted,
+				(now() - a.query_start)::text AS age,
+				a.query
+			FROM pg_locks l
+			JOIN pg_stat_activity a ON a.pid = l.pid
+			LEFT JOIN pg_class c ON c.oid = l.relation
+			WHERE a.query <> '<insufficient privilege>'
+				AND l.pid <> pg_backend_pid()
+			ORDER BY a.query_start;
+		`,
+    },
+    outliers: {
+        describe: "Queries taking the most cumulative execution time (needs pg_stat_statements)",
+        fields: ["total_exec_time", "prop_exec_time", "ncalls", "query"],
+        emptyMessage: "No statements recorded yet.",
+        requiresExtension: "pg_stat_statements",
+        sql: /* sql */ `
+			SELECT
+				(interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
+				to_char(
+					(total_exec_time / nullif(sum(total_exec_time) OVER (), 0)) * 100,
+					'FM990D0'
+				) || '%' AS prop_exec_time,
+				calls AS ncalls,
+				query
+			FROM pg_stat_statements s
+			JOIN pg_database d ON d.oid = s.dbid
+			WHERE d.datname = current_database()
+			ORDER BY total_exec_time DESC
+			LIMIT 25;
+		`,
+    },
+    calls: {
+        describe: "Most frequently called queries (needs pg_stat_statements)",
+        fields: ["ncalls", "total_exec_time", "prop_exec_time", "query"],
+        emptyMessage: "No statements recorded yet.",
+        requiresExtension: "pg_stat_statements",
+        sql: /* sql */ `
+			SELECT
+				calls AS ncalls,
+				(interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
+				to_char(
+					(calls / nullif(sum(calls) OVER (), 0)::float) * 100,
+					'FM990D0'
+				) || '%' AS prop_exec_time,
+				query
+			FROM pg_stat_statements s
+			JOIN pg_database d ON d.oid = s.dbid
+			WHERE d.datname = current_database()
+			ORDER BY calls DESC
+			LIMIT 25;
+		`,
+    },
+    "lfc-hit-rate": {
+        describe: "Local File Cache hit rate (needs neon extension)",
+        fields: ["name", "ratio"],
+        emptyMessage: "No LFC stats available.",
+        requiresExtension: "neon",
+        // Read the hit/miss counters from neon_get_lfc_stats() rather than the
+        // neon_lfc_stats / neon_stat_file_cache views: those views are owned by
+        // cloud_admin and are not always readable by end-user roles, whereas the
+        // function is EXECUTE-able by the default role.
+        sql: /* sql */ `
+			WITH lfc AS (
+				SELECT lfc_key AS k, lfc_value AS v
+				FROM neon_get_lfc_stats() t(lfc_key text, lfc_value bigint)
+			)
+			SELECT
+				'lfc hit rate' AS name,
+				max(v) FILTER (WHERE k = 'file_cache_hits')::float
+					/ nullif(
+						max(v) FILTER (WHERE k = 'file_cache_hits')
+						+ max(v) FILTER (WHERE k = 'file_cache_misses'),
+						0
+					) AS ratio
+			FROM lfc;
+		`,
+    },
+    "working-set": {
+        describe: "Estimated working set vs LFC size (needs neon extension)",
+        fields: ["window", "working_set", "lfc_size", "exceeds_lfc"],
+        emptyMessage: "No working-set estimate available.",
+        requiresExtension: "neon",
+        sql: /* sql */ `
+			SELECT
+				w.window,
+				pg_size_pretty(w.working_set_bytes) AS working_set,
+				pg_size_pretty(pg_size_bytes(current_setting('neon.file_cache_size_limit'))) AS lfc_size,
+				CASE
+					WHEN w.working_set_bytes
+						> pg_size_bytes(current_setting('neon.file_cache_size_limit'))
+					THEN 'yes' ELSE 'no'
+				END AS exceeds_lfc
+			FROM (
+				SELECT
+					x AS window,
+					approximate_working_set_size_seconds(
+						extract('epoch' from x::interval)::int
+					)::bigint * 8192 AS working_set_bytes
+				FROM (VALUES ('1m'), ('5m'), ('15m'), ('1h')) AS t(x)
+			) w
+			ORDER BY working_set_bytes;
+		`,
+    },
+    "vacuum-stats": {
+        describe: "Autovacuum status per table: last (auto)vacuum, dead tuples, threshold",
+        fields: [
+            "schema",
+            "table",
+            "last_vacuum",
+            "last_autovacuum",
+            "rowcount",
+            "dead_rowcount",
+            "expect_autovacuum",
+        ],
+        emptyMessage: "No user tables found.",
+        sql: /* sql */ `
+			SELECT
+				n.nspname AS schema,
+				c.relname AS "table",
+				to_char(psut.last_vacuum, 'YYYY-MM-DD HH24:MI') AS last_vacuum,
+				to_char(psut.last_autovacuum, 'YYYY-MM-DD HH24:MI') AS last_autovacuum,
+				c.reltuples::bigint AS rowcount,
+				psut.n_dead_tup AS dead_rowcount,
+				CASE
+					WHEN current_setting('autovacuum_vacuum_threshold')::bigint
+						+ current_setting('autovacuum_vacuum_scale_factor')::numeric
+							* c.reltuples
+						< psut.n_dead_tup
+					THEN 'yes'
+					ELSE 'no'
+				END AS expect_autovacuum
+			FROM pg_stat_user_tables psut
+			JOIN pg_class c ON psut.relid = c.oid
+			JOIN pg_namespace n ON c.relnamespace = n.oid
+			ORDER BY psut.n_dead_tup DESC;
+		`,
+    },
+    bloat: {
+        describe: "Estimated table/index bloat (statistical estimate, no extension needed)",
+        fields: ["type", "schema", "object_name", "bloat", "waste"],
+        emptyMessage: "No bloat estimate available.",
+        sql: /* sql */ `
+			WITH constants AS (
+				SELECT current_setting('block_size')::numeric AS bs, 23 AS hdr, 8 AS ma
+			),
+			bloat_info AS (
+				SELECT
+					ma, bs, schemaname, tablename,
+					(datawidth + (hdr + ma - (CASE WHEN hdr % ma = 0 THEN ma ELSE hdr % ma END)))::numeric AS datahdr,
+					(maxfracsum * (nullhdr + ma - (CASE WHEN nullhdr % ma = 0 THEN ma ELSE nullhdr % ma END))) AS nullhdr2
+				FROM (
+					SELECT
+						schemaname, tablename, hdr, ma, bs,
+						SUM((1 - null_frac) * avg_width) AS datawidth,
+						MAX(null_frac) AS maxfracsum,
+						hdr + (
+							SELECT 1 + count(*) / 8
+							FROM pg_stats s2
+							WHERE null_frac <> 0
+								AND s2.schemaname = s.schemaname
+								AND s2.tablename = s.tablename
+						) AS nullhdr
+					FROM pg_stats s, constants
+					GROUP BY 1, 2, 3, 4, 5
+				) AS foo
+			),
+			table_bloat AS (
+				SELECT
+					schemaname, tablename, cc.relpages, bs,
+					CEIL((cc.reltuples * ((datahdr + ma
+						- (CASE WHEN datahdr % ma = 0 THEN ma ELSE datahdr % ma END))
+						+ nullhdr2 + 4)) / (bs - 20::float)) AS otta
+				FROM bloat_info
+				JOIN pg_class cc ON cc.relname = bloat_info.tablename
+				JOIN pg_namespace nn ON cc.relnamespace = nn.oid
+					AND nn.nspname = bloat_info.schemaname
+					AND nn.nspname NOT IN ('information_schema', 'pg_catalog')
+				WHERE cc.relkind = 'r'
+			)
+			SELECT
+				'table' AS type,
+				schemaname AS schema,
+				tablename AS object_name,
+				round(CASE WHEN otta = 0 THEN 0.0 ELSE relpages::numeric / otta::numeric END, 1) AS bloat,
+				pg_size_pretty(
+					(CASE WHEN relpages < otta THEN 0 ELSE (bs * (relpages - otta))::bigint END)
+				) AS waste
+			FROM table_bloat
+			ORDER BY (CASE WHEN relpages < otta THEN 0 ELSE bs * (relpages - otta) END) DESC
+			LIMIT 25;
+		`,
+    },
+    "replication-slots": {
+        describe: "Replication slots: kind, status, client, restart/confirmed-flush LSNs, and lag (pg_replication_slots + pg_stat_replication)",
+        fields: [
+            "slot_name",
+            "slot_type",
+            "slot_kind",
+            "status",
+            "client_addr",
+            "restart_lsn",
+            "confirmed_flush_lsn",
+            "replication_lag",
+        ],
+        emptyMessage: "No replication slots found.",
+        sql: /* sql */ `
+			SELECT
+				s.slot_name,
+				s.slot_type,
+				CASE
+					WHEN s.slot_type = 'physical' THEN 'physical'
+					WHEN s.slot_name LIKE 'pg_%_sync_%' THEN 'initial-sync (tablesync)'
+					WHEN s.slot_type = 'logical' THEN 'CDC (apply)'
+					ELSE 'other'
+				END AS slot_kind,
+				CASE
+					WHEN r.state IS NOT NULL THEN r.state
+					WHEN s.active THEN 'active (no walsender)'
+					ELSE 'inactive'
+				END AS status,
+				r.client_addr,
+				s.restart_lsn,
+				s.confirmed_flush_lsn,
+				pg_size_pretty(
+					pg_wal_lsn_diff(
+						CASE
+							WHEN pg_is_in_recovery() THEN pg_last_wal_receive_lsn()
+							ELSE pg_current_wal_lsn()
+						END,
+						COALESCE(s.confirmed_flush_lsn, s.restart_lsn)
+					)
+				) AS replication_lag
+			FROM pg_replication_slots s
+			LEFT JOIN pg_stat_replication r ON r.pid = s.active_pid
+			ORDER BY s.slot_name;
+		`,
+    },
+    subscriptions: {
+        describe: "Per-table logical replication progress on this subscriber (pg_subscription_rel)",
+        fields: ["subscription", "table_name", "status", "lsn"],
+        emptyMessage: "No subscriptions found on this database.",
+        sql: /* sql */ `
+			SELECT
+				sub.subname AS subscription,
+				sr.srrelid::regclass::text AS table_name,
+				CASE sr.srsubstate
+					WHEN 'i' THEN 'initialize'
+					WHEN 'd' THEN 'data being copied'
+					WHEN 'f' THEN 'finished table copy'
+					WHEN 's' THEN 'synchronized'
+					WHEN 'r' THEN 'ready'
+					ELSE sr.srsubstate::text
+				END AS status,
+				sr.srsublsn AS lsn
+			FROM pg_subscription_rel sr
+			JOIN pg_subscription sub ON sub.oid = sr.srsubid
+			ORDER BY sub.subname, table_name;
+		`,
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neonctl",
-  "version": "2.35.1",
+  "version": "2.36.0",
   "description": "CLI tool for Neon Serverless Postgres",
   "keywords": [
     "neon",
@@ -54,7 +54,7 @@
     "@neon/sdk": "1.2.0",
     "@neon/config": "0.9.5",
     "@neon/config-runtime": "0.9.6",
-    "@neon/env": "0.11.4"
+    "@neon/env": "0.11.5"
   },
   "optionalDependencies": {
     "esbuild": "0.28.1"