neon 3.0.0 → 3.1.0

package/dist/utils/inspect_queries.js

@@ -1,19 +1,14 @@
-/**
- * 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 */ `
+//#region src/utils/inspect_queries.ts
+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: `
 			SELECT
 				n.nspname AS schema,
 				c.relname AS name,
@@ -24,13 +19,17 @@ export const INSPECT_QUERIES = {
 				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 */ `
+		`
+	},
+	"index-sizes": {
+		describe: "Size of each index, largest first (pg_relation_size)",
+		fields: [
+			"schema",
+			"name",
+			"size"
+		],
+		emptyMessage: "No indexes found.",
+		sql: `
 			SELECT
 				n.nspname AS schema,
 				c.relname AS name,
@@ -41,13 +40,18 @@ export const INSPECT_QUERIES = {
 				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 */ `
+		`
+	},
+	"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: `
 			SELECT
 				s.schemaname || '.' || s.relname AS "table",
 				s.indexrelname AS index,
@@ -59,26 +63,35 @@ export const INSPECT_QUERIES = {
 				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 */ `
+		`
+	},
+	"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: `
 			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 */ `
+		`
+	},
+	"long-running-queries": {
+		describe: "Queries running longer than 5 minutes (pg_stat_activity)",
+		fields: [
+			"pid",
+			"duration",
+			"state",
+			"query"
+		],
+		emptyMessage: "No long-running queries.",
+		sql: `
 			SELECT
 				pid,
 				(now() - query_start)::text AS duration,
@@ -89,21 +102,21 @@ export const INSPECT_QUERIES = {
 				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 */ `
+		`
+	},
+	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: `
 			SELECT
 				a.pid,
 				c.relname,
@@ -118,14 +131,19 @@ export const INSPECT_QUERIES = {
 			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 */ `
+		`
+	},
+	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: `
 			SELECT
 				(interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
 				to_char(
@@ -139,14 +157,19 @@ export const INSPECT_QUERIES = {
 			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 */ `
+		`
+	},
+	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: `
 			SELECT
 				calls AS ncalls,
 				(interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
@@ -160,18 +183,14 @@ export const INSPECT_QUERIES = {
 			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 */ `
+		`
+	},
+	"lfc-hit-rate": {
+		describe: "Local File Cache hit rate (needs neon extension)",
+		fields: ["name", "ratio"],
+		emptyMessage: "No LFC stats available.",
+		requiresExtension: "neon",
+		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)
@@ -185,14 +204,19 @@ export const INSPECT_QUERIES = {
 						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 */ `
+		`
+	},
+	"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: `
 			SELECT
 				w.window,
 				pg_size_pretty(w.working_set_bytes) AS working_set,
@@ -211,21 +235,21 @@ export const INSPECT_QUERIES = {
 				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 */ `
+		`
+	},
+	"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: `
 			SELECT
 				n.nspname AS schema,
 				c.relname AS "table",
@@ -245,13 +269,19 @@ export const INSPECT_QUERIES = {
 			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 */ `
+		`
+	},
+	bloat: {
+		describe: "Estimated table/index bloat (statistical estimate, no extension needed)",
+		fields: [
+			"type",
+			"schema",
+			"object_name",
+			"bloat",
+			"waste"
+		],
+		emptyMessage: "No bloat estimate available.",
+		sql: `
 			WITH constants AS (
 				SELECT current_setting('block_size')::numeric AS bs, 23 AS hdr, 8 AS ma
 			),
@@ -300,22 +330,22 @@ export const INSPECT_QUERIES = {
 			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 */ `
+		`
+	},
+	"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: `
 			SELECT
 				s.slot_name,
 				s.slot_type,
@@ -345,13 +375,18 @@ export const INSPECT_QUERIES = {
 			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 */ `
+		`
+	},
+	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: `
 			SELECT
 				sub.subname AS subscription,
 				sr.srrelid::regclass::text AS table_name,
@@ -367,6 +402,8 @@ export const INSPECT_QUERIES = {
 			FROM pg_subscription_rel sr
 			JOIN pg_subscription sub ON sub.oid = sr.srsubid
 			ORDER BY sub.subname, table_name;
-		`,
-    },
+		`
+	}
 };
+//#endregion
+export { INSPECT_QUERIES };

package/dist/utils/middlewares.js

@@ -1,49 +1,42 @@
 import { recordCredentialInputs } from "../_shared/auth_selection.js";
+//#region src/utils/middlewares.ts
 /**
- * Resolves `--api-key` from `NEON_API_KEY` when the flag is absent, leaving it an
- * empty string when neither is set.
- *
- * This cannot be expressed as the option's yargs `default`, because yargs prints
- * defaults in help output and would print the key itself.
- *
- * This is also the one place that reads the credential environment, and it records what it saw
- * before folding anything together. Folding destroys the distinction the precedence rules turn
- * on — `--api-key` outranks `--profile` and an exported `NEON_API_KEY` does not, but once both
- * live in `args.apiKey` they are indistinguishable. The snapshot lives outside `args`
- * deliberately: a hidden yargs option would be a second, undocumented way to pass a
- * credential, and commands that call `.strict()` reject arguments the middleware invents.
- */
-export const resolveApiKeyFromEnv = (args) => {
-    const fromFlag = typeof args.apiKey === "string" ? args.apiKey : "";
-    const fromEnv = process.env.NEON_API_KEY ?? "";
-    recordCredentialInputs({
-        apiKeyFlag: fromFlag,
-        apiKeyEnv: fromEnv,
-        profileEnv: process.env.NEON_PROFILE ?? "",
-    });
-    if (fromFlag !== "") {
-        return;
-    }
-    args.apiKey = fromEnv;
-    args["api-key"] = fromEnv;
+* Resolves `--api-key` from `NEON_API_KEY` when the flag is absent, leaving it an
+* empty string when neither is set.
+*
+* This cannot be expressed as the option's yargs `default`, because yargs prints
+* defaults in help output and would print the key itself.
+*
+* This is also the one place that reads the credential environment, and it records what it saw
+* before folding anything together. Folding destroys the distinction the precedence rules turn
+* on — `--api-key` outranks `--profile` and an exported `NEON_API_KEY` does not, but once both
+* live in `args.apiKey` they are indistinguishable. The snapshot lives outside `args`
+* deliberately: a hidden yargs option would be a second, undocumented way to pass a
+* credential, and commands that call `.strict()` reject arguments the middleware invents.
+*/
+const resolveApiKeyFromEnv = (args) => {
+	const fromFlag = typeof args.apiKey === "string" ? args.apiKey : "";
+	const fromEnv = process.env.NEON_API_KEY ?? "";
+	recordCredentialInputs({
+		apiKeyFlag: fromFlag,
+		apiKeyEnv: fromEnv,
+		profileEnv: process.env.NEON_PROFILE ?? ""
+	});
+	if (fromFlag !== "") return;
+	args.apiKey = fromEnv;
+	args["api-key"] = fromEnv;
 };
 /**
- * This middleware is needed to fill in the args for nested objects,
- * so that required arguments would work
- * otherwise yargs just throws an error
- */
-export const fillInArgs = (args, currentArgs = args, acc = []) => {
-    Object.entries(currentArgs).forEach(([k, v]) => {
-        if (k === "_" || k === "--") {
-            return;
-        }
-        // check if the value is an Object
-        if (typeof v === "object" && v !== null) {
-            fillInArgs(args, v, [...acc, k]);
-        }
-        else if (acc.length > 0) {
-            // if it's not an object, and we have a path, fill it in
-            args[acc.join(".") + "." + k] = v;
-        }
-    });
+* This middleware is needed to fill in the args for nested objects,
+* so that required arguments would work
+* otherwise yargs just throws an error
+*/
+const fillInArgs = (args, currentArgs = args, acc = []) => {
+	Object.entries(currentArgs).forEach(([k, v]) => {
+		if (k === "_" || k === "--") return;
+		if (typeof v === "object" && v !== null) fillInArgs(args, v, [...acc, k]);
+		else if (acc.length > 0) args[acc.join(".") + "." + k] = v;
+	});
 };
+//#endregion
+export { fillInArgs, resolveApiKeyFromEnv };