@neon/tools 2.14.3 → 2.14.4

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 CHANGED
@@ -123,7 +123,7 @@ Custom tools combine several requests into one call, or call Postgres or neon.co
123
123
  | `sql.runTransaction` | `run_transaction_sql` | One `{ rows, totalRowCount, truncated, note? }` per statement, run in one transaction. |
124
124
  | `sql.explain` | `explain_sql` | The `EXPLAIN (FORMAT JSON)` rows. `analyze: true` executes the statement. |
125
125
  | `schema.listTables` | `list_tables_schema` | `{ table_schema, table_name, table_type }` for every table outside `pg_catalog` and `information_schema`. |
126
- | `schema.describeTable` | `describe_table_schema` | `{ raw, formatted }`: columns, indexes, constraints, and sizes. A missing table throws `NeonClientError`. |
126
+ | `schema.describeTable` | `describe_table_schema` | `{ raw, formatted }`: columns, indexes, constraints, and sizes. A missing table, or a name that matches two tables, throws `NeonClientError`. |
127
127
  | `branches.describe` | `describe_branches` | `{ branch, console_url, text, database_structure }`, where `database_structure` is `[[], rows]`: one `{ tree_structure }` row per database, then the connected database's schemas and objects, read from the system catalogs in a `READ ONLY` transaction. When that query fails it is `null` and `database_structure_error` says why. |
128
128
  | `queries.listSlow` | `list_slow_queries` | `{ slow_queries, total_queries_found }` from `pg_stat_statements`, slowest mean time first. Without the extension it throws `NeonClientError`. |
129
129
  | `database.inspect` | `inspect_database` | One `neon inspect db` check: `{ check, describe, projectId, branchId, databases, fields, totalRowCount, rows, truncated, note? }`. |
@@ -14,8 +14,14 @@ export interface QueryMetrics {
14
14
  local: BufferMetrics;
15
15
  };
16
16
  }
