@neon/tools 2.12.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 +3 -3
- 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 +854 -39
- package/dist/lib/ergonomic/catalog.d.ts.map +1 -1
- package/dist/lib/ergonomic/catalog.js +35 -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 +41 -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 +2 -2
- package/dist/operations.gen.js +301 -301
- package/package.json +8 -5
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import { bindTool, publishedId } from "../ergonomic/bind.js";
|
|
2
|
+
import { matchesNameOrId } from "./organizations.js";
|
|
3
|
+
import { NeonApiError } from "@neon/sdk";
|
|
4
|
+
import * as z from "zod";
|
|
5
|
+
import { listSharedProjects } from "@neon/sdk/raw";
|
|
6
|
+
// src/lib/custom/resources.ts
|
|
7
|
+
const DEFAULT_API_BASE_URL = "https://console.neon.tech/api/v2";
|
|
8
|
+
const PROJECTS_PER_ORGANIZATION = 400;
|
|
9
|
+
const searchResourcesInputSchema = z.strictObject({ query: z.string().min(3).describe("Part of a name or id, or a compute endpoint host from a connection string.") });
|
|
10
|
+
const consoleBaseUrl = (apiBaseUrl) => apiBaseUrl.replace(/\/api\/v2\/?$/, "");
|
|
11
|
+
/**
|
|
12
|
+
* 403 and 404 mean the credential may not read that list. Any other API error,
|
|
13
|
+
* such as a 5xx or an exhausted 429, is a failure the caller must see.
|
|
14
|
+
*/
|
|
15
|
+
const isAccessRefusal = (error) => error instanceof NeonApiError && (error.status === 403 || error.status === 404);
|
|
16
|
+
/** A resource the API refuses to list is left out of the results; anything else fails the search. */
|
|
17
|
+
const skipIfRefused = async (read) => {
|
|
18
|
+
try {
|
|
19
|
+
return await read();
|
|
20
|
+
} catch (error) {
|
|
21
|
+
if (isAccessRefusal(error)) return [];
|
|
22
|
+
throw error;
|
|
23
|
+
}
|
|
24
|
+
};
|
|
25
|
+
const searchResources = async (neon, query, consoleUrl, signal) => {
|
|
26
|
+
const link = (path) => new URL(path, consoleUrl).toString();
|
|
27
|
+
const projectPath = (projectId) => `/app/projects/${encodeURIComponent(projectId)}`;
|
|
28
|
+
const branchPath = (projectId, branchId) => `${projectPath(projectId)}/branches/${encodeURIComponent(branchId)}`;
|
|
29
|
+
const hostQuery = query.replace("-pooler.", ".");
|
|
30
|
+
const searchProject = async (projectId) => {
|
|
31
|
+
const [branches, endpoints, snapshots] = await Promise.all([
|
|
32
|
+
skipIfRefused(async () => (await neon.branches.list({ projectId }, { signal }).page()).items.filter((branch) => matchesNameOrId(branch, query))),
|
|
33
|
+
skipIfRefused(async () => (await neon.postgres.endpoints.list({ projectId }, { signal })).filter((endpoint) => endpoint.id.toLowerCase().includes(query) || endpoint.host.toLowerCase().includes(hostQuery))),
|
|
34
|
+
skipIfRefused(async () => (await neon.snapshots.list({ projectId }, { signal })).filter((snapshot) => matchesNameOrId(snapshot, query)))
|
|
35
|
+
]);
|
|
36
|
+
return [
|
|
37
|
+
...branches.map((branch) => ({
|
|
38
|
+
id: `branch:${projectId}/${branch.id}`,
|
|
39
|
+
title: branch.name,
|
|
40
|
+
url: link(branchPath(projectId, branch.id))
|
|
41
|
+
})),
|
|
42
|
+
...endpoints.map((endpoint) => ({
|
|
43
|
+
id: `endpoint:${projectId}/${endpoint.id}`,
|
|
44
|
+
title: `${endpoint.id} (${endpoint.type})`,
|
|
45
|
+
url: link(branchPath(projectId, endpoint.branch_id))
|
|
46
|
+
})),
|
|
47
|
+
...snapshots.map((snapshot) => ({
|
|
48
|
+
id: `snapshot:${projectId}/${snapshot.id}`,
|
|
49
|
+
title: snapshot.name,
|
|
50
|
+
url: link(projectPath(projectId))
|
|
51
|
+
}))
|
|
52
|
+
];
|
|
53
|
+
};
|
|
54
|
+
const searchProjects = async (projects) => {
|
|
55
|
+
const matchingProjects = projects.filter((project) => matchesNameOrId(project, query)).map((project) => ({
|
|
56
|
+
id: `project:${project.id}`,
|
|
57
|
+
title: project.name,
|
|
58
|
+
url: link(projectPath(project.id))
|
|
59
|
+
}));
|
|
60
|
+
const children = await Promise.all(projects.map((project) => searchProject(project.id)));
|
|
61
|
+
return [...matchingProjects, ...children.flat()];
|
|
62
|
+
};
|
|
63
|
+
const results = [];
|
|
64
|
+
for (const org of await neon.user.organizations({ signal })) {
|
|
65
|
+
if (matchesNameOrId(org, query)) results.push({
|
|
66
|
+
id: `org:${org.id}`,
|
|
67
|
+
title: org.name,
|
|
68
|
+
url: link(`/app/${encodeURIComponent(org.id)}/projects`)
|
|
69
|
+
});
|
|
70
|
+
results.push(...await skipIfRefused(async () => {
|
|
71
|
+
const page = await neon.projects.list({
|
|
72
|
+
org_id: org.id,
|
|
73
|
+
limit: PROJECTS_PER_ORGANIZATION
|
|
74
|
+
}, { signal }).page();
|
|
75
|
+
return searchProjects(page.items);
|
|
76
|
+
}));
|
|
77
|
+
}
|
|
78
|
+
results.push(...await skipIfRefused(async () => {
|
|
79
|
+
const shared = await listSharedProjects({
|
|
80
|
+
client: neon.client,
|
|
81
|
+
query: { limit: PROJECTS_PER_ORGANIZATION },
|
|
82
|
+
throwOnError: true,
|
|
83
|
+
signal
|
|
84
|
+
});
|
|
85
|
+
return searchProjects(shared.projects);
|
|
86
|
+
}));
|
|
87
|
+
return { results };
|
|
88
|
+
};
|
|
89
|
+
const searchResourcesTool = (options) => {
|
|
90
|
+
const consoleUrl = consoleBaseUrl(options.baseUrl ?? "https://console.neon.tech/api/v2");
|
|
91
|
+
return bindTool(options, {
|
|
92
|
+
operationId: "resources.search",
|
|
93
|
+
id: publishedId("resources.search"),
|
|
94
|
+
title: "Search Neon resources",
|
|
95
|
+
description: "Finds organizations, projects (including shared ones), branches, computes, and snapshots whose name or id contains query, with ids for {{resources.fetch}}. To list projects, use {{projects.list}}; for docs, {{docs.search}}.",
|
|
96
|
+
inputSchema: searchResourcesInputSchema,
|
|
97
|
+
annotations: {
|
|
98
|
+
readOnlyHint: true,
|
|
99
|
+
destructiveHint: false,
|
|
100
|
+
idempotentHint: true,
|
|
101
|
+
openWorldHint: false
|
|
102
|
+
},
|
|
103
|
+
requiresApproval: false,
|
|
104
|
+
metadata: {
|
|
105
|
+
method: "GET",
|
|
106
|
+
path: "/projects",
|
|
107
|
+
stability: "stable",
|
|
108
|
+
deprecated: false,
|
|
109
|
+
tags: ["Project"]
|
|
110
|
+
}
|
|
111
|
+
}, (neon, input, signal) => searchResources(neon, input.query.toLowerCase(), consoleUrl, signal));
|
|
112
|
+
};
|
|
113
|
+
export { DEFAULT_API_BASE_URL, consoleBaseUrl, isAccessRefusal, searchResourcesInputSchema, searchResourcesTool };
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { type NeonClient } from "@neon/sdk";
|
|
2
|
+
import * as z from "zod";
|
|
3
|
+
import type { NeonToolExecutionContext, NeonToolMetadata } from "../../operation.js";
|
|
4
|
+
export declare const NEON_DEFAULT_DATABASE_NAME = "neondb";
|
|
5
|
+
export declare const SQL_METADATA: NeonToolMetadata;
|
|
6
|
+
export declare const DATABASE_NAME_DESCRIPTION = "Database name. Omit for neondb, else the first database.";
|
|
7
|
+
export declare const projectIdField: z.ZodString;
|
|
8
|
+
export declare const branchIdField: z.ZodOptional<z.ZodString>;
|
|
9
|
+
export declare const databaseNameField: z.ZodOptional<z.ZodString>;
|
|
10
|
+
export declare const roleNameField: z.ZodOptional<z.ZodString>;
|
|
11
|
+
export declare const COMPUTE_ID_DESCRIPTION = "Compute endpoint id (ep-...). Omit for the read-write compute.";
|
|
12
|
+
export declare const computeIdField: z.ZodOptional<z.ZodString>;
|
|
13
|
+
export interface ConnectionTarget {
|
|
14
|
+
project_id: string;
|
|
15
|
+
branch_id?: string;
|
|
16
|
+
database_name?: string;
|
|
17
|
+
role_name?: string;
|
|
18
|
+
compute_id?: string;
|
|
19
|
+
/** Defaults to `true`, as in `@neon/sdk`. */
|
|
20
|
+
pooled?: boolean;
|
|
21
|
+
}
|
|
22
|
+
export interface ResolvedConnection {
|
|
23
|
+
uri: string;
|
|
24
|
+
projectId: string;
|
|
25
|
+
branchId: string;
|
|
26
|
+
databaseName: string;
|
|
27
|
+
roleName: string;
|
|
28
|
+
computeId?: string;
|
|
29
|
+
}
|
|
30
|
+
/** `neondb` when the branch has it, otherwise the first database. */
|
|
31
|
+
export declare const defaultDatabase: (neonClient: NeonClient<true>, ids: {
|
|
32
|
+
projectId: string;
|
|
33
|
+
branchId: string;
|
|
34
|
+
}, signal?: AbortSignal) => Promise<import("@neon/sdk").Database>;
|
|
35
|
+
/**
|
|
36
|
+
* Resolves the connection every SQL tool uses, and the URI `postgres.connectionString`
|
|
37
|
+
* returns. The URI embeds a role password, so the SQL tools keep it inside the tool.
|
|
38
|
+
*/
|
|
39
|
+
export declare const resolveConnection: (neonClient: NeonClient<true>, target: ConnectionTarget, context: NeonToolExecutionContext, signal?: AbortSignal) => Promise<ResolvedConnection>;
|
|
40
|
+
export declare const sqlClient: (uri: string, signal?: AbortSignal) => import("@neondatabase/serverless").NeonQueryFunction<false, false>;
|
|
41
|
+
/**
|
|
42
|
+
* Caller SQL that shares one transaction can escape `READ ONLY` with `COMMIT`
|
|
43
|
+
* or `SET TRANSACTION READ WRITE`, so these tools refuse instead.
|
|
44
|
+
*/
|
|
45
|
+
export declare const refuseInReadOnly: (context: NeonToolExecutionContext) => void;
|
|
46
|
+
//# sourceMappingURL=connection.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,WAAW,CAAC;AAE7D,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,KAAK,EACX,wBAAwB,EACxB,gBAAgB,EAChB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,0BAA0B,WAAW,CAAC;AAEnD,eAAO,MAAM,YAAY,EAAE,gBAM1B,CAAC;AAEF,eAAO,MAAM,yBAAyB,6DAAoF,CAAC;AAE3H,eAAO,MAAM,cAAc,aAEiB,CAAC;AAE7C,eAAO,MAAM,aAAa,4BAKxB,CAAC;AAEH,eAAO,MAAM,iBAAiB,4BAGO,CAAC;AAEtC,eAAO,MAAM,aAAa,4BAG4C,CAAC;AAEvE,eAAO,MAAM,sBAAsB,mEAC8B,CAAC;AAElE,eAAO,MAAM,cAAc,4BAGO,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,GAC3B,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,KAAK;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC5C,SAAS,WAAW,0CAcpB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC7B,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,QAAQ,gBAAgB,EACxB,SAAS,wBAAwB,EACjC,SAAS,WAAW,KAClB,OAAO,CAAC,kBAAkB,CAyD5B,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,SAAS,WAAW,uEACS,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,wBAAwB,SAMjE,CAAC"}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import { pathInputDescriptions } from "../../../descriptions.gen.js";
|
|
2
|
+
import { NeonClientError } from "@neon/sdk";
|
|
3
|
+
import { neon } from "@neondatabase/serverless";
|
|
4
|
+
import * as z from "zod";
|
|
5
|
+
// src/lib/custom/sql/connection.ts
|
|
6
|
+
const NEON_DEFAULT_DATABASE_NAME = "neondb";
|
|
7
|
+
const SQL_METADATA = {
|
|
8
|
+
method: "SQL",
|
|
9
|
+
path: "/projects/{project_id}/connection_uri",
|
|
10
|
+
stability: "stable",
|
|
11
|
+
deprecated: false,
|
|
12
|
+
tags: ["SQL"]
|
|
13
|
+
};
|
|
14
|
+
const DATABASE_NAME_DESCRIPTION = `Database name. Omit for ${NEON_DEFAULT_DATABASE_NAME}, else the first database.`;
|
|
15
|
+
const projectIdField = z.string().describe(pathInputDescriptions.project_id);
|
|
16
|
+
const branchIdField = z.string().optional().describe(`${pathInputDescriptions.branch_id} Omit it for the default branch.`);
|
|
17
|
+
const databaseNameField = z.string().optional().describe(DATABASE_NAME_DESCRIPTION);
|
|
18
|
+
const roleNameField = z.string().optional().describe("Postgres role to log in as. Omit for the database owner.");
|
|
19
|
+
const COMPUTE_ID_DESCRIPTION = "Compute endpoint id (ep-...). Omit for the read-write compute.";
|
|
20
|
+
const computeIdField = z.string().optional().describe(COMPUTE_ID_DESCRIPTION);
|
|
21
|
+
/** `neondb` when the branch has it, otherwise the first database. */
|
|
22
|
+
const defaultDatabase = async (neonClient, ids, signal) => {
|
|
23
|
+
const databases = await neonClient.postgres.databases.list(ids, { signal });
|
|
24
|
+
const first = databases[0];
|
|
25
|
+
if (first === void 0) throw new NeonClientError("No databases found in your project branch");
|
|
26
|
+
return databases.find((database) => database.name === "neondb") ?? first;
|
|
27
|
+
};
|
|
28
|
+
/**
|
|
29
|
+
* Resolves the connection every SQL tool uses, and the URI `postgres.connectionString`
|
|
30
|
+
* returns. The URI embeds a role password, so the SQL tools keep it inside the tool.
|
|
31
|
+
*/
|
|
32
|
+
const resolveConnection = async (neonClient, target, context, signal) => {
|
|
33
|
+
const projectId = target.project_id;
|
|
34
|
+
let roleName = target.role_name;
|
|
35
|
+
const pinnedRole = context.postgresRole;
|
|
36
|
+
if (pinnedRole !== void 0) {
|
|
37
|
+
if (roleName !== void 0 && roleName !== pinnedRole) throw new NeonClientError(`This connection is pinned to Postgres role "${pinnedRole}"; role_name "${roleName}" is not allowed.`);
|
|
38
|
+
roleName = pinnedRole;
|
|
39
|
+
}
|
|
40
|
+
const branchId = target.branch_id ?? (await neonClient.branches.getDefault({ projectId }, { signal })).id;
|
|
41
|
+
let databaseName = target.database_name;
|
|
42
|
+
if (databaseName === void 0) {
|
|
43
|
+
const database = await defaultDatabase(neonClient, {
|
|
44
|
+
projectId,
|
|
45
|
+
branchId
|
|
46
|
+
}, signal);
|
|
47
|
+
databaseName = database.name;
|
|
48
|
+
roleName ??= database.owner_name;
|
|
49
|
+
} else if (roleName === void 0) roleName = (await neonClient.postgres.databases.get({
|
|
50
|
+
projectId,
|
|
51
|
+
branchId,
|
|
52
|
+
databaseName
|
|
53
|
+
}, { signal })).owner_name;
|
|
54
|
+
return {
|
|
55
|
+
uri: await neonClient.postgres.connectionString({
|
|
56
|
+
projectId,
|
|
57
|
+
branchId,
|
|
58
|
+
databaseName,
|
|
59
|
+
roleName,
|
|
60
|
+
...target.compute_id === void 0 ? {} : { endpointId: target.compute_id },
|
|
61
|
+
...target.pooled === void 0 ? {} : { pooled: target.pooled }
|
|
62
|
+
}, { signal }),
|
|
63
|
+
projectId,
|
|
64
|
+
branchId,
|
|
65
|
+
databaseName,
|
|
66
|
+
roleName,
|
|
67
|
+
...target.compute_id === void 0 ? {} : { computeId: target.compute_id }
|
|
68
|
+
};
|
|
69
|
+
};
|
|
70
|
+
const sqlClient = (uri, signal) => neon(uri, signal === void 0 ? {} : { fetchOptions: { signal } });
|
|
71
|
+
/**
|
|
72
|
+
* Caller SQL that shares one transaction can escape `READ ONLY` with `COMMIT`
|
|
73
|
+
* or `SET TRANSACTION READ WRITE`, so these tools refuse instead.
|
|
74
|
+
*/
|
|
75
|
+
const refuseInReadOnly = (context) => {
|
|
76
|
+
if (context.readOnly === true) throw new NeonClientError("This tool is unavailable in read-only mode because it runs caller SQL that can leave a read-only transaction.");
|
|
77
|
+
};
|
|
78
|
+
export { COMPUTE_ID_DESCRIPTION, DATABASE_NAME_DESCRIPTION, NEON_DEFAULT_DATABASE_NAME, SQL_METADATA, branchIdField, computeIdField, databaseNameField, defaultDatabase, projectIdField, refuseInReadOnly, resolveConnection, roleNameField, sqlClient };
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import type { Branch, NeonClient } from "@neon/sdk";
|
|
2
|
+
import * as z from "zod";
|
|
3
|
+
import { type ToolClientOptions } from "../../ergonomic/bind.js";
|
|
4
|
+
import type { NeonToolExecutionContext } from "../../operation.js";
|
|
5
|
+
import type { Row } from "./rows.js";
|
|
6
|
+
export declare const describeBranchInputSchema: z.ZodObject<{
|
|
7
|
+
project_id: z.ZodString;
|
|
8
|
+
branch_id: z.ZodString;
|
|
9
|
+
database_name: z.ZodOptional<z.ZodString>;
|
|
10
|
+
}, z.core.$strict>;
|
|
11
|
+
export declare const branchConsoleUrl: (consoleUrl: string, projectId: string, branchId: string) => string;
|
|
12
|
+
export interface BranchDescription {
|
|
13
|
+
branch: Branch;
|
|
14
|
+
console_url: string;
|
|
15
|
+
/** The branch details and database tree as text. */
|
|
16
|
+
text: string;
|
|
17
|
+
/**
|
|
18
|
+
* `[[], treeRows]`, or null when the tree query failed. The leading empty array
|
|
19
|
+
* keeps the shape the Neon MCP server's `describe_branch` returns.
|
|
20
|
+
*/
|
|
21
|
+
database_structure: Row[][] | null;
|
|
22
|
+
database_structure_error?: string;
|
|
23
|
+
}
|
|
24
|
+
export declare const describeBranch: (neonClient: NeonClient<true>, input: {
|
|
25
|
+
project_id: string;
|
|
26
|
+
branch_id: string;
|
|
27
|
+
database_name?: string;
|
|
28
|
+
}, context: NeonToolExecutionContext, consoleUrl: string, signal?: AbortSignal) => Promise<BranchDescription>;
|
|
29
|
+
export declare const describeBranchTool: (options: ToolClientOptions) => import("../../operation.js").NeonTool<z.ZodObject<{
|
|
30
|
+
project_id: z.ZodString;
|
|
31
|
+
branch_id: z.ZodString;
|
|
32
|
+
database_name: z.ZodOptional<z.ZodString>;
|
|
33
|
+
}, z.core.$strict>, "describe_branches", {
|
|
34
|
+
branch: {
|
|
35
|
+
id: string;
|
|
36
|
+
project_id: string;
|
|
37
|
+
parent_id?: string | null | undefined;
|
|
38
|
+
parent_lsn?: string | null | undefined;
|
|
39
|
+
parent_timestamp?: string | null | undefined;
|
|
40
|
+
name: string;
|
|
41
|
+
current_state: import("@neon/sdk").BranchState;
|
|
42
|
+
pending_state?: string | null | undefined;
|
|
43
|
+
state_changed_at: string;
|
|
44
|
+
logical_size?: number | null | undefined;
|
|
45
|
+
creation_source: string;
|
|
46
|
+
primary?: boolean | null | undefined;
|
|
47
|
+
default: boolean;
|
|
48
|
+
protected: boolean;
|
|
49
|
+
cpu_used_sec: number;
|
|
50
|
+
compute_time_seconds: number;
|
|
51
|
+
active_time_seconds: number;
|
|
52
|
+
written_data_bytes: number;
|
|
53
|
+
data_transfer_bytes: number;
|
|
54
|
+
created_at: string;
|
|
55
|
+
updated_at: string;
|
|
56
|
+
ttl_interval_seconds?: number | null | undefined;
|
|
57
|
+
expires_at?: string | null | undefined;
|
|
58
|
+
last_reset_at?: string | null | undefined;
|
|
59
|
+
created_by?: {
|
|
60
|
+
name?: string | null | undefined;
|
|
61
|
+
image?: string | null | undefined;
|
|
62
|
+
} | null | undefined;
|
|
63
|
+
init_source?: string | null | undefined;
|
|
64
|
+
restore_status?: string | null | undefined;
|
|
65
|
+
restored_from?: string | null | undefined;
|
|
66
|
+
restored_as?: string | null | undefined;
|
|
67
|
+
restricted_actions?: {
|
|
68
|
+
name: string;
|
|
69
|
+
reason: string;
|
|
70
|
+
}[] | null | undefined;
|
|
71
|
+
recovery?: {
|
|
72
|
+
deleted_at: string;
|
|
73
|
+
recoverable_until: string;
|
|
74
|
+
deletion_method: "user" | "ttl";
|
|
75
|
+
} | null | undefined;
|
|
76
|
+
};
|
|
77
|
+
console_url: string;
|
|
78
|
+
text: string;
|
|
79
|
+
database_structure: {
|
|
80
|
+
[x: string]: unknown;
|
|
81
|
+
}[][] | null;
|
|
82
|
+
database_structure_error?: string | null | undefined;
|
|
83
|
+
}>;
|
|
84
|
+
//# sourceMappingURL=describe-branch.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"describe-branch.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/describe-branch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AASnE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGrC,eAAO,MAAM,yBAAyB;;;;kBAIpC,CAAC;AAkFH,eAAO,MAAM,gBAAgB,GAC5B,YAAY,MAAM,EAClB,WAAW,MAAM,EACjB,UAAU,MAAM,WAKJ,CAAC;AAoBd,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,kBAAkB,EAAE,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC;IACnC,wBAAwB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,eAAO,MAAM,cAAc,GAC1B,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,OAAO;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EACxE,SAAS,wBAAwB,EACjC,YAAY,MAAM,EAClB,SAAS,WAAW,KAClB,OAAO,CAAC,iBAAiB,CA6C3B,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAhE/C,MAAM;UAEb,MAAM;;;;;EAgFZ,CAAC"}
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
import { pathInputDescriptions } from "../../../descriptions.gen.js";
|
|
2
|
+
import { bindTool, publishedId } from "../../ergonomic/bind.js";
|
|
3
|
+
import { SQL_METADATA, databaseNameField, projectIdField, resolveConnection, sqlClient } from "./connection.js";
|
|
4
|
+
import { sqlReadAnnotations } from "./schema.js";
|
|
5
|
+
import { consoleBaseUrl } from "../resources.js";
|
|
6
|
+
import * as z from "zod";
|
|
7
|
+
// src/lib/custom/sql/describe-branch.ts
|
|
8
|
+
const describeBranchInputSchema = z.strictObject({
|
|
9
|
+
project_id: projectIdField,
|
|
10
|
+
branch_id: z.string().describe(pathInputDescriptions.branch_id),
|
|
11
|
+
database_name: databaseNameField
|
|
12
|
+
});
|
|
13
|
+
const DESCRIBE_DATABASE_QUERY = `
|
|
14
|
+
WITH RECURSIVE
|
|
15
|
+
schemas AS (
|
|
16
|
+
SELECT
|
|
17
|
+
n.nspname AS object_name,
|
|
18
|
+
1 AS level,
|
|
19
|
+
n.nspname AS path,
|
|
20
|
+
'SCHEMA' AS object_type
|
|
21
|
+
FROM pg_namespace n
|
|
22
|
+
WHERE n.nspname NOT LIKE 'pg_%'
|
|
23
|
+
AND n.nspname != 'information_schema'
|
|
24
|
+
),
|
|
25
|
+
|
|
26
|
+
objects AS (
|
|
27
|
+
SELECT
|
|
28
|
+
c.relname AS object_name,
|
|
29
|
+
2 AS level,
|
|
30
|
+
s.path || ' → ' || c.relname AS path,
|
|
31
|
+
CASE c.relkind
|
|
32
|
+
WHEN 'r' THEN 'TABLE'
|
|
33
|
+
WHEN 'v' THEN 'VIEW'
|
|
34
|
+
WHEN 'm' THEN 'MATERIALIZED VIEW'
|
|
35
|
+
WHEN 'i' THEN 'INDEX'
|
|
36
|
+
WHEN 'S' THEN 'SEQUENCE'
|
|
37
|
+
WHEN 'f' THEN 'FOREIGN TABLE'
|
|
38
|
+
END AS object_type
|
|
39
|
+
FROM pg_class c
|
|
40
|
+
JOIN pg_namespace n ON n.oid = c.relnamespace
|
|
41
|
+
JOIN schemas s ON n.nspname = s.object_name
|
|
42
|
+
WHERE c.relkind IN ('r','v','m','i','S','f')
|
|
43
|
+
|
|
44
|
+
UNION ALL
|
|
45
|
+
|
|
46
|
+
SELECT
|
|
47
|
+
p.proname AS object_name,
|
|
48
|
+
2 AS level,
|
|
49
|
+
s.path || ' → ' || p.proname AS path,
|
|
50
|
+
'FUNCTION' AS object_type
|
|
51
|
+
FROM pg_proc p
|
|
52
|
+
JOIN pg_namespace n ON n.oid = p.pronamespace
|
|
53
|
+
JOIN schemas s ON n.nspname = s.object_name
|
|
54
|
+
),
|
|
55
|
+
|
|
56
|
+
combined AS (
|
|
57
|
+
SELECT * FROM schemas
|
|
58
|
+
UNION ALL
|
|
59
|
+
SELECT * FROM objects
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
SELECT tree_structure FROM (
|
|
63
|
+
SELECT 0 AS part, NULL::text AS path, ':file_folder: ' || datname || ' (DATABASE)' AS tree_structure
|
|
64
|
+
FROM pg_database
|
|
65
|
+
WHERE datistemplate = false
|
|
66
|
+
|
|
67
|
+
UNION ALL
|
|
68
|
+
|
|
69
|
+
SELECT 1 AS part, path,
|
|
70
|
+
REPEAT(' ', level) ||
|
|
71
|
+
CASE
|
|
72
|
+
WHEN level = 1 THEN '└── :open_file_folder: '
|
|
73
|
+
ELSE ' └── ' ||
|
|
74
|
+
CASE object_type
|
|
75
|
+
WHEN 'TABLE' THEN ':bar_chart: '
|
|
76
|
+
WHEN 'VIEW' THEN ':eye: '
|
|
77
|
+
WHEN 'MATERIALIZED VIEW' THEN ':newspaper: '
|
|
78
|
+
WHEN 'FUNCTION' THEN ':zap: '
|
|
79
|
+
WHEN 'INDEX' THEN ':mag: '
|
|
80
|
+
WHEN 'SEQUENCE' THEN ':1234: '
|
|
81
|
+
WHEN 'FOREIGN TABLE' THEN ':globe_with_meridians: '
|
|
82
|
+
ELSE ''
|
|
83
|
+
END
|
|
84
|
+
END || object_name || ' (' || object_type || ')' AS tree_structure
|
|
85
|
+
FROM combined
|
|
86
|
+
) tree
|
|
87
|
+
ORDER BY part, path;
|
|
88
|
+
`;
|
|
89
|
+
const branchConsoleUrl = (consoleUrl, projectId, branchId) => new URL(`/app/projects/${encodeURIComponent(projectId)}/branches/${encodeURIComponent(branchId)}`, consoleUrl).toString();
|
|
90
|
+
const branchInfo = (branch, consoleLink) => `Branch Details:
|
|
91
|
+
Name: ${branch.name}
|
|
92
|
+
ID: ${branch.id}
|
|
93
|
+
Parent Branch: ${branch.parent_id}
|
|
94
|
+
Default: ${branch.default}
|
|
95
|
+
Protected: ${branch.protected ? "Yes" : "No"}
|
|
96
|
+
|
|
97
|
+
${branch.created_by ? `Created By: ${branch.created_by.name}` : ""}
|
|
98
|
+
Created: ${new Date(branch.created_at).toLocaleDateString()}
|
|
99
|
+
Updated: ${new Date(branch.updated_at).toLocaleDateString()}
|
|
100
|
+
|
|
101
|
+
Compute Usage: ${branch.compute_time_seconds} seconds
|
|
102
|
+
Written Data: ${branch.written_data_bytes} bytes
|
|
103
|
+
Data Transfer: ${branch.data_transfer_bytes} bytes
|
|
104
|
+
|
|
105
|
+
Console Link: ${consoleLink}
|
|
106
|
+
`;
|
|
107
|
+
const describeBranch = async (neonClient, input, context, consoleUrl, signal) => {
|
|
108
|
+
const branch = await neonClient.branches.get({
|
|
109
|
+
projectId: input.project_id,
|
|
110
|
+
branchId: input.branch_id
|
|
111
|
+
}, { signal });
|
|
112
|
+
const url = branchConsoleUrl(consoleUrl, branch.project_id, branch.id);
|
|
113
|
+
const info = branchInfo(branch, url);
|
|
114
|
+
try {
|
|
115
|
+
const connection = await resolveConnection(neonClient, {
|
|
116
|
+
project_id: input.project_id,
|
|
117
|
+
branch_id: branch.id,
|
|
118
|
+
database_name: input.database_name
|
|
119
|
+
}, context, signal);
|
|
120
|
+
const sql = sqlClient(connection.uri, signal);
|
|
121
|
+
const [tree] = await sql.transaction([sql.query(DESCRIBE_DATABASE_QUERY)], { readOnly: true });
|
|
122
|
+
const structure = [[], tree];
|
|
123
|
+
return {
|
|
124
|
+
branch,
|
|
125
|
+
console_url: url,
|
|
126
|
+
text: `${info}\nDatabase Structure:\n${JSON.stringify(structure, null, 2)}`,
|
|
127
|
+
database_structure: structure
|
|
128
|
+
};
|
|
129
|
+
} catch (error) {
|
|
130
|
+
if (signal?.aborted) throw error;
|
|
131
|
+
const reason = error instanceof Error ? error.message : String(error);
|
|
132
|
+
const message = context.postgresRole === void 0 ? `Database structure unavailable: ${reason}` : `Database structure unavailable as Postgres role "${context.postgresRole}": ${reason}`;
|
|
133
|
+
return {
|
|
134
|
+
branch,
|
|
135
|
+
console_url: url,
|
|
136
|
+
text: `${info}\n${message}`,
|
|
137
|
+
database_structure: null,
|
|
138
|
+
database_structure_error: message
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
};
|
|
142
|
+
const describeBranchTool = (options) => {
|
|
143
|
+
const consoleUrl = consoleBaseUrl(options.baseUrl ?? "https://console.neon.tech/api/v2");
|
|
144
|
+
return bindTool(options, {
|
|
145
|
+
operationId: "branches.describe",
|
|
146
|
+
id: publishedId("branches.describe"),
|
|
147
|
+
title: "Describe Branch",
|
|
148
|
+
description: "Returns a branch summary, its database names, and a tree of one database's schemas, tables, views, indexes, sequences, and functions. Starts a suspended compute. Branch record only: {{branches.get}}; table names: {{schema.listTables}}; columns: {{schema.describeTable}}.",
|
|
149
|
+
inputSchema: describeBranchInputSchema,
|
|
150
|
+
annotations: sqlReadAnnotations,
|
|
151
|
+
requiresApproval: false,
|
|
152
|
+
metadata: SQL_METADATA
|
|
153
|
+
}, (neonClient, input, signal, context) => describeBranch(neonClient, input, context, consoleUrl, signal));
|
|
154
|
+
};
|
|
155
|
+
export { branchConsoleUrl, describeBranch, describeBranchInputSchema, describeBranchTool };
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import * as z from "zod";
|
|
2
|
+
import { type ToolClientOptions } from "../../../ergonomic/bind.js";
|
|
3
|
+
import { type InspectCheck } from "./queries.js";
|
|
4
|
+
/**
|
|
5
|
+
* Postgres rejected one of the package's own diagnostic queries. That is a bug
|
|
6
|
+
* in the catalog, not in the caller's input, so hosts should report it like any
|
|
7
|
+
* other server fault. `cause` is the original `NeonDbError`.
|
|
8
|
+
*/
|
|
9
|
+
export declare class InspectDiagnosticError extends Error {
|
|
10
|
+
readonly check: InspectCheck;
|
|
11
|
+
constructor(message: string, check: InspectCheck, cause: unknown);
|
|
12
|
+
}
|
|
13
|
+
export declare const inspectDatabaseInputSchema: z.ZodObject<{
|
|
14
|
+
check: z.ZodEnum<{
|
|
15
|
+
"table-sizes": "table-sizes";
|
|
16
|
+
"index-sizes": "index-sizes";
|
|
17
|
+
"unused-indexes": "unused-indexes";
|
|
18
|
+
"seq-scans": "seq-scans";
|
|
19
|
+
"long-running-queries": "long-running-queries";
|
|
20
|
+
"stalled-queries": "stalled-queries";
|
|
21
|
+
locks: "locks";
|
|
22
|
+
outliers: "outliers";
|
|
23
|
+
calls: "calls";
|
|
24
|
+
"lfc-hit-rate": "lfc-hit-rate";
|
|
25
|
+
"working-set": "working-set";
|
|
26
|
+
"vacuum-stats": "vacuum-stats";
|
|
27
|
+
bloat: "bloat";
|
|
28
|
+
"replication-slots": "replication-slots";
|
|
29
|
+
subscriptions: "subscriptions";
|
|
30
|
+
}>;
|
|
31
|
+
project_id: z.ZodString;
|
|
32
|
+
branch_id: z.ZodOptional<z.ZodString>;
|
|
33
|
+
database_name: z.ZodOptional<z.ZodString>;
|
|
34
|
+
compute_id: z.ZodOptional<z.ZodString>;
|
|
35
|
+
limit: z.ZodDefault<z.ZodNumber>;
|
|
36
|
+
}, z.core.$strict>;
|
|
37
|
+
export declare const inspectDatabaseTool: (options: ToolClientOptions) => import("../../../operation.js").NeonTool<z.ZodObject<{
|
|
38
|
+
check: z.ZodEnum<{
|
|
39
|
+
"table-sizes": "table-sizes";
|
|
40
|
+
"index-sizes": "index-sizes";
|
|
41
|
+
"unused-indexes": "unused-indexes";
|
|
42
|
+
"seq-scans": "seq-scans";
|
|
43
|
+
"long-running-queries": "long-running-queries";
|
|
44
|
+
"stalled-queries": "stalled-queries";
|
|
45
|
+
locks: "locks";
|
|
46
|
+
outliers: "outliers";
|
|
47
|
+
calls: "calls";
|
|
48
|
+
"lfc-hit-rate": "lfc-hit-rate";
|
|
49
|
+
"working-set": "working-set";
|
|
50
|
+
"vacuum-stats": "vacuum-stats";
|
|
51
|
+
bloat: "bloat";
|
|
52
|
+
"replication-slots": "replication-slots";
|
|
53
|
+
subscriptions: "subscriptions";
|
|
54
|
+
}>;
|
|
55
|
+
project_id: z.ZodString;
|
|
56
|
+
branch_id: z.ZodOptional<z.ZodString>;
|
|
57
|
+
database_name: z.ZodOptional<z.ZodString>;
|
|
58
|
+
compute_id: z.ZodOptional<z.ZodString>;
|
|
59
|
+
limit: z.ZodDefault<z.ZodNumber>;
|
|
60
|
+
}, z.core.$strict>, "inspect_database", {
|
|
61
|
+
check: InspectCheck;
|
|
62
|
+
describe: string;
|
|
63
|
+
projectId: string;
|
|
64
|
+
branchId: string;
|
|
65
|
+
databaseName?: string | null | undefined;
|
|
66
|
+
databases: string[];
|
|
67
|
+
fields: string[];
|
|
68
|
+
totalRowCount: number;
|
|
69
|
+
rows: {
|
|
70
|
+
[x: string]: unknown;
|
|
71
|
+
}[];
|
|
72
|
+
truncated: boolean;
|
|
73
|
+
note?: string | null | undefined;
|
|
74
|
+
}>;
|
|
75
|
+
//# sourceMappingURL=inspect.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../../../src/lib/custom/sql/inspect/inspect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EAKN,KAAK,YAAY,EACjB,MAAM,cAAc,CAAC;AAItB;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO;CAKhE;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;kBAsBrC,CAAC;AAyEH,eAAO,MAAM,mBAAmB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2G5D,CAAC"}
|