@neon/tools 2.12.0 → 2.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/README.md +152 -7
  2. package/dist/descriptions.gen.d.ts +10 -0
  3. package/dist/descriptions.gen.d.ts.map +1 -0
  4. package/dist/descriptions.gen.js +150 -0
  5. package/dist/generated/zod.gen.d.ts +6 -6
  6. package/dist/index.d.ts +7 -3
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +15 -11
  9. package/dist/lib/custom/auth-config.d.ts +164 -0
  10. package/dist/lib/custom/auth-config.d.ts.map +1 -0
  11. package/dist/lib/custom/auth-config.js +177 -0
  12. package/dist/lib/custom/docs.d.ts +58 -0
  13. package/dist/lib/custom/docs.d.ts.map +1 -0
  14. package/dist/lib/custom/docs.js +143 -0
  15. package/dist/lib/custom/feedback.d.ts +15 -0
  16. package/dist/lib/custom/feedback.d.ts.map +1 -0
  17. package/dist/lib/custom/feedback.js +55 -0
  18. package/dist/lib/custom/fetch.d.ts +402 -0
  19. package/dist/lib/custom/fetch.d.ts.map +1 -0
  20. package/dist/lib/custom/fetch.js +198 -0
  21. package/dist/lib/custom/organizations.d.ts +23 -0
  22. package/dist/lib/custom/organizations.d.ts.map +1 -0
  23. package/dist/lib/custom/organizations.js +32 -0
  24. package/dist/lib/custom/resources.d.ts +22 -0
  25. package/dist/lib/custom/resources.d.ts.map +1 -0
  26. package/dist/lib/custom/resources.js +113 -0
  27. package/dist/lib/custom/sql/connection.d.ts +46 -0
  28. package/dist/lib/custom/sql/connection.d.ts.map +1 -0
  29. package/dist/lib/custom/sql/connection.js +78 -0
  30. package/dist/lib/custom/sql/describe-branch.d.ts +84 -0
  31. package/dist/lib/custom/sql/describe-branch.d.ts.map +1 -0
  32. package/dist/lib/custom/sql/describe-branch.js +155 -0
  33. package/dist/lib/custom/sql/inspect/catalog.d.ts +22 -0
  34. package/dist/lib/custom/sql/inspect/catalog.d.ts.map +1 -0
  35. package/dist/lib/custom/sql/inspect/catalog.js +18 -0
  36. package/dist/lib/custom/sql/inspect/inspect.d.ts +75 -0
  37. package/dist/lib/custom/sql/inspect/inspect.d.ts.map +1 -0
  38. package/dist/lib/custom/sql/inspect/inspect.js +135 -0
  39. package/dist/lib/custom/sql/inspect/queries.d.ts +63 -0
  40. package/dist/lib/custom/sql/inspect/queries.d.ts.map +1 -0
  41. package/dist/lib/custom/sql/inspect/queries.js +528 -0
  42. package/dist/lib/custom/sql/inspect/report.d.ts +33 -0
  43. package/dist/lib/custom/sql/inspect/report.d.ts.map +1 -0
  44. package/dist/lib/custom/sql/inspect/report.js +45 -0
  45. package/dist/lib/custom/sql/inspect/targets.d.ts +27 -0
  46. package/dist/lib/custom/sql/inspect/targets.d.ts.map +1 -0
  47. package/dist/lib/custom/sql/inspect/targets.js +33 -0
  48. package/dist/lib/custom/sql/migrations.d.ts +69 -0
  49. package/dist/lib/custom/sql/migrations.d.ts.map +1 -0
  50. package/dist/lib/custom/sql/migrations.js +144 -0
  51. package/dist/lib/custom/sql/plan.d.ts +27 -0
  52. package/dist/lib/custom/sql/plan.d.ts.map +1 -0
  53. package/dist/lib/custom/sql/plan.js +53 -0
  54. package/dist/lib/custom/sql/query-tuning.d.ts +107 -0
  55. package/dist/lib/custom/sql/query-tuning.d.ts.map +1 -0
  56. package/dist/lib/custom/sql/query-tuning.js +129 -0
  57. package/dist/lib/custom/sql/rows.d.ts +11 -0
  58. package/dist/lib/custom/sql/rows.d.ts.map +1 -0
  59. package/dist/lib/custom/sql/rows.js +19 -0
  60. package/dist/lib/custom/sql/run.d.ts +81 -0
  61. package/dist/lib/custom/sql/run.d.ts.map +1 -0
  62. package/dist/lib/custom/sql/run.js +90 -0
  63. package/dist/lib/custom/sql/schema.d.ts +84 -0
  64. package/dist/lib/custom/sql/schema.d.ts.map +1 -0
  65. package/dist/lib/custom/sql/schema.js +201 -0
  66. package/dist/lib/custom/sql/slow-queries.d.ts +43 -0
  67. package/dist/lib/custom/sql/slow-queries.d.ts.map +1 -0
  68. package/dist/lib/custom/sql/slow-queries.js +87 -0
  69. package/dist/lib/customize.d.ts +9 -2
  70. package/dist/lib/customize.d.ts.map +1 -1
  71. package/dist/lib/customize.js +21 -7
  72. package/dist/lib/ergonomic/bind.d.ts +11 -1
  73. package/dist/lib/ergonomic/bind.d.ts.map +1 -1
  74. package/dist/lib/ergonomic/bind.js +13 -3
  75. package/dist/lib/ergonomic/catalog.d.ts +902 -87
  76. package/dist/lib/ergonomic/catalog.d.ts.map +1 -1
  77. package/dist/lib/ergonomic/catalog.js +35 -8
  78. package/dist/lib/ergonomic/composed.d.ts +4 -4
  79. package/dist/lib/ergonomic/composed.d.ts.map +1 -1
  80. package/dist/lib/ergonomic/composed.js +47 -45
  81. package/dist/lib/ergonomic/ids.d.ts +3 -1
  82. package/dist/lib/ergonomic/ids.d.ts.map +1 -1
  83. package/dist/lib/ergonomic/ids.js +41 -2
  84. package/dist/lib/ergonomic/index.d.ts +1 -1
  85. package/dist/lib/ergonomic/index.d.ts.map +1 -1
  86. package/dist/lib/ergonomic/index.js +2 -2
  87. package/dist/lib/operation.d.ts +11 -0
  88. package/dist/lib/operation.d.ts.map +1 -1
  89. package/dist/lib/references.d.ts +10 -0
  90. package/dist/lib/references.d.ts.map +1 -0
  91. package/dist/lib/references.js +28 -0
  92. package/dist/operations.gen.d.ts +2 -2
  93. package/dist/operations.gen.js +302 -302
  94. package/package.json +8 -5
