@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.
Files changed (91) hide show
  1. package/README.md +150 -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 +3 -3
  6. package/dist/index.d.ts +4 -3
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +14 -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/inspect.d.ts +75 -0
  34. package/dist/lib/custom/sql/inspect/inspect.d.ts.map +1 -0
  35. package/dist/lib/custom/sql/inspect/inspect.js +135 -0
  36. package/dist/lib/custom/sql/inspect/queries.d.ts +63 -0
  37. package/dist/lib/custom/sql/inspect/queries.d.ts.map +1 -0
  38. package/dist/lib/custom/sql/inspect/queries.js +528 -0
  39. package/dist/lib/custom/sql/inspect/report.d.ts +31 -0
  40. package/dist/lib/custom/sql/inspect/report.d.ts.map +1 -0
  41. package/dist/lib/custom/sql/inspect/report.js +43 -0
  42. package/dist/lib/custom/sql/inspect/targets.d.ts +27 -0
  43. package/dist/lib/custom/sql/inspect/targets.d.ts.map +1 -0
  44. package/dist/lib/custom/sql/inspect/targets.js +33 -0
  45. package/dist/lib/custom/sql/migrations.d.ts +69 -0
  46. package/dist/lib/custom/sql/migrations.d.ts.map +1 -0
  47. package/dist/lib/custom/sql/migrations.js +144 -0
  48. package/dist/lib/custom/sql/plan.d.ts +27 -0
  49. package/dist/lib/custom/sql/plan.d.ts.map +1 -0
  50. package/dist/lib/custom/sql/plan.js +53 -0
  51. package/dist/lib/custom/sql/query-tuning.d.ts +107 -0
  52. package/dist/lib/custom/sql/query-tuning.d.ts.map +1 -0
  53. package/dist/lib/custom/sql/query-tuning.js +129 -0
  54. package/dist/lib/custom/sql/rows.d.ts +11 -0
  55. package/dist/lib/custom/sql/rows.d.ts.map +1 -0
  56. package/dist/lib/custom/sql/rows.js +19 -0
  57. package/dist/lib/custom/sql/run.d.ts +81 -0
  58. package/dist/lib/custom/sql/run.d.ts.map +1 -0
  59. package/dist/lib/custom/sql/run.js +90 -0
  60. package/dist/lib/custom/sql/schema.d.ts +84 -0
  61. package/dist/lib/custom/sql/schema.d.ts.map +1 -0
  62. package/dist/lib/custom/sql/schema.js +201 -0
  63. package/dist/lib/custom/sql/slow-queries.d.ts +43 -0
  64. package/dist/lib/custom/sql/slow-queries.d.ts.map +1 -0
  65. package/dist/lib/custom/sql/slow-queries.js +87 -0
  66. package/dist/lib/customize.d.ts +9 -2
  67. package/dist/lib/customize.d.ts.map +1 -1
  68. package/dist/lib/customize.js +21 -7
  69. package/dist/lib/ergonomic/bind.d.ts +11 -1
  70. package/dist/lib/ergonomic/bind.d.ts.map +1 -1
  71. package/dist/lib/ergonomic/bind.js +13 -3
  72. package/dist/lib/ergonomic/catalog.d.ts +854 -39
  73. package/dist/lib/ergonomic/catalog.d.ts.map +1 -1
  74. package/dist/lib/ergonomic/catalog.js +35 -8
  75. package/dist/lib/ergonomic/composed.d.ts +4 -4
  76. package/dist/lib/ergonomic/composed.d.ts.map +1 -1
  77. package/dist/lib/ergonomic/composed.js +47 -45
  78. package/dist/lib/ergonomic/ids.d.ts +3 -1
  79. package/dist/lib/ergonomic/ids.d.ts.map +1 -1
  80. package/dist/lib/ergonomic/ids.js +41 -2
  81. package/dist/lib/ergonomic/index.d.ts +1 -1
  82. package/dist/lib/ergonomic/index.d.ts.map +1 -1
  83. package/dist/lib/ergonomic/index.js +2 -2
  84. package/dist/lib/operation.d.ts +11 -0
  85. package/dist/lib/operation.d.ts.map +1 -1
  86. package/dist/lib/references.d.ts +10 -0
  87. package/dist/lib/references.d.ts.map +1 -0
  88. package/dist/lib/references.js +28 -0
  89. package/dist/operations.gen.d.ts +2 -2
  90. package/dist/operations.gen.js +301 -301
  91. package/package.json +8 -5
