@neon/tools 2.11.0 → 2.13.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.
- package/README.md +150 -7
- package/dist/descriptions.gen.d.ts +10 -0
- package/dist/descriptions.gen.d.ts.map +1 -0
- package/dist/descriptions.gen.js +150 -0
- package/dist/generated/zod.gen.d.ts +33 -2
- package/dist/generated/zod.gen.d.ts.map +1 -1
- package/dist/generated/zod.gen.js +29 -11
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +14 -11
- package/dist/lib/custom/auth-config.d.ts +164 -0
- package/dist/lib/custom/auth-config.d.ts.map +1 -0
- package/dist/lib/custom/auth-config.js +177 -0
- package/dist/lib/custom/docs.d.ts +58 -0
- package/dist/lib/custom/docs.d.ts.map +1 -0
- package/dist/lib/custom/docs.js +143 -0
- package/dist/lib/custom/feedback.d.ts +15 -0
- package/dist/lib/custom/feedback.d.ts.map +1 -0
- package/dist/lib/custom/feedback.js +55 -0
- package/dist/lib/custom/fetch.d.ts +402 -0
- package/dist/lib/custom/fetch.d.ts.map +1 -0
- package/dist/lib/custom/fetch.js +198 -0
- package/dist/lib/custom/organizations.d.ts +23 -0
- package/dist/lib/custom/organizations.d.ts.map +1 -0
- package/dist/lib/custom/organizations.js +32 -0
- package/dist/lib/custom/resources.d.ts +22 -0
- package/dist/lib/custom/resources.d.ts.map +1 -0
- package/dist/lib/custom/resources.js +113 -0
- package/dist/lib/custom/sql/connection.d.ts +46 -0
- package/dist/lib/custom/sql/connection.d.ts.map +1 -0
- package/dist/lib/custom/sql/connection.js +78 -0
- package/dist/lib/custom/sql/describe-branch.d.ts +84 -0
- package/dist/lib/custom/sql/describe-branch.d.ts.map +1 -0
- package/dist/lib/custom/sql/describe-branch.js +155 -0
- package/dist/lib/custom/sql/inspect/inspect.d.ts +75 -0
- package/dist/lib/custom/sql/inspect/inspect.d.ts.map +1 -0
- package/dist/lib/custom/sql/inspect/inspect.js +135 -0
- package/dist/lib/custom/sql/inspect/queries.d.ts +63 -0
- package/dist/lib/custom/sql/inspect/queries.d.ts.map +1 -0
- package/dist/lib/custom/sql/inspect/queries.js +528 -0
- package/dist/lib/custom/sql/inspect/report.d.ts +31 -0
- package/dist/lib/custom/sql/inspect/report.d.ts.map +1 -0
- package/dist/lib/custom/sql/inspect/report.js +43 -0
- package/dist/lib/custom/sql/inspect/targets.d.ts +27 -0
- package/dist/lib/custom/sql/inspect/targets.d.ts.map +1 -0
- package/dist/lib/custom/sql/inspect/targets.js +33 -0
- package/dist/lib/custom/sql/migrations.d.ts +69 -0
- package/dist/lib/custom/sql/migrations.d.ts.map +1 -0
- package/dist/lib/custom/sql/migrations.js +144 -0
- package/dist/lib/custom/sql/plan.d.ts +27 -0
- package/dist/lib/custom/sql/plan.d.ts.map +1 -0
- package/dist/lib/custom/sql/plan.js +53 -0
- package/dist/lib/custom/sql/query-tuning.d.ts +107 -0
- package/dist/lib/custom/sql/query-tuning.d.ts.map +1 -0
- package/dist/lib/custom/sql/query-tuning.js +129 -0
- package/dist/lib/custom/sql/rows.d.ts +11 -0
- package/dist/lib/custom/sql/rows.d.ts.map +1 -0
- package/dist/lib/custom/sql/rows.js +19 -0
- package/dist/lib/custom/sql/run.d.ts +81 -0
- package/dist/lib/custom/sql/run.d.ts.map +1 -0
- package/dist/lib/custom/sql/run.js +90 -0
- package/dist/lib/custom/sql/schema.d.ts +84 -0
- package/dist/lib/custom/sql/schema.d.ts.map +1 -0
- package/dist/lib/custom/sql/schema.js +201 -0
- package/dist/lib/custom/sql/slow-queries.d.ts +43 -0
- package/dist/lib/custom/sql/slow-queries.d.ts.map +1 -0
- package/dist/lib/custom/sql/slow-queries.js +87 -0
- package/dist/lib/customize.d.ts +9 -2
- package/dist/lib/customize.d.ts.map +1 -1
- package/dist/lib/customize.js +21 -7
- package/dist/lib/ergonomic/bind.d.ts +11 -1
- package/dist/lib/ergonomic/bind.d.ts.map +1 -1
- package/dist/lib/ergonomic/bind.js +13 -3
- package/dist/lib/ergonomic/catalog.d.ts +870 -38
- package/dist/lib/ergonomic/catalog.d.ts.map +1 -1
- package/dist/lib/ergonomic/catalog.js +44 -8
- package/dist/lib/ergonomic/composed.d.ts +4 -4
- package/dist/lib/ergonomic/composed.d.ts.map +1 -1
- package/dist/lib/ergonomic/composed.js +47 -45
- package/dist/lib/ergonomic/ids.d.ts +3 -1
- package/dist/lib/ergonomic/ids.d.ts.map +1 -1
- package/dist/lib/ergonomic/ids.js +42 -2
- package/dist/lib/ergonomic/index.d.ts +1 -1
- package/dist/lib/ergonomic/index.d.ts.map +1 -1
- package/dist/lib/ergonomic/index.js +2 -2
- package/dist/lib/operation.d.ts +11 -0
- package/dist/lib/operation.d.ts.map +1 -1
- package/dist/lib/references.d.ts +10 -0
- package/dist/lib/references.d.ts.map +1 -0
- package/dist/lib/references.js +28 -0
- package/dist/operations.gen.d.ts +22 -2
- package/dist/operations.gen.d.ts.map +1 -1
- package/dist/operations.gen.js +335 -300
- package/dist/schemas.d.ts +1 -1
- package/dist/schemas.d.ts.map +1 -1
- package/dist/schemas.js +1 -1
- package/package.json +9 -6
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { bindTool, publishedId } from "../../../ergonomic/bind.js";
|
|
2
|
+
import { SQL_METADATA, branchIdField, computeIdField, projectIdField, resolveConnection, sqlClient } from "../connection.js";
|
|
3
|
+
import { sqlReadAnnotations } from "../schema.js";
|
|
4
|
+
import { INSPECT_CHECKS, INSPECT_MAX_LIMIT, INSPECT_QUERIES } from "./queries.js";
|
|
5
|
+
import { assembleInspectReport } from "./report.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. If a check needs an extension, 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"}
|