@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,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,22 @@
1
+ import { type InspectCheck } from "./queries.js";
2
+ import type { InspectQueryScope } from "./targets.js";
3
+ export interface InspectCheckInfo {
4
+ readonly id: InspectCheck;
5
+ /** The `describe` text the result carries. */
6
+ readonly description: string;
7
+ /** `compute` checks run once for the whole compute, whatever `database_name` is. */
8
+ readonly scope: InspectQueryScope;
9
+ /** The extension the check needs; without it the tool throws before running SQL. */
10
+ readonly requiresExtension?: string;
11
+ /** Output columns in order. A run over every database adds `database` first. */
12
+ readonly fields: readonly string[];
13
+ /** Rows the SQL returns at most, per database. */
14
+ readonly sqlLimit?: number;
15
+ /** The `note` of an empty result for one database, or for a `compute` check. */
16
+ readonly emptyNote: string;
17
+ /** The `note` of an empty result when `database_name` is omitted. Only `database` checks have it. */
18
+ readonly emptyNoteAllDatabases?: string;
19
+ }
20
+ /** The checks `database.inspect` runs, in the order its `check` input lists them. */
21
+ export declare const inspectChecks: readonly InspectCheckInfo[];
22
+ //# sourceMappingURL=catalog.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../../src/lib/custom/sql/inspect/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,YAAY,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qGAAqG;IACrG,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED,qFAAqF;AACrF,eAAO,MAAM,aAAa,EAAE,SAAS,gBAAgB,EAoBpD,CAAC"}
@@ -0,0 +1,18 @@
1
+ import { INSPECT_CHECKS, INSPECT_QUERIES } from "./queries.js";
2
+ import { emptyResultNote } from "./report.js";
3
+ // src/lib/custom/sql/inspect/catalog.ts
4
+ /** The checks `database.inspect` runs, in the order its `check` input lists them. */
5
+ const inspectChecks = Object.freeze(INSPECT_CHECKS.map((id) => {
6
+ const query = INSPECT_QUERIES[id];
7
+ return Object.freeze({
8
+ id,
9
+ description: query.describe,
10
+ scope: query.scope,
11
+ ...query.requiresExtension === void 0 ? {} : { requiresExtension: query.requiresExtension },
12
+ fields: Object.freeze([...query.fields]),
13
+ ...query.sqlLimit === void 0 ? {} : { sqlLimit: query.sqlLimit },
14
+ emptyNote: emptyResultNote(query, false),
15
+ ...query.scope === "database" ? { emptyNoteAllDatabases: emptyResultNote(query, true) } : {}
16
+ });
17
+ }));
18
+ export { inspectChecks };
@@ -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"}