neon 4.0.0 → 4.1.0

package/README.md

@@ -62,7 +62,7 @@ Alternatively, you can authenticate a connection with a Neon API key using the `
 neon projects list --api-key <neon_api_key>
 ```
 
-For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
+For information about obtaining an Neon API key, see [Authentication](https://neon.com/docs/reference/api/get-started), in the _Neon API Reference_.
 
 ## Project and branch creation
 
@@ -766,6 +766,15 @@ neon snapshots schedule set --branch main --schedule '[{"frequency":"weekly","da
 
 All sub-commands honor the [global options](#global-options), including `--output json|yaml|table`.
 
+## Database diagnostics (`inspect`)
+
+`neon inspect db stalled-queries` takes a read-only snapshot of active queries that have run for more than 30 seconds and groups parallel workers with their leader. Table output shows duration, wait event, blocking pids, role, query group, and query. `--output json` adds timestamps, query IDs, pids, database, and the rest of the row. A blocking pid can belong to an idle-in-transaction backend this command does not list; `neon inspect db locks` shows lock holders.
+
+```bash
+neon inspect db stalled-queries
+neon inspect db stalled-queries --output json
+```
+
 ## Logs (`logs`)
 
 `neon logs` reads the log records the services on a branch emit — Neon Functions, object storage, and Postgres computes. **Logs require Neon Platform Beta and are currently available only for projects in `aws-us-east-2`.**
@@ -1078,6 +1087,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                                   | Manage roles                       |
 | [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                                       | Manage operations                  |
 | logs                                                                       | `query`, `fields`, `field-values`                                                                            | Query branch logs (Beta)           |
+| inspect                                                                    | `db stalled-queries`                                                                                         | Inspect Postgres diagnostics       |
 | snapshots                                                                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `finalize`, `schedule get`, `schedule set`           | Manage snapshots                   |
 | [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                                              | Get connection string              |
 | [psql](https://neon.com/docs/reference/cli-psql)                           |                                                                                                              | Connect to a database via psql     |
@@ -1141,7 +1151,7 @@ Global options are supported with any Neon CLI command.
 
 - <a id="api-key"></a>`--api-key`
 
-  Specifies your Neon API key. You can authenticate using a Neon API key when running a Neon CLI command instead of using `neon auth`. For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
+  Specifies your Neon API key. You can authenticate using a Neon API key when running a Neon CLI command instead of using `neon auth`. For information about obtaining an Neon API key, see [Authentication](https://neon.com/docs/reference/api/get-started), in the _Neon API Reference_.
 
   ```bash
   neon <command> --api-key <neon_api_key>

package/dist/utils/inspect_queries.js

@@ -111,6 +111,57 @@ const INSPECT_QUERIES = {
 			ORDER BY now() - query_start DESC;
 		`
 	},
+	"stalled-queries": {
+		describe: "Active queries running longer than 30 seconds with parallel workers, waits, and blockers (compute-wide)",
+		scope: "compute",
+		fields: [
+			"duration",
+			"wait_event",
+			"blocking_pids",
+			"role",
+			"query_group",
+			"query"
+		],
+		emptyMessage: "No active queries running longer than 30 seconds.",
+		sql: `
+			WITH activity AS MATERIALIZED (
+				SELECT *
+				FROM pg_stat_activity
+				WHERE state = 'active'
+					AND backend_type IN ('client backend', 'parallel worker')
+					AND pid <> pg_backend_pid()
+			),
+			stalled_groups AS (
+				SELECT DISTINCT COALESCE(leader_pid, pid) AS query_group
+				FROM activity
+				WHERE query_start <= statement_timestamp() - interval '30 seconds'
+			)
+			SELECT
+				statement_timestamp() AS observed_at,
+				a.query_start,
+				g.query_group,
+				a.pid,
+				a.leader_pid,
+				CASE
+					WHEN a.leader_pid IS NULL THEN 'leader'
+					ELSE 'worker'
+				END AS role,
+				a.backend_type,
+				a.datname AS database,
+				a.application_name,
+				a.query_id::text AS query_id,
+				a.state,
+				a.wait_event_type,
+				a.wait_event,
+				array_to_string(pg_blocking_pids(a.pid), ',') AS blocking_pids,
+				(statement_timestamp() - a.query_start)::text AS duration,
+				a.query
+			FROM activity a
+			JOIN stalled_groups g
+				ON g.query_group = COALESCE(a.leader_pid, a.pid)
+			ORDER BY g.query_group, a.leader_pid NULLS FIRST, a.pid;
+		`
+	},
 	locks: {
 		describe: "Locks held with the acquiring query and its age (pg_locks + pg_stat_activity)",
 		scope: "database",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -63,9 +63,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
+    "@neon/sdk": "2.2.0",
     "@neon/config-runtime": "1.0.2",
-    "@neon/config": "1.0.2",
-    "@neon/sdk": "2.2.0"
+    "@neon/config": "1.0.2"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",