17
- /** Every `schema.relation` an `EXPLAIN (FORMAT JSON)` result scans. */
18
- export declare const extractTableNamesFromPlan: (plan: unknown) => string[];
17
+ export interface PlanTable {
18
+ /** `schema.relation`, as the plan spells it. */
19
+ name: string;
20
+ /** The quoted SQL name, which resolves to exactly this relation. */
21
+ quotedName: string;
22
+ }
23
+ /** Every relation an `EXPLAIN (FORMAT JSON)` result scans. */
24
+ export declare const extractTablesFromPlan: (plan: unknown) => PlanTable[];
19
25
  /**
20
26
  * Query-level totals from the rows `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)`
21
27
  * returns: one row whose `QUERY PLAN` column holds the plan document. They come
@@ -1 +1 @@
1
- {"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/plan.ts"],"names":[],"mappings":"AAAA,UAAU,aAAa;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QACZ,MAAM,EAAE,aAAa,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;KACrB,CAAC;CACF;AAUD,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,GAAI,MAAM,OAAO,KAAG,MAAM,EAiB/D,CAAC;AAYF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,OAAO,KAAG,YAkBvD,CAAC"}
1
+ {"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/plan.ts"],"names":[],"mappings":"AAAA,UAAU,aAAa;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QACZ,MAAM,EAAE,aAAa,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;KACrB,CAAC;CACF;AAUD,MAAM,WAAW,SAAS;IACzB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACnB;AAKD,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,GAAI,MAAM,OAAO,KAAG,SAAS,EAqB9D,CAAC;AAYF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,OAAO,KAAG,YAkBvD,CAAC"}
@@ -4,9 +4,10 @@ const numberAt = (node, key) => {
4
4
  const value = node[key];
5
5
  return typeof value === "number" ? value : 0;
6
6
  };
7
- /** Every `schema.relation` an `EXPLAIN (FORMAT JSON)` result scans. */
8
- const extractTableNamesFromPlan = (plan) => {
9
- const tableNames = /* @__PURE__ */ new Set();
7
+ const quoteIdentifier = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
8
+ /** Every relation an `EXPLAIN (FORMAT JSON)` result scans. */
9
+ const extractTablesFromPlan = (plan) => {
10
+ const tables = /* @__PURE__ */ new Map();
10
11
  const visit = (node) => {
11
12
  if (Array.isArray(node)) {
12
13
  for (const item of node) visit(item);
@@ -15,11 +16,17 @@ const extractTableNamesFromPlan = (plan) => {
15
16
  if (!isRecord(node)) return;
16
17
  const relation = node["Relation Name"];
17
18
  const schema = node.Schema;
18
- if (typeof relation === "string" && typeof schema === "string") tableNames.add(`${schema}.${relation}`);
19
+ if (typeof relation === "string" && typeof schema === "string") {
20
+ const quotedName = `${quoteIdentifier(schema)}.${quoteIdentifier(relation)}`;
21
+ tables.set(quotedName, {
22
+ name: `${schema}.${relation}`,
23
+ quotedName
24
+ });
25
+ }
19
26
  for (const value of Object.values(node)) visit(value);
20
27
  };
21
28
  visit(plan);
22
- return [...tableNames];
29
+ return [...tables.values()];
23
30
  };
24
31
  const buffers = (node, prefix) => ({
25
32
  hit: numberAt(node, `${prefix} Hit Blocks`),
@@ -50,4 +57,4 @@ const extractExecutionMetrics = (rows) => {
50
57
  }
51
58
  };
52
59
  };
53
- export { extractExecutionMetrics, extractTableNamesFromPlan };
60
+ export { extractExecutionMetrics, extractTablesFromPlan };
@@ -4,7 +4,7 @@ import { SQL_METADATA, projectIdField, refuseInReadOnly, resolveConnection } fro
4
4
  import { describeTableAt } from "./schema.js";
5
5
  import { explainStatement, runTransaction, sqlWriteAnnotations } from "./run.js";
6
6
  import { withTemporaryBranch } from "./migrations.js";
7
- import { extractExecutionMetrics, extractTableNamesFromPlan } from "./plan.js";
7
+ import { extractExecutionMetrics, extractTablesFromPlan } from "./plan.js";
8
8
  import { NeonClientError } from "@neon/sdk";
9
9
  import * as z from "zod";
10
10
  import { randomUUID } from "node:crypto";
@@ -55,12 +55,12 @@ const prepareQueryTuningTool = (options) => bindTool(options, {
55
55
  sql: input.sql,
56
56
  analyze: true
57
57
  }, context, signal);
58
- const tableNames = extractTableNamesFromPlan(executionPlan);
59
- if (tableNames.length === 0) throw new NeonClientError("No tables found in execution plan. Cannot proceed with optimization.");
58
+ const tables = extractTablesFromPlan(executionPlan);
59
+ if (tables.length === 0) throw new NeonClientError("No tables found in execution plan. Cannot proceed with optimization.");
60
60
  const connection = await resolveConnection(neonClient, target, context, signal);
61
- const tableSchemas = await Promise.all(tableNames.map(async (tableName) => {
61
+ const tableSchemas = await Promise.all(tables.map(async ({ name: tableName, quotedName }) => {
62
62
  try {
63
- const schema = await describeTableAt(connection.uri, tableName, signal);
63
+ const schema = await describeTableAt(connection.uri, quotedName, signal);
64
64
  return {
65
65
  tableName,
66
66
  schema: schema.raw,
@@ -1 +1 @@
1
- {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/schema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAU9D,eAAO,MAAM,kBAAkB,EAAE,mBAKhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;kBAIhC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;kBASnC,CAAC;AAsFH,UAAU,iBAAiB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,gBAAgB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,UAAU,qBAAqB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAgDD,eAAO,MAAM,sBAAsB,GAAI,MAAM,gBAAgB,KAAG,MAmC/D,CAAC;AAEF,eAAO,MAAM,eAAe,GAC3B,KAAK,MAAM,EACX,WAAW,MAAM,EACjB,SAAS,WAAW;;;EAUpB,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,SAAS,iBAAiB;;;;;;IAuBvD,CAAC;AAEH,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB;;;;;;;;kBAvJrD,MAAM;kBACN,MAAM;sBACF,OAAO;qBACR,MAAM,GAAG,IAAI;yBACT,MAAM,GAAG,IAAI;;;kBAIpB,MAAM;wBACA,MAAM;kBACZ,MAAM;;;kBAIN,MAAM;kBACN,MAAM;wBACA,MAAM;;mBAOP,MAAM;mBACN,MAAM;mBACN,MAAM;;;EAqJhB,CAAC"}
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/schema.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAU9D,eAAO,MAAM,kBAAkB,EAAE,mBAKhC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;kBAIhC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;kBASnC,CAAC;AAyGH,UAAU,iBAAiB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,gBAAgB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,UAAU,qBAAqB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAmDD,eAAO,MAAM,sBAAsB,GAAI,MAAM,gBAAgB,KAAG,MAmC/D,CAAC;AAEF,eAAO,MAAM,eAAe,GAC3B,KAAK,MAAM,EACX,WAAW,MAAM,EACjB,SAAS,WAAW;;;EAUpB,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,SAAS,iBAAiB;;;;;;IAuBvD,CAAC;AAEH,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB;;;;;;;;kBA1JrD,MAAM;kBACN,MAAM;sBACF,OAAO;qBACR,MAAM,GAAG,IAAI;yBACT,MAAM,GAAG,IAAI;;;kBAIpB,MAAM;wBACA,MAAM;kBACZ,MAAM;;;kBAIN,MAAM;kBACN,MAAM;wBACA,MAAM;;mBAOP,MAAM;mBACN,MAAM;mBACN,MAAM;;;EAwJhB,CAAC"}
@@ -29,6 +29,27 @@ const LIST_TABLES_SQL = `
29
29
  WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
30
30
  ORDER BY table_schema, table_name;
31
31
  `;
32
+ const RESOLVE_TABLE_SQL = `
33
+ WITH candidates AS (
34
+ SELECT oid
35
+ FROM pg_catalog.pg_class
36
+ WHERE relname = $1::text AND pg_catalog.pg_table_is_visible(oid)
37
+ UNION
38
+ SELECT cls.oid
39
+ FROM pg_catalog.pg_class cls
40
+ JOIN pg_catalog.pg_namespace ns ON ns.oid = cls.relnamespace
41
+ WHERE ns.nspname || '.' || cls.relname = $1
42
+ UNION
43
+ SELECT to_regclass($1)::oid
44
+ )
45
+ SELECT
46
+ cls.oid::text AS oid,
47
+ format('%I.%I', ns.nspname, cls.relname) AS quoted_name
48
+ FROM candidates
49
+ JOIN pg_catalog.pg_class cls ON cls.oid = candidates.oid
50
+ JOIN pg_catalog.pg_namespace ns ON ns.oid = cls.relnamespace
51
+ ORDER BY quoted_name;
52
+ `;
32
53
  const DESCRIBE_COLUMNS_SQL = `
33
54
  WITH target AS (
34
55
  SELECT
@@ -37,7 +58,7 @@ const DESCRIBE_COLUMNS_SQL = `
37
58
  cls.relname AS table_name
38
59
  FROM pg_catalog.pg_class cls
39
60
  JOIN pg_catalog.pg_namespace ns ON ns.oid = cls.relnamespace
40
- WHERE cls.oid = to_regclass($1)
61
+ WHERE cls.oid = $1::oid
41
62
  )
42
63
  SELECT
43
64
  c.column_name as name,
@@ -55,57 +76,49 @@ const DESCRIBE_COLUMNS_SQL = `
55
76
  ORDER BY c.ordinal_position;
56
77
  `;
57
78
  const DESCRIBE_INDEXES_SQL = `
58
- WITH target AS (
59
- SELECT to_regclass($1) AS oid
60
- )
61
79
  SELECT
62
80
  i.relname as name,
63
81
  pg_get_indexdef(i.oid) as definition,
64
82
  pg_size_pretty(pg_relation_size(i.oid)) as size
65
- FROM target
66
- JOIN pg_catalog.pg_class t ON t.oid = target.oid
83
+ FROM pg_catalog.pg_class t
67
84
  JOIN pg_catalog.pg_index ix ON t.oid = ix.indrelid
68
85
  JOIN pg_catalog.pg_class i ON i.oid = ix.indexrelid
69
- WHERE t.relkind = 'r';
86
+ WHERE t.oid = $1::oid AND t.relkind = 'r';
70
87
  `;
71
88
  const DESCRIBE_CONSTRAINTS_SQL = `
72
- WITH target AS (
73
- SELECT
74
- cls.oid,
75
- ns.nspname AS table_schema,
76
- cls.relname AS table_name
77
- FROM pg_catalog.pg_class cls
78
- JOIN pg_catalog.pg_namespace ns ON ns.oid = cls.relnamespace
79
- WHERE cls.oid = to_regclass($1)
80
- )
81
89
  SELECT
82
- tc.constraint_name as name,
83
- tc.constraint_type as type,
84
- pg_get_constraintdef(cc.oid) as definition
85
- FROM target t
86
- JOIN information_schema.table_constraints tc
87
- ON tc.table_schema = t.table_schema
88
- AND tc.table_name = t.table_name
89
- JOIN pg_catalog.pg_constraint cc
90
- ON cc.conrelid = t.oid
91
- AND cc.conname = tc.constraint_name;
90
+ conname as name,
91
+ CASE contype
92
+ WHEN 'p' THEN 'PRIMARY KEY'
93
+ WHEN 'f' THEN 'FOREIGN KEY'
94
+ WHEN 'u' THEN 'UNIQUE'
95
+ WHEN 'c' THEN 'CHECK'
96
+ WHEN 'x' THEN 'EXCLUDE'
97
+ END as type,
98
+ pg_get_constraintdef(oid) as definition
99
+ FROM pg_catalog.pg_constraint
100
+ WHERE conrelid = $1::oid AND contype IN ('p', 'f', 'u', 'c', 'x')
101
+ ORDER BY conname;
92
102
  `;
93
103
  const DESCRIBE_SIZES_SQL = `
94
104
  SELECT
95
- pg_size_pretty(pg_total_relation_size(to_regclass($1))) as total_size,
96
- pg_size_pretty(pg_relation_size(to_regclass($1))) as table_size,
105
+ pg_size_pretty(pg_total_relation_size($1::oid)) as total_size,
106
+ pg_size_pretty(pg_relation_size($1::oid)) as table_size,
97
107
  pg_size_pretty(
98
- pg_total_relation_size(to_regclass($1)) - pg_relation_size(to_regclass($1))
108
+ pg_total_relation_size($1::oid) - pg_relation_size($1::oid)
99
109
  ) as index_size;
100
110
  `;
101
111
  const describeTable = async (uri, tableName, signal) => {
102
112
  const sql = sqlClient(uri, signal);
103
- if (typeof (await sql.query("SELECT to_regclass($1)::text AS relation_name", [tableName]))[0]?.relation_name !== "string") return null;
113
+ const candidates = await sql.query(RESOLVE_TABLE_SQL, [tableName]);
114
+ const [table, ...others] = candidates;
115
+ if (table === void 0) return null;
116
+ if (others.length > 0) throw new NeonClientError(`Table name ${tableName} matches ${candidates.length} tables. Pass one of these quoted names: ${candidates.map((candidate) => candidate.quoted_name).join(", ")}`);
104
117
  const [columns, indexes, constraints, sizes] = await Promise.all([
105
- sql.query(DESCRIBE_COLUMNS_SQL, [tableName]),
106
- sql.query(DESCRIBE_INDEXES_SQL, [tableName]),
107
- sql.query(DESCRIBE_CONSTRAINTS_SQL, [tableName]),
108
- sql.query(DESCRIBE_SIZES_SQL, [tableName])
118
+ sql.query(DESCRIBE_COLUMNS_SQL, [table.oid]),
119
+ sql.query(DESCRIBE_INDEXES_SQL, [table.oid]),
120
+ sql.query(DESCRIBE_CONSTRAINTS_SQL, [table.oid]),
121
+ sql.query(DESCRIBE_SIZES_SQL, [table.oid])
109
122
  ]);
110
123
  const size = sizes[0];
111
124
  if (size === void 0) throw new Error(`Table size query returned no row for ${tableName}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@neon/tools",
3
- "version": "2.14.3",
3
+ "version": "2.14.4",
4
4
  "description": "Agent tools for the Neon SDK ergonomic client, compatible with MCP, Eve, and Mastra.",
5
5
  "keywords": [
6
6
  "neon",