@@ -0,0 +1,528 @@
1
+ // src/lib/custom/sql/inspect/queries.ts
2
+ /**
3
+ * Every available check, in the order they are offered to the model. Declared as
4
+ * a tuple so it can back a Zod enum directly, which keeps the tool's input
5
+ * schema and this catalog from drifting apart.
6
+ */
7
+ const INSPECT_CHECKS = [
8
+ "table-sizes",
9
+ "index-sizes",
10
+ "unused-indexes",
11
+ "seq-scans",
12
+ "long-running-queries",
13
+ "stalled-queries",
14
+ "locks",
15
+ "outliers",
16
+ "calls",
17
+ "lfc-hit-rate",
18
+ "working-set",
19
+ "vacuum-stats",
20
+ "bloat",
21
+ "replication-slots",
22
+ "subscriptions"
23
+ ];
24
+ /**
25
+ * Typed as an exact `Record` so adding a check to `INSPECT_CHECKS` without
26
+ * writing its query is a compile error.
27
+ */
28
+ const INSPECT_QUERIES = {
29
+ "table-sizes": {
30
+ describe: "Size of each table (including TOAST), largest first (pg_table_size)",
31
+ scope: "database",
32
+ fields: [
33
+ "schema",
34
+ "name",
35
+ "size"
36
+ ],
37
+ emptyMessage: "No user tables found.",
38
+ sql: `
39
+ SELECT
40
+ n.nspname AS schema,
41
+ c.relname AS name,
42
+ pg_size_pretty(pg_table_size(c.oid)) AS size
43
+ FROM pg_class c
44
+ LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
45
+ WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
46
+ AND n.nspname !~ '^pg_toast'
47
+ AND c.relkind = 'r'
48
+ ORDER BY pg_table_size(c.oid) DESC;
49
+ `
50
+ },
51
+ "index-sizes": {
52
+ describe: "Size of each index, largest first (pg_relation_size)",
53
+ scope: "database",
54
+ fields: [
55
+ "schema",
56
+ "name",
57
+ "size"
58
+ ],
59
+ emptyMessage: "No indexes found.",
60
+ sql: `
61
+ SELECT
62
+ n.nspname AS schema,
63
+ c.relname AS name,
64
+ pg_size_pretty(pg_relation_size(c.oid)) AS size
65
+ FROM pg_class c
66
+ LEFT JOIN pg_namespace n ON n.oid = c.relnamespace
67
+ WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
68
+ AND n.nspname !~ '^pg_toast'
69
+ AND c.relkind = 'i'
70
+ ORDER BY pg_relation_size(c.oid) DESC;
71
+ `
72
+ },
73
+ "unused-indexes": {
74
+ describe: "Non-unique indexes with fewer than 50 scans — candidates for removal (pg_stat_user_indexes)",
75
+ scope: "database",
76
+ fields: [
77
+ "table",
78
+ "index",
79
+ "index_size",
80
+ "index_scans"
81
+ ],
82
+ emptyMessage: "No unused indexes detected.",
83
+ sql: `
84
+ SELECT
85
+ s.schemaname || '.' || s.relname AS "table",
86
+ s.indexrelname AS index,
87
+ pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size,
88
+ s.idx_scan AS index_scans
89
+ FROM pg_stat_user_indexes s
90
+ JOIN pg_index i ON i.indexrelid = s.indexrelid
91
+ WHERE NOT i.indisunique
92
+ AND NOT i.indisprimary
93
+ AND s.idx_scan < 50
94
+ ORDER BY pg_relation_size(s.indexrelid) DESC, s.idx_scan ASC;
95
+ `
96
+ },
97
+ "seq-scans": {
98
+ describe: "Number of sequential scans recorded against each table (pg_stat_user_tables)",
99
+ scope: "database",
100
+ fields: [
101
+ "schema",
102
+ "name",
103
+ "count"
104
+ ],
105
+ emptyMessage: "No user tables found.",
106
+ sql: `
107
+ SELECT
108
+ schemaname AS schema,
109
+ relname AS name,
110
+ seq_scan AS count
111
+ FROM pg_stat_user_tables
112
+ ORDER BY seq_scan DESC;
113
+ `
114
+ },
115
+ "long-running-queries": {
116
+ describe: "Queries running longer than 5 minutes (pg_stat_activity)",
117
+ scope: "database",
118
+ fields: [
119
+ "pid",
120
+ "duration",
121
+ "state",
122
+ "query"
123
+ ],
124
+ emptyMessage: "No long-running queries in this database.",
125
+ emptyMessageAll: "No long-running queries in any database.",
126
+ sql: `
127
+ SELECT
128
+ pid,
129
+ (now() - query_start)::text AS duration,
130
+ state,
131
+ query
132
+ FROM pg_stat_activity
133
+ WHERE datname = current_database()
134
+ AND state <> 'idle'
135
+ AND query NOT ILIKE '%pg_stat_activity%'
136
+ AND now() - query_start > interval '5 minutes'
137
+ ORDER BY now() - query_start DESC;
138
+ `
139
+ },
140
+ "stalled-queries": {
141
+ describe: "Active queries running longer than 30 seconds with parallel-worker grouping, waits, and blockers, oldest query group first (compute-wide)",
142
+ scope: "compute",
143
+ fields: [
144
+ "observed_at",
145
+ "query_start",
146
+ "query_group",
147
+ "pid",
148
+ "leader_pid",
149
+ "role",
150
+ "backend_type",
151
+ "database",
152
+ "application_name",
153
+ "query_id",
154
+ "state",
155
+ "wait_event_type",
156
+ "wait_event",
157
+ "blocking_pids",
158
+ "duration",
159
+ "query"
160
+ ],
161
+ emptyMessage: "No active queries running longer than 30 seconds on this compute.",
162
+ sql: `
163
+ WITH activity AS MATERIALIZED (
164
+ SELECT *
165
+ FROM pg_stat_activity
166
+ WHERE state = 'active'
167
+ AND backend_type IN ('client backend', 'parallel worker')
168
+ AND pid <> pg_backend_pid()
169
+ ),
170
+ stalled_groups AS (
171
+ SELECT
172
+ COALESCE(leader_pid, pid) AS query_group,
173
+ min(query_start) AS group_start
174
+ FROM activity
175
+ WHERE query_start <= statement_timestamp() - interval '30 seconds'
176
+ GROUP BY COALESCE(leader_pid, pid)
177
+ )
178
+ SELECT
179
+ statement_timestamp() AS observed_at,
180
+ a.query_start,
181
+ g.query_group,
182
+ a.pid,
183
+ a.leader_pid,
184
+ CASE
185
+ WHEN a.leader_pid IS NULL THEN 'leader'
186
+ ELSE 'worker'
187
+ END AS role,
188
+ a.backend_type,
189
+ a.datname AS database,
190
+ a.application_name,
191
+ a.query_id::text AS query_id,
192
+ a.state,
193
+ a.wait_event_type,
194
+ a.wait_event,
195
+ array_to_string(pg_blocking_pids(a.pid), ',') AS blocking_pids,
196
+ (statement_timestamp() - a.query_start)::text AS duration,
197
+ a.query
198
+ FROM activity a
199
+ JOIN stalled_groups g
200
+ ON g.query_group = COALESCE(a.leader_pid, a.pid)
201
+ ORDER BY g.group_start, g.query_group, a.leader_pid NULLS FIRST, a.pid;
202
+ `
203
+ },
204
+ locks: {
205
+ describe: "Locks held with the acquiring query and its age (pg_locks + pg_stat_activity)",
206
+ scope: "database",
207
+ fields: [
208
+ "pid",
209
+ "relname",
210
+ "mode",
211
+ "locktype",
212
+ "granted",
213
+ "age",
214
+ "query"
215
+ ],
216
+ emptyMessage: "No locks held in this database.",
217
+ emptyMessageAll: "No locks held in any database.",
218
+ sql: `
219
+ SELECT
220
+ a.pid,
221
+ c.relname,
222
+ l.mode,
223
+ l.locktype,
224
+ l.granted,
225
+ (now() - a.query_start)::text AS age,
226
+ a.query
227
+ FROM pg_locks l
228
+ JOIN pg_stat_activity a ON a.pid = l.pid
229
+ LEFT JOIN pg_class c ON c.oid = l.relation
230
+ WHERE a.datname = current_database()
231
+ AND a.query <> '<insufficient privilege>'
232
+ AND l.pid <> pg_backend_pid()
233
+ ORDER BY a.query_start;
234
+ `
235
+ },
236
+ outliers: {
237
+ describe: "The 25 queries with the highest cumulative execution time since statistics were last reset (needs pg_stat_statements)",
238
+ scope: "database",
239
+ fields: [
240
+ "total_exec_time",
241
+ "prop_exec_time",
242
+ "ncalls",
243
+ "query"
244
+ ],
245
+ emptyMessage: "No statements recorded yet.",
246
+ sqlLimit: 25,
247
+ requiresExtension: "pg_stat_statements",
248
+ sql: `
249
+ SELECT
250
+ (interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
251
+ to_char(
252
+ (total_exec_time / nullif(sum(total_exec_time) OVER (), 0)) * 100,
253
+ 'FM990D0'
254
+ ) || '%' AS prop_exec_time,
255
+ calls AS ncalls,
256
+ query
257
+ FROM pg_stat_statements s
258
+ JOIN pg_database d ON d.oid = s.dbid
259
+ WHERE d.datname = current_database()
260
+ ORDER BY total_exec_time DESC
261
+ LIMIT 25;
262
+ `
263
+ },
264
+ calls: {
265
+ describe: "The 25 most frequently executed queries since statistics were last reset (needs pg_stat_statements)",
266
+ scope: "database",
267
+ fields: [
268
+ "ncalls",
269
+ "total_exec_time",
270
+ "prop_exec_time",
271
+ "query"
272
+ ],
273
+ emptyMessage: "No statements recorded yet.",
274
+ sqlLimit: 25,
275
+ requiresExtension: "pg_stat_statements",
276
+ sql: `
277
+ SELECT
278
+ calls AS ncalls,
279
+ (interval '1 millisecond' * total_exec_time)::text AS total_exec_time,
280
+ to_char(
281
+ (calls / nullif(sum(calls) OVER (), 0)::float) * 100,
282
+ 'FM990D0'
283
+ ) || '%' AS prop_exec_time,
284
+ query
285
+ FROM pg_stat_statements s
286
+ JOIN pg_database d ON d.oid = s.dbid
287
+ WHERE d.datname = current_database()
288
+ ORDER BY calls DESC
289
+ LIMIT 25;
290
+ `
291
+ },
292
+ "lfc-hit-rate": {
293
+ describe: "Local File Cache hit rate (compute-wide, needs neon extension)",
294
+ scope: "compute",
295
+ fields: ["name", "ratio"],
296
+ emptyMessage: "No LFC stats available.",
297
+ requiresExtension: "neon",
298
+ sql: `
299
+ WITH lfc AS (
300
+ SELECT lfc_key AS k, lfc_value AS v
301
+ FROM neon_get_lfc_stats() t(lfc_key text, lfc_value bigint)
302
+ )
303
+ SELECT
304
+ 'lfc hit rate' AS name,
305
+ max(v) FILTER (WHERE k = 'file_cache_hits')::float
306
+ / nullif(
307
+ max(v) FILTER (WHERE k = 'file_cache_hits')
308
+ + max(v) FILTER (WHERE k = 'file_cache_misses'),
309
+ 0
310
+ ) AS ratio
311
+ FROM lfc;
312
+ `
313
+ },
314
+ "working-set": {
315
+ describe: "Estimated working set vs LFC size (compute-wide, needs neon extension)",
316
+ scope: "compute",
317
+ fields: [
318
+ "window",
319
+ "working_set",
320
+ "lfc_size",
321
+ "exceeds_lfc"
322
+ ],
323
+ emptyMessage: "No working-set estimate available.",
324
+ requiresExtension: "neon",
325
+ sql: `
326
+ SELECT
327
+ w.window,
328
+ pg_size_pretty(w.working_set_bytes) AS working_set,
329
+ pg_size_pretty(pg_size_bytes(current_setting('neon.file_cache_size_limit'))) AS lfc_size,
330
+ CASE
331
+ WHEN w.working_set_bytes
332
+ > pg_size_bytes(current_setting('neon.file_cache_size_limit'))
333
+ THEN 'yes' ELSE 'no'
334
+ END AS exceeds_lfc
335
+ FROM (
336
+ SELECT
337
+ x AS window,
338
+ approximate_working_set_size_seconds(
339
+ extract('epoch' from x::interval)::int
340
+ )::bigint * 8192 AS working_set_bytes
341
+ FROM (VALUES ('1m'), ('5m'), ('15m'), ('1h')) AS t(x)
342
+ ) w
343
+ ORDER BY working_set_bytes;
344
+ `
345
+ },
346
+ "vacuum-stats": {
347
+ describe: "Autovacuum status per table: last (auto)vacuum, dead tuples, threshold",
348
+ scope: "database",
349
+ fields: [
350
+ "schema",
351
+ "table",
352
+ "last_vacuum",
353
+ "last_autovacuum",
354
+ "rowcount",
355
+ "dead_rowcount",
356
+ "expect_autovacuum"
357
+ ],
358
+ emptyMessage: "No user tables found.",
359
+ sql: `
360
+ SELECT
361
+ n.nspname AS schema,
362
+ c.relname AS "table",
363
+ to_char(psut.last_vacuum, 'YYYY-MM-DD HH24:MI') AS last_vacuum,
364
+ to_char(psut.last_autovacuum, 'YYYY-MM-DD HH24:MI') AS last_autovacuum,
365
+ c.reltuples::bigint AS rowcount,
366
+ psut.n_dead_tup AS dead_rowcount,
367
+ CASE
368
+ WHEN current_setting('autovacuum_vacuum_threshold')::bigint
369
+ + current_setting('autovacuum_vacuum_scale_factor')::numeric
370
+ * c.reltuples
371
+ < psut.n_dead_tup
372
+ THEN 'yes'
373
+ ELSE 'no'
374
+ END AS expect_autovacuum
375
+ FROM pg_stat_user_tables psut
376
+ JOIN pg_class c ON psut.relid = c.oid
377
+ JOIN pg_namespace n ON c.relnamespace = n.oid
378
+ ORDER BY psut.n_dead_tup DESC;
379
+ `
380
+ },
381
+ bloat: {
382
+ describe: "Estimated bloat for the 25 most bloated tables (statistical estimate, no extension needed)",
383
+ scope: "database",
384
+ fields: [
385
+ "type",
386
+ "schema",
387
+ "object_name",
388
+ "bloat",
389
+ "waste"
390
+ ],
391
+ emptyMessage: "No bloat estimate available.",
392
+ sqlLimit: 25,
393
+ sql: `
394
+ WITH constants AS (
395
+ SELECT current_setting('block_size')::numeric AS bs, 23 AS hdr, 8 AS ma
396
+ ),
397
+ bloat_info AS (
398
+ SELECT
399
+ ma, bs, schemaname, tablename,
400
+ (datawidth + (hdr + ma - (CASE WHEN hdr % ma = 0 THEN ma ELSE hdr % ma END)))::numeric AS datahdr,
401
+ (maxfracsum * (nullhdr + ma - (CASE WHEN nullhdr % ma = 0 THEN ma ELSE nullhdr % ma END))) AS nullhdr2
402
+ FROM (
403
+ SELECT
404
+ schemaname, tablename, hdr, ma, bs,
405
+ SUM((1 - null_frac) * avg_width) AS datawidth,
406
+ MAX(null_frac) AS maxfracsum,
407
+ hdr + (
408
+ SELECT 1 + count(*) / 8
409
+ FROM pg_stats s2
410
+ WHERE null_frac <> 0
411
+ AND s2.schemaname = s.schemaname
412
+ AND s2.tablename = s.tablename
413
+ ) AS nullhdr
414
+ FROM pg_stats s, constants
415
+ GROUP BY 1, 2, 3, 4, 5
416
+ ) AS foo
417
+ ),
418
+ table_bloat AS (
419
+ SELECT
420
+ schemaname, tablename, cc.relpages, bs,
421
+ CEIL((cc.reltuples * ((datahdr + ma
422
+ - (CASE WHEN datahdr % ma = 0 THEN ma ELSE datahdr % ma END))
423
+ + nullhdr2 + 4)) / (bs - 20::float)) AS otta
424
+ FROM bloat_info
425
+ JOIN pg_class cc ON cc.relname = bloat_info.tablename
426
+ JOIN pg_namespace nn ON cc.relnamespace = nn.oid
427
+ AND nn.nspname = bloat_info.schemaname
428
+ AND nn.nspname NOT IN ('information_schema', 'pg_catalog')
429
+ WHERE cc.relkind = 'r'
430
+ )
431
+ SELECT
432
+ 'table' AS type,
433
+ schemaname AS schema,
434
+ tablename AS object_name,
435
+ round(CASE WHEN otta = 0 THEN 0.0 ELSE relpages::numeric / otta::numeric END, 1) AS bloat,
436
+ pg_size_pretty(
437
+ (CASE WHEN relpages < otta THEN 0 ELSE (bs * (relpages - otta))::bigint END)
438
+ ) AS waste
439
+ FROM table_bloat
440
+ ORDER BY (CASE WHEN relpages < otta THEN 0 ELSE bs * (relpages - otta) END) DESC
441
+ LIMIT 25;
442
+ `
443
+ },
444
+ "replication-slots": {
445
+ describe: "Replication slots (compute-wide): kind, status, client, restart/confirmed-flush LSNs, and lag (pg_replication_slots + pg_stat_replication)",
446
+ scope: "compute",
447
+ fields: [
448
+ "slot_name",
449
+ "slot_type",
450
+ "slot_kind",
451
+ "status",
452
+ "client_addr",
453
+ "restart_lsn",
454
+ "confirmed_flush_lsn",
455
+ "replication_lag"
456
+ ],
457
+ emptyMessage: "No replication slots found.",
458
+ sql: `
459
+ SELECT
460
+ s.slot_name,
461
+ s.slot_type,
462
+ CASE
463
+ WHEN s.slot_type = 'physical' THEN 'physical'
464
+ WHEN s.slot_name LIKE 'pg_%_sync_%' THEN 'initial-sync (tablesync)'
465
+ WHEN s.slot_type = 'logical' THEN 'CDC (apply)'
466
+ ELSE 'other'
467
+ END AS slot_kind,
468
+ CASE
469
+ WHEN r.state IS NOT NULL THEN r.state
470
+ WHEN s.active THEN 'active (no walsender)'
471
+ ELSE 'inactive'
472
+ END AS status,
473
+ r.client_addr,
474
+ s.restart_lsn,
475
+ s.confirmed_flush_lsn,
476
+ pg_size_pretty(
477
+ pg_wal_lsn_diff(
478
+ CASE
479
+ WHEN pg_is_in_recovery() THEN pg_last_wal_receive_lsn()
480
+ ELSE pg_current_wal_lsn()
481
+ END,
482
+ COALESCE(s.confirmed_flush_lsn, s.restart_lsn)
483
+ )
484
+ ) AS replication_lag
485
+ FROM pg_replication_slots s
486
+ LEFT JOIN pg_stat_replication r ON r.pid = s.active_pid
487
+ ORDER BY s.slot_name;
488
+ `
489
+ },
490
+ subscriptions: {
491
+ describe: "Per-table logical replication progress on this subscriber (pg_subscription_rel)",
492
+ scope: "database",
493
+ fields: [
494
+ "subscription",
495
+ "table_name",
496
+ "status",
497
+ "lsn"
498
+ ],
499
+ emptyMessage: "No subscriptions found on this database.",
500
+ emptyMessageAll: "No subscriptions found on any database.",
501
+ sql: `
502
+ SELECT
503
+ sub.subname AS subscription,
504
+ sr.srrelid::regclass::text AS table_name,
505
+ CASE sr.srsubstate
506
+ WHEN 'i' THEN 'initialize'
507
+ WHEN 'd' THEN 'data being copied'
508
+ WHEN 'f' THEN 'finished table copy'
509
+ WHEN 's' THEN 'synchronized'
510
+ WHEN 'r' THEN 'ready'
511
+ ELSE sr.srsubstate::text
512
+ END AS status,
513
+ sr.srsublsn AS lsn
514
+ FROM pg_subscription_rel sr
515
+ JOIN pg_subscription sub ON sub.oid = sr.srsubid
516
+ ORDER BY sub.subname, table_name;
517
+ `
518
+ }
519
+ };
520
+ /**
521
+ * Rows returned per call unless the caller raises it. Diagnostics like
522
+ * `table-sizes` are unbounded in SQL, and a few thousand rows would crowd out the
523
+ * model's context, so the handler caps the response and reports the full count.
524
+ */
525
+ const INSPECT_DEFAULT_LIMIT = 50;
526
+ /** Ceiling on `limit`, so a diagnostic can never return an unbounded response. */
527
+ const INSPECT_MAX_LIMIT = 1e3;
528
+ export { INSPECT_CHECKS, INSPECT_DEFAULT_LIMIT, INSPECT_MAX_LIMIT, INSPECT_QUERIES };
@@ -0,0 +1,31 @@
1
+ import { type InspectCheck, type InspectQuery } from "./queries.js";
2
+ export type InspectDatabaseBatch = {
3
+ database: string;
4
+ rows: Record<string, unknown>[];
5
+ };
6
+ export type InspectDatabaseResult = {
7
+ check: InspectCheck;
8
+ describe: string;
9
+ projectId: string;
10
+ branchId: string;
11
+ databaseName?: string;
12
+ databases: string[];
13
+ fields: readonly string[];
14
+ totalRowCount: number;
15
+ rows: Record<string, unknown>[];
16
+ truncated: boolean;
17
+ note?: string;
18
+ };
19
+ type AssembleInspectReportInput = {
20
+ check: InspectCheck;
21
+ query: InspectQuery;
22
+ projectId: string;
23
+ branchId: string;
24
+ batches: InspectDatabaseBatch[];
25
+ includeDatabaseColumn: boolean;
26
+ includeDatabaseName: boolean;
27
+ limit: number;
28
+ };
29
+ export declare function assembleInspectReport({ check, query, projectId, branchId, batches, includeDatabaseColumn, includeDatabaseName, limit, }: AssembleInspectReportInput): InspectDatabaseResult;
30
+ export {};
31
+ //# sourceMappingURL=report.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../../../src/lib/custom/sql/inspect/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,0BAA0B,GAAG;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAuCF,wBAAgB,qBAAqB,CAAC,EACrC,KAAK,EACL,KAAK,EACL,SAAS,EACT,QAAQ,EACR,OAAO,EACP,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,GACL,EAAE,0BAA0B,GAAG,qBAAqB,CAwDpD"}
@@ -0,0 +1,43 @@
1
+ import "./queries.js";
2
+ // src/lib/custom/sql/inspect/report.ts
3
+ function databasesIn(rows) {
4
+ const names = [];
5
+ for (const row of rows) if (typeof row.database === "string" && !names.includes(row.database)) names.push(row.database);
6
+ return names;
7
+ }
8
+ function truncationNote(displayed, totalRowCount, limit, includeDatabaseColumn, ran, allRows) {
9
+ if ((includeDatabaseColumn ? databasesIn(allRows).filter((name) => !databasesIn(displayed).includes(name)) : []).length > 0) return `Showing the first ${limit} of ${totalRowCount} rows, which cover only the databases ${databasesIn(displayed).join(", ")} (of ${ran.length}). ${limit < 1e3 ? "Raise `limit` to reach the rest." : "Narrow the question with your own SQL to see the rest."}`;
10
+ if (limit < 1e3) return `Showing the first ${limit} of ${totalRowCount} rows. Raise \`limit\` to see more.`;
11
+ return `Showing the first ${limit} of ${totalRowCount} rows, which is the maximum this tool returns. Narrow the question with your own SQL to see the rest.`;
12
+ }
13
+ function assembleInspectReport({ check, query, projectId, branchId, batches, includeDatabaseColumn, includeDatabaseName, limit }) {
14
+ const databases = batches.map((batch) => batch.database);
15
+ const rows = includeDatabaseColumn ? batches.flatMap((batch) => batch.rows.map((row) => ({
16
+ database: batch.database,
17
+ ...row
18
+ }))) : batches.flatMap((batch) => batch.rows);
19
+ const fields = includeDatabaseColumn ? ["database", ...query.fields] : query.fields;
20
+ const truncated = rows.length > limit;
21
+ const displayed = truncated ? rows.slice(0, limit) : rows;
22
+ let note;
23
+ if (rows.length === 0) note = includeDatabaseColumn ? query.emptyMessageAll ?? query.emptyMessage : query.emptyMessage;
24
+ else if (truncated) note = truncationNote(displayed, rows.length, limit, includeDatabaseColumn, databases, rows);
25
+ if (query.sqlLimit !== void 0 && batches.some((batch) => batch.rows.length === query.sqlLimit)) {
26
+ const sqlCapNote = includeDatabaseColumn ? `The \`${check}\` check returns at most ${query.sqlLimit} rows per database, and at least one database hit that cap, so there may be more. Run your own SQL for the full ranking.` : `The \`${check}\` check returns at most ${query.sqlLimit} rows, and hit that cap, so there may be more. Run your own SQL for the full ranking.`;
27
+ note = note === void 0 ? sqlCapNote : `${note} ${sqlCapNote}`;
28
+ }
29
+ return {
30
+ check,
31
+ describe: query.describe,
32
+ projectId,
33
+ branchId,
34
+ ...includeDatabaseName && query.scope === "database" ? { databaseName: databases[0] } : {},
35
+ databases,
36
+ fields,
37
+ totalRowCount: rows.length,
38
+ rows: displayed,
39
+ truncated,
40
+ ...note !== void 0 && { note }
41
+ };
42
+ }
43
+ export { assembleInspectReport };
@@ -0,0 +1,27 @@
1
+ export type InspectQueryScope = "database" | "compute";
2
+ type InspectTargetSelection = {
3
+ databases: string[];
4
+ includeDatabaseColumn: boolean;
5
+ };
6
+ type SelectInspectTargetsInput = {
7
+ databaseName?: string;
8
+ branchDatabases: readonly string[];
9
+ scope: InspectQueryScope;
10
+ };
11
+ /**
12
+ * Keep the database column on one-database branches so adding another database
13
+ * does not change the output schema. Compute-wide views run once because every
14
+ * database returns the same rows.
15
+ */
16
+ export declare const selectInspectTargets: (input: SelectInspectTargetsInput) => InspectTargetSelection;
17
+ type FormatInspectQueryErrorInput = {
18
+ reason: string;
19
+ database: string;
20
+ databaseName?: string;
21
+ offerDatabaseNameHint: boolean;
22
+ scope: InspectQueryScope;
23
+ requiresExtension?: string;
24
+ };
25
+ export declare const formatInspectQueryError: (input: FormatInspectQueryErrorInput) => string | undefined;
26
+ export {};
27
+ //# sourceMappingURL=targets.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"targets.d.ts","sourceRoot":"","sources":["../../../../../src/lib/custom/sql/inspect/targets.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvD,KAAK,sBAAsB,GAAG;IAC7B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,qBAAqB,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,KAAK,yBAAyB,GAAG;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,KAAK,EAAE,iBAAiB,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAChC,OAAO,yBAAyB,KAC9B,sBAyBF,CAAC;AAEF,KAAK,4BAA4B,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,KAAK,EAAE,iBAAiB,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,uBAAuB,GACnC,OAAO,4BAA4B,KACjC,MAAM,GAAG,SAuBX,CAAC"}
@@ -0,0 +1,33 @@
1
+ import { NeonClientError } from "@neon/sdk";
2
+ // src/lib/custom/sql/inspect/targets.ts
3
+ /**
4
+ * Keep the database column on one-database branches so adding another database
5
+ * does not change the output schema. Compute-wide views run once because every
6
+ * database returns the same rows.
7
+ */
8
+ const selectInspectTargets = (input) => {
9
+ if (input.databaseName !== void 0) {
10
+ if (input.databaseName === "") throw new NeonClientError("database_name cannot be empty. Omit it to cover every database.");
11
+ return {
12
+ databases: [input.databaseName],
13
+ includeDatabaseColumn: false
14
+ };
15
+ }
16
+ if (input.branchDatabases.length === 0) throw new NeonClientError("No databases found for the branch");
17
+ if (input.scope === "compute") return {
18
+ databases: [input.branchDatabases[0]],
19
+ includeDatabaseColumn: false
20
+ };
21
+ return {
22
+ databases: [...input.branchDatabases].sort((a, b) => a.localeCompare(b, "en")),
23
+ includeDatabaseColumn: true
24
+ };
25
+ };
26
+ const formatInspectQueryError = (input) => {
27
+ if (input.databaseName !== void 0) return;
28
+ const missingExtension = input.requiresExtension !== void 0 && input.reason.includes(`"${input.requiresExtension}"`);
29
+ const hint = !input.offerDatabaseNameHint ? "" : missingExtension ? `. Pass database_name to try a database that already has the "${input.requiresExtension}" extension.` : input.scope === "compute" ? ". Pass database_name to connect through a different database." : ". Pass database_name to inspect one database.";
30
+ const tagged = input.reason.includes(`database "${input.database}"`) ? input.reason : `${input.reason} (database ${input.database})`;
31
+ return `${tagged}${hint.startsWith(".") && tagged.endsWith(".") ? hint.slice(1) : hint}`;
32
+ };
33
+ export { formatInspectQueryError, selectInspectTargets };