@@ -0,0 +1,135 @@
1
+ import { INSPECT_CHECKS, INSPECT_MAX_LIMIT, INSPECT_QUERIES } from "./queries.js";
2
+ import { assembleInspectReport } from "./report.js";
3
+ import { bindTool, publishedId } from "../../../ergonomic/bind.js";
4
+ import { SQL_METADATA, branchIdField, computeIdField, projectIdField, resolveConnection, sqlClient } from "../connection.js";
5
+ import { sqlReadAnnotations } from "../schema.js";
6
+ import { formatInspectQueryError, selectInspectTargets } from "./targets.js";
7
+ import { NeonClientError } from "@neon/sdk";
8
+ import { NeonDbError } from "@neondatabase/serverless";
9
+ import * as z from "zod";
10
+ // src/lib/custom/sql/inspect/inspect.ts
11
+ /**
12
+ * Postgres rejected one of the package's own diagnostic queries. That is a bug
13
+ * in the catalog, not in the caller's input, so hosts should report it like any
14
+ * other server fault. `cause` is the original `NeonDbError`.
15
+ */
16
+ var InspectDiagnosticError = class extends Error {
17
+ check;
18
+ constructor(message, check, cause) {
19
+ super(message, { cause });
20
+ this.name = "InspectDiagnosticError";
21
+ this.check = check;
22
+ }
23
+ };
24
+ const inspectDatabaseInputSchema = z.strictObject({
25
+ check: z.enum(INSPECT_CHECKS).describe("The diagnostic to run."),
26
+ project_id: projectIdField,
27
+ branch_id: branchIdField,
28
+ database_name: z.string().min(1, "database_name cannot be empty. Omit it to cover every database.").optional().describe("Database to inspect, or to connect through for a compute-wide check. Omit for every database; one failure fails the run."),
29
+ compute_id: computeIdField,
30
+ limit: z.number().int().min(1).max(INSPECT_MAX_LIMIT).default(50).describe("Rows to return. Raise it only when truncated is true.")
31
+ });
32
+ /**
33
+ * The proxy refuses an IP allowlist or blocked-network connection with an HTTP
34
+ * 400 whose `severity` is empty; Postgres sets it on every error it raises. A
35
+ * quota refusal is another 4xx, which `@neondatabase/serverless` reports only as
36
+ * this message. A connection the proxy refused never ran the query.
37
+ */
38
+ const isRefusedConnection = (error) => error.severity === "" || /^Server error \(HTTP status 4\d\d\)/.test(error.message);
39
+ const runDiagnostic = async (check, run) => {
40
+ try {
41
+ return await run();
42
+ } catch (error) {
43
+ if (error instanceof NeonDbError && !isRefusedConnection(error)) throw new InspectDiagnosticError(`The "${check}" diagnostic failed against Postgres: ${error.message}`, check, error);
44
+ throw error;
45
+ }
46
+ };
47
+ const runInspectOnDatabase = async (check, uri, databaseName, signal) => {
48
+ const query = INSPECT_QUERIES[check];
49
+ const sql = sqlClient(uri, signal);
50
+ if (query.requiresExtension) {
51
+ const extension = query.requiresExtension;
52
+ if ((await runDiagnostic(check, () => sql.query("SELECT 1 FROM pg_extension WHERE extname = $1", [extension]))).length === 0) throw new NeonClientError(`The "${check}" check needs the "${extension}" extension, which is not installed on database "${databaseName}". Installing it writes to the user's database, so ask the user first, then run \`CREATE EXTENSION IF NOT EXISTS ${extension};\`.`);
53
+ }
54
+ const [rows] = await runDiagnostic(check, () => sql.transaction([sql.query(query.sql)], { readOnly: true }));
55
+ return rows;
56
+ };
57
+ /**
58
+ * Puts which database failed into the message of the original error, so its
59
+ * class and fields (`status`, `code`, `check`, …) reach the caller unchanged.
60
+ */
61
+ const rethrowInspectError = (error, wrapped) => {
62
+ if (wrapped === void 0) throw error;
63
+ if (error instanceof Error) {
64
+ error.message = wrapped;
65
+ throw error;
66
+ }
67
+ throw new Error(wrapped, { cause: error });
68
+ };
69
+ const inspectDatabaseTool = (options) => bindTool(options, {
70
+ operationId: "database.inspect",
71
+ id: publishedId("database.inspect"),
72
+ title: "Inspect Database",
73
+ description: "Runs one read-only neon inspect db check; some are compute-wide. outliers ranks queries by total time and calls by count, both via pg_stat_statements; lfc-hit-rate and working-set need the neon extension. If one is missing, the error gives the CREATE EXTENSION; ask before running it. Other SQL: {{sql.run}}; one plan: {{sql.explain}}; new indexes: {{queryTuning.prepare}}.",
74
+ inputSchema: inspectDatabaseInputSchema,
75
+ annotations: sqlReadAnnotations,
76
+ requiresApproval: false,
77
+ metadata: SQL_METADATA
78
+ }, async (neonClient, input, signal, context) => {
79
+ const { check, database_name: databaseName, limit } = input;
80
+ const query = INSPECT_QUERIES[check];
81
+ const projectId = input.project_id;
82
+ const branchId = input.branch_id ?? (await neonClient.branches.getDefault({ projectId }, { signal })).id;
83
+ let branchDatabaseCount = 1;
84
+ let selection;
85
+ if (databaseName !== void 0) selection = selectInspectTargets({
86
+ databaseName,
87
+ branchDatabases: [],
88
+ scope: query.scope
89
+ });
90
+ else {
91
+ const branchDatabases = (await neonClient.postgres.databases.list({
92
+ projectId,
93
+ branchId
94
+ }, { signal })).map((database) => database.name);
95
+ if (branchDatabases.length === 0) throw new NeonClientError("No databases found in your project branch");
96
+ branchDatabaseCount = branchDatabases.length;
97
+ selection = selectInspectTargets({
98
+ branchDatabases,
99
+ scope: query.scope
100
+ });
101
+ }
102
+ const batches = [];
103
+ for (const name of selection.databases) try {
104
+ const connection = await resolveConnection(neonClient, {
105
+ project_id: projectId,
106
+ branch_id: branchId,
107
+ database_name: name,
108
+ compute_id: input.compute_id
109
+ }, context, signal);
110
+ batches.push({
111
+ database: name,
112
+ rows: await runInspectOnDatabase(check, connection.uri, name, signal)
113
+ });
114
+ } catch (error) {
115
+ rethrowInspectError(error, formatInspectQueryError({
116
+ reason: error instanceof Error ? error.message : String(error),
117
+ database: name,
118
+ databaseName,
119
+ offerDatabaseNameHint: branchDatabaseCount > 1,
120
+ scope: query.scope,
121
+ requiresExtension: query.requiresExtension
122
+ }));
123
+ }
124
+ return assembleInspectReport({
125
+ check,
126
+ query,
127
+ projectId,
128
+ branchId,
129
+ batches,
130
+ includeDatabaseColumn: selection.includeDatabaseColumn,
131
+ includeDatabaseName: databaseName !== void 0,
132
+ limit
133
+ });
134
+ });
135
+ export { InspectDiagnosticError, inspectDatabaseInputSchema, inspectDatabaseTool };
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Diagnostic SQL behind `database.inspect`. Each entry is a read-only query
3
+ * against Postgres' own statistics and catalog views, plus the output columns
4
+ * in display order.
5
+ *
6
+ * The SQL is a verbatim copy of `packages/cli/src/utils/inspect_queries.ts`,
7
+ * which powers `neon inspect db <check>`. Port fixes to both files so the two
8
+ * catalogs do not diverge.
9
+ *
10
+ * The `describe` strings deliberately differ from the CLI's for `unused-indexes`,
11
+ * `outliers`, `calls`, and `bloat`: they name the thresholds the SQL applies
12
+ * (`< 50` scans, `LIMIT 25`). `sqlLimit` carries the same fact in
13
+ * machine-readable form.
14
+ */
15
+ import type { InspectQueryScope } from "./targets.js";
16
+ /**
17
+ * Every available check, in the order they are offered to the model. Declared as
18
+ * a tuple so it can back a Zod enum directly, which keeps the tool's input
19
+ * schema and this catalog from drifting apart.
20
+ */
21
+ export declare const INSPECT_CHECKS: readonly ["table-sizes", "index-sizes", "unused-indexes", "seq-scans", "long-running-queries", "stalled-queries", "locks", "outliers", "calls", "lfc-hit-rate", "working-set", "vacuum-stats", "bloat", "replication-slots", "subscriptions"];
22
+ export type InspectCheck = (typeof INSPECT_CHECKS)[number];
23
+ export type InspectQuery = {
24
+ /** One-line description of what the check reports. */
25
+ describe: string;
26
+ /** The read-only SQL to execute. */
27
+ sql: string;
28
+ /** Output columns, in display order. */
29
+ fields: readonly string[];
30
+ /** Explanation to return instead of an empty row set. */
31
+ emptyMessage: string;
32
+ emptyMessageAll?: string;
33
+ /**
34
+ * Row ceiling the SQL itself imposes, for the checks that carry a `LIMIT`.
35
+ * Without it a capped result is indistinguishable from a complete one, and the
36
+ * response would report `truncated: false` on a row set Postgres already cut.
37
+ */
38
+ sqlLimit?: number;
39
+ /**
40
+ * Postgres extension the query needs (e.g. `pg_stat_statements`). When set,
41
+ * the handler verifies the extension is installed before running the query.
42
+ */
43
+ requiresExtension?: string;
44
+ /**
45
+ * Database catalogs differ, while compute-wide views return the same rows
46
+ * from every database.
47
+ */
48
+ scope: InspectQueryScope;
49
+ };
50
+ /**
51
+ * Typed as an exact `Record` so adding a check to `INSPECT_CHECKS` without
52
+ * writing its query is a compile error.
53
+ */
54
+ export declare const INSPECT_QUERIES: Record<InspectCheck, InspectQuery>;
55
+ /**
56
+ * Rows returned per call unless the caller raises it. Diagnostics like
57
+ * `table-sizes` are unbounded in SQL, and a few thousand rows would crowd out the
58
+ * model's context, so the handler caps the response and reports the full count.
59
+ */
60
+ export declare const INSPECT_DEFAULT_LIMIT = 50;
61
+ /** Ceiling on `limit`, so a diagnostic can never return an unbounded response. */
62
+ export declare const INSPECT_MAX_LIMIT = 1000;
63
+ //# sourceMappingURL=queries.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../../../src/lib/custom/sql/inspect/queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,cAAc,+OAgBjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,MAAM,MAAM,YAAY,GAAG;IAC1B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,KAAK,EAAE,iBAAiB,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,YAAY,EAAE,YAAY,CAyd9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,OAAO,CAAC"}