postgresai 0.14.0-dev.76 → 0.14.0-dev.78

package/bin/postgres-ai.ts

@@ -20,6 +20,7 @@ import { maskSecret } from "../lib/util";
 import { createInterface } from "readline";
 import * as childProcess from "child_process";
 import { REPORT_GENERATORS, CHECK_INFO, generateAllReports } from "../lib/checkup";
+import { getAllCheckupEntries, getCheckupEntry, isValidCheckupCode } from "../lib/checkup-dictionary";
 import { createCheckupReport, uploadCheckupReportJson, RpcError, formatRpcErrorForDisplay, withRetry } from "../lib/checkup-api";
 
 // Singleton readline interface for stdin prompts
@@ -1641,10 +1642,18 @@ program
     }
   });
 
+// Build help text showing all checks from dictionary with express-mode indicators
+const expressCheckIds = new Set(Object.keys(REPORT_GENERATORS));
+const allChecks = getAllCheckupEntries();
+const checkHelpLines = allChecks.map((entry) => {
+  const isExpress = expressCheckIds.has(entry.code);
+  return `  ${entry.code}: ${entry.title}${isExpress ? "" : " (*)"}`;
+});
+
 program
   .command("checkup [conn]")
   .description("generate health check reports directly from PostgreSQL (express mode)")
-  .option("--check-id <id>", `specific check to run: ${Object.keys(CHECK_INFO).join(", ")}, or ALL`, "ALL")
+  .option("--check-id <id>", `specific check to run (see list below), or ALL`, "ALL")
   .option("--node-name <name>", "node name for reports", "node-01")
   .option("--output <path>", "output directory for JSON files")
   .option("--[no-]upload", "upload JSON results to PostgresAI (default: enabled; requires API key)", undefined)
@@ -1658,7 +1667,10 @@ program
     [
       "",
       "Available checks:",
-      ...Object.entries(CHECK_INFO).map(([id, title]) => `  ${id}: ${title}`),
+      ...checkHelpLines,
+      "",
+      "  (*) = not yet available in express mode (coming soon)",
+      "  ALL = run all express-mode checks",
       "",
       "Examples:",
       "  postgresai checkup postgresql://user:pass@host:5432/db",
@@ -1725,8 +1737,16 @@ program
         const generator = REPORT_GENERATORS[checkId];
         if (!generator) {
           spinner.stop();
-          console.error(`Unknown check ID: ${opts.checkId}`);
-          console.error(`Available: ${Object.keys(CHECK_INFO).join(", ")}, ALL`);
+          // Check if it's a valid check ID from the dictionary (just not implemented in express mode)
+          const dictEntry = getCheckupEntry(checkId);
+          if (dictEntry) {
+            console.error(`Check ${checkId} (${dictEntry.title}) is not yet available in express mode.`);
+            console.error(`Express-mode checks: ${Object.keys(CHECK_INFO).join(", ")}`);
+            console.error(`\nFull checkup reports are available at: https://postgres.ai/checkup`);
+          } else {
+            console.error(`Unknown check ID: ${opts.checkId}`);
+            console.error(`See 'postgresai checkup --help' for available checks.`);
+          }
           process.exitCode = 1;
           return;
         }

package/dist/bin/postgres-ai.js

@@ -13064,7 +13064,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.14.0-dev.76",
+  version: "0.14.0-dev.78",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -13090,15 +13090,17 @@ var package_default = {
   },
   scripts: {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
-    build: `bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
+    "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
+    "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
+    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
-    dev: "bun run embed-metrics && bun --watch ./bin/postgres-ai.ts",
-    test: "bun run embed-metrics && bun test",
-    "test:fast": "bun run embed-metrics && bun test --coverage=false",
-    "test:coverage": "bun run embed-metrics && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
-    typecheck: "bun run embed-metrics && bunx tsc --noEmit"
+    dev: "bun run embed-all && bun --watch ./bin/postgres-ai.ts",
+    test: "bun run embed-all && bun test",
+    "test:fast": "bun run embed-all && bun test",
+    "test:coverage": "bun run embed-all && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
+    typecheck: "bun run embed-all && bunx tsc --noEmit"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.20.2",
@@ -15887,7 +15889,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.14.0-dev.76";
+var version = "0.14.0-dev.78";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -15916,15 +15918,17 @@ var package_default2 = {
   },
   scripts: {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
-    build: `bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
+    "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
+    "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
+    build: `bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e "const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))" && cp -r ./sql ./dist/sql`,
     prepublishOnly: "npm run build",
     start: "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
-    dev: "bun run embed-metrics && bun --watch ./bin/postgres-ai.ts",
-    test: "bun run embed-metrics && bun test",
-    "test:fast": "bun run embed-metrics && bun test --coverage=false",
-    "test:coverage": "bun run embed-metrics && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
-    typecheck: "bun run embed-metrics && bunx tsc --noEmit"
+    dev: "bun run embed-all && bun --watch ./bin/postgres-ai.ts",
+    test: "bun run embed-all && bun test",
+    "test:fast": "bun run embed-all && bun test",
+    "test:coverage": "bun run embed-all && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
+    typecheck: "bun run embed-all && bunx tsc --noEmit"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.20.2",
@@ -26542,6 +26546,572 @@ function transformMetricRow(row) {
   return result;
 }
 
+// lib/checkup-dictionary-embedded.ts
+var CHECKUP_DICTIONARY_DATA = [
+  {
+    code: "A001",
+    title: "System information",
+    description: "OS, kernel, hardware details",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A002",
+    title: "Postgres major version",
+    description: "Major version and end-of-life status",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A003",
+    title: "Postgres settings",
+    description: "Full list of current settings",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A004",
+    title: "Cluster information",
+    description: "Data directory, cluster name, system identifier",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A005",
+    title: "Extensions",
+    description: "Installed and available extensions",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A006",
+    title: "Postgres setting deviations",
+    description: "Settings that differ from defaults",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A007",
+    title: "Altered settings",
+    description: "Settings changed via ALTER SYSTEM or per-user/database",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A008",
+    title: "Disk usage and file system type",
+    description: "Disk space, mount points, filesystem types",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A009",
+    title: "Tablespaces",
+    description: "Tablespace locations and usage",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A010",
+    title: "Corruption control",
+    description: "Checksums, wal_log_hints, backup safety",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A011",
+    title: "Connection management and pooling",
+    description: "Connection limits and pooler detection",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A012",
+    title: "Anti-crash checks",
+    description: "fsync, full_page_writes, synchronous_commit",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "A013",
+    title: "Postgres minor version",
+    description: "Minor version and available updates",
+    category: "system",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "B001",
+    title: "SLO/SLA, RPO, RTO",
+    description: "Recovery objectives and current capabilities",
+    category: "backup",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "B002",
+    title: "File system and mount flags",
+    description: "Mount options affecting durability",
+    category: "backup",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "B003",
+    title: "Full and incremental backups",
+    description: "Backup tooling and schedule",
+    category: "backup",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "B004",
+    title: "WAL archiving",
+    description: "Archive configuration and status",
+    category: "backup",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "B005",
+    title: "Backup restore testing and monitoring",
+    description: "Restore testing practices and alerting",
+    category: "backup",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "C001",
+    title: "SLO/SLA",
+    description: "Availability objectives",
+    category: "replication",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "C002",
+    title: "Replication mode and method",
+    description: "Sync/async, streaming/WAL shipping",
+    category: "replication",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "C003",
+    title: "Single points of failure",
+    description: "SPOF analysis",
+    category: "replication",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "C004",
+    title: "Failover",
+    description: "Failover mechanism and automation",
+    category: "replication",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "C005",
+    title: "Switchover",
+    description: "Planned switchover procedures",
+    category: "replication",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "C006",
+    title: "Delayed replica",
+    description: "Delayed standby configuration",
+    category: "replication",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "C007",
+    title: "Replication slots and lag",
+    description: "Slot status, lag, standby feedback",
+    category: "replication",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "D001",
+    title: "Logging settings",
+    description: "Log destination, verbosity, rotation",
+    category: "monitoring",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "D002",
+    title: "Useful Linux tools",
+    description: "Recommended OS-level tooling",
+    category: "monitoring",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "D003",
+    title: "Monitoring metrics",
+    description: "Key metrics to track",
+    category: "monitoring",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "D004",
+    title: "pg_stat_statements and pg_stat_kcache",
+    description: "Query stats extension settings",
+    category: "monitoring",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "D005",
+    title: "track_io_timing and auto_explain",
+    description: "I/O timing and plan logging",
+    category: "monitoring",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "D006",
+    title: "Recommended DBA toolsets",
+    description: "Useful third-party tools",
+    category: "monitoring",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "D007",
+    title: "Postgres troubleshooting tools",
+    description: "Built-in and ecosystem diagnostic tools",
+    category: "monitoring",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "E001",
+    title: "WAL and checkpoint settings",
+    description: "WAL size, checkpoint timing, I/O limits",
+    category: "wal",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "E002",
+    title: "Checkpoint and bgwriter activity",
+    description: "Checkpoint frequency, bgwriter stats",
+    category: "wal",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F001",
+    title: "Autovacuum: current settings",
+    description: "Autovacuum configuration",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F002",
+    title: "Autovacuum: transaction ID wraparound",
+    description: "XID age and wraparound risk",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F003",
+    title: "Autovacuum: dead tuples",
+    description: "Dead tuple counts and cleanup status",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F004",
+    title: "Autovacuum: heap bloat estimate",
+    description: "Estimated table bloat",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F005",
+    title: "Autovacuum: index bloat estimate",
+    description: "Estimated index bloat",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F006",
+    title: "Precise heap bloat analysis",
+    description: "Detailed table bloat measurement",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F007",
+    title: "Precise index bloat analysis",
+    description: "Detailed index bloat measurement",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "F008",
+    title: "Autovacuum: resource usage",
+    description: "Autovacuum I/O and CPU impact",
+    category: "vacuum",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "G001",
+    title: "Memory-related settings",
+    description: "shared_buffers, work_mem, maintenance_work_mem",
+    category: "tuning",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "G002",
+    title: "Connections and current activity",
+    description: "Connection usage and active sessions",
+    category: "tuning",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "G003",
+    title: "Timeouts, locks, deadlocks",
+    description: "Lock settings and deadlock stats",
+    category: "tuning",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "G004",
+    title: "Query planner settings",
+    description: "Planner cost and behavior settings",
+    category: "tuning",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "G005",
+    title: "I/O settings",
+    description: "effective_io_concurrency, random_page_cost",
+    category: "tuning",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "G006",
+    title: "Statistics target settings",
+    description: "default_statistics_target and per-column targets",
+    category: "tuning",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "H001",
+    title: "Invalid indexes",
+    description: "Indexes that failed to build",
+    category: "indexes",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "H002",
+    title: "Unused indexes",
+    description: "Indexes with no scans",
+    category: "indexes",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "H003",
+    title: "Non-indexed foreign keys",
+    description: "FKs missing supporting indexes",
+    category: "indexes",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "H004",
+    title: "Redundant indexes",
+    description: "Indexes covered by other indexes",
+    category: "indexes",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "J001",
+    title: "Capacity planning",
+    description: "Growth trends and resource projections",
+    category: "capacity",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K001",
+    title: "Globally aggregated query metrics",
+    description: "Overall query stats summary",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K002",
+    title: "Workload type",
+    description: "Read/write/mixed workload classification",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K003",
+    title: "Top queries by total time",
+    description: "Highest total execution + planning time",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K004",
+    title: "Top queries by temp bytes written",
+    description: "Queries spilling to disk",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K005",
+    title: "Top queries by WAL generation",
+    description: "Queries generating most WAL",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K006",
+    title: "Top queries by shared blocks read",
+    description: "Queries with most disk reads",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K007",
+    title: "Top queries by shared blocks hit",
+    description: "Queries with most buffer hits",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "K008",
+    title: "Top queries by shared blocks accessed",
+    description: "Queries touching most data",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "L001",
+    title: "Table sizes",
+    description: "Table and toast sizes",
+    category: "schema",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "L002",
+    title: "Data types being used",
+    description: "Column type distribution",
+    category: "schema",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "L003",
+    title: "Integer overflow risks in primary keys",
+    description: "PKs approaching integer limits",
+    category: "schema",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "L004",
+    title: "Tables without primary key",
+    description: "Tables missing PK or unique constraint",
+    category: "schema",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "M001",
+    title: "Top queries by mean execution time",
+    description: "Slowest queries on average",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "M002",
+    title: "Top queries by rows processed",
+    description: "Queries touching most rows",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "M003",
+    title: "Top queries by I/O time",
+    description: "Queries with highest I/O wait",
+    category: "queries",
+    sort_order: null,
+    is_system_report: false
+  },
+  {
+    code: "N001",
+    title: "Wait events by type and query",
+    description: "Wait event analysis",
+    category: "waits",
+    sort_order: null,
+    is_system_report: false
+  }
+];
+
+// lib/checkup-dictionary.ts
+var dictionaryByCode = new Map(CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code, entry]));
+function buildCheckInfoMap() {
+  const result = {};
+  for (const entry of CHECKUP_DICTIONARY_DATA) {
+    result[entry.code] = entry.title;
+  }
+  return result;
+}
+
 // lib/checkup.ts
 var __dirname = "/builds/postgres-ai/postgres_ai/cli/lib";
 var SECONDS_PER_DAY = 86400;
@@ -27298,19 +27868,15 @@ var REPORT_GENERATORS = {
   H002: generateH002,
   H004: generateH004
 };
-var CHECK_INFO = {
-  A002: "Postgres major version",
-  A003: "Postgres settings",
-  A004: "Cluster information",
-  A007: "Altered settings",
-  A013: "Postgres minor version",
-  D004: "pg_stat_statements and pg_stat_kcache settings",
-  F001: "Autovacuum: current settings",
-  G001: "Memory-related settings",
-  H001: "Invalid indexes",
-  H002: "Unused indexes",
-  H004: "Redundant indexes"
-};
+var CHECK_INFO = (() => {
+  const fullMap = buildCheckInfoMap();
+  const expressCheckIds = Object.keys(REPORT_GENERATORS);
+  const filtered = {};
+  for (const checkId of expressCheckIds) {
+    filtered[checkId] = fullMap[checkId] || checkId;
+  }
+  return filtered;
+})();
 async function generateAllReports(client, nodeName = "node-01", onProgress) {
   const reports = {};
   const entries = Object.entries(REPORT_GENERATORS);
@@ -27329,6 +27895,15 @@ async function generateAllReports(client, nodeName = "node-01", onProgress) {
   return reports;
 }
 
+// lib/checkup-dictionary.ts
+var dictionaryByCode2 = new Map(CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code, entry]));
+function getAllCheckupEntries() {
+  return CHECKUP_DICTIONARY_DATA;
+}
+function getCheckupEntry(code) {
+  return dictionaryByCode2.get(code.toUpperCase()) ?? null;
+}
+
 // lib/checkup-api.ts
 import * as https from "https";
 import { URL as URL3 } from "url";
@@ -28835,10 +29410,19 @@ program2.command("unprepare-db [conn]").description("remove monitoring setup: dr
     closeReadline();
   }
 });
-program2.command("checkup [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run: ${Object.keys(CHECK_INFO).join(", ")}, or ALL`, "ALL").option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--[no-]upload", "upload JSON results to PostgresAI (default: enabled; requires API key)", undefined).option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout (implies --no-upload)").addHelpText("after", [
+var expressCheckIds = new Set(Object.keys(REPORT_GENERATORS));
+var allChecks = getAllCheckupEntries();
+var checkHelpLines = allChecks.map((entry) => {
+  const isExpress = expressCheckIds.has(entry.code);
+  return `  ${entry.code}: ${entry.title}${isExpress ? "" : " (*)"}`;
+});
+program2.command("checkup [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run (see list below), or ALL`, "ALL").option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--[no-]upload", "upload JSON results to PostgresAI (default: enabled; requires API key)", undefined).option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout (implies --no-upload)").addHelpText("after", [
   "",
   "Available checks:",
-  ...Object.entries(CHECK_INFO).map(([id, title]) => `  ${id}: ${title}`),
+  ...checkHelpLines,
+  "",
+  "  (*) = not yet available in express mode (coming soon)",
+  "  ALL = run all express-mode checks",
   "",
   "Examples:",
   "  postgresai checkup postgresql://user:pass@host:5432/db",
@@ -28894,8 +29478,16 @@ program2.command("checkup [conn]").description("generate health check reports di
       const generator = REPORT_GENERATORS[checkId];
       if (!generator) {
         spinner.stop();
-        console.error(`Unknown check ID: ${opts.checkId}`);
-        console.error(`Available: ${Object.keys(CHECK_INFO).join(", ")}, ALL`);
+        const dictEntry = getCheckupEntry(checkId);
+        if (dictEntry) {
+          console.error(`Check ${checkId} (${dictEntry.title}) is not yet available in express mode.`);
+          console.error(`Express-mode checks: ${Object.keys(CHECK_INFO).join(", ")}`);
+          console.error(`
+Full checkup reports are available at: https://postgres.ai/checkup`);
+        } else {
+          console.error(`Unknown check ID: ${opts.checkId}`);
+          console.error(`See 'postgresai checkup --help' for available checks.`);
+        }
         process.exitCode = 1;
         return;
       }

package/lib/checkup-dictionary.ts

@@ -0,0 +1,113 @@
+/**
+ * Checkup Dictionary Module
+ * =========================
+ * Provides access to the checkup report dictionary data embedded at build time.
+ *
+ * The dictionary is fetched from https://postgres.ai/api/general/checkup_dictionary
+ * during the build process and embedded into checkup-dictionary-embedded.ts.
+ *
+ * This ensures no API calls are made at runtime while keeping the data up-to-date.
+ */
+
+import { CHECKUP_DICTIONARY_DATA } from "./checkup-dictionary-embedded";
+
+/**
+ * A checkup dictionary entry describing a single check type.
+ */
+export interface CheckupDictionaryEntry {
+  /** Unique check code (e.g., "A001", "H002") */
+  code: string;
+  /** Human-readable title for the check */
+  title: string;
+  /** Brief description of what the check covers */
+  description: string;
+  /** Category grouping (e.g., "system", "indexes", "vacuum") */
+  category: string;
+  /** Optional sort order within category */
+  sort_order: number | null;
+  /** Whether this is a system-level report */
+  is_system_report: boolean;
+}
+
+/**
+ * Module-level cache for O(1) lookups by code.
+ * Initialized at module load time from embedded data.
+ */
+const dictionaryByCode: Map<string, CheckupDictionaryEntry> = new Map(
+  CHECKUP_DICTIONARY_DATA.map((entry) => [entry.code, entry])
+);
+
+/**
+ * Get all checkup dictionary entries.
+ *
+ * @returns Array of all checkup dictionary entries
+ */
+export function getAllCheckupEntries(): CheckupDictionaryEntry[] {
+  return CHECKUP_DICTIONARY_DATA;
+}
+
+/**
+ * Get a checkup dictionary entry by its code.
+ *
+ * @param code - The check code (e.g., "A001", "H002")
+ * @returns The dictionary entry or null if not found
+ */
+export function getCheckupEntry(code: string): CheckupDictionaryEntry | null {
+  return dictionaryByCode.get(code.toUpperCase()) ?? null;
+}
+
+/**
+ * Get the title for a checkup code.
+ *
+ * @param code - The check code (e.g., "A001", "H002")
+ * @returns The title or the code itself if not found
+ */
+export function getCheckupTitle(code: string): string {
+  const entry = getCheckupEntry(code);
+  return entry?.title ?? code;
+}
+
+/**
+ * Check if a code exists in the dictionary.
+ *
+ * @param code - The check code to validate
+ * @returns True if the code exists in the dictionary
+ */
+export function isValidCheckupCode(code: string): boolean {
+  return dictionaryByCode.has(code.toUpperCase());
+}
+
+/**
+ * Get all check codes as an array.
+ *
+ * @returns Array of all check codes (e.g., ["A001", "A002", ...])
+ */
+export function getAllCheckupCodes(): string[] {
+  return CHECKUP_DICTIONARY_DATA.map((entry) => entry.code);
+}
+
+/**
+ * Get checkup entries filtered by category.
+ *
+ * @param category - The category to filter by (e.g., "indexes", "vacuum")
+ * @returns Array of entries in the specified category
+ */
+export function getCheckupEntriesByCategory(category: string): CheckupDictionaryEntry[] {
+  return CHECKUP_DICTIONARY_DATA.filter(
+    (entry) => entry.category.toLowerCase() === category.toLowerCase()
+  );
+}
+
+/**
+ * Build a code-to-title mapping object.
+ * Useful for backwards compatibility with CHECK_INFO style usage.
+ *
+ * @returns Object mapping check codes to titles (e.g., { "A001": "System information", ... })
+ */
+export function buildCheckInfoMap(): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const entry of CHECKUP_DICTIONARY_DATA) {
+    result[entry.code] = entry.title;
+  }
+  return result;
+}

package/lib/checkup.ts

@@ -51,6 +51,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as pkg from "../package.json";
 import { getMetricSql, transformMetricRow, METRIC_NAMES } from "./metrics-loader";
+import { getCheckupTitle, buildCheckInfoMap } from "./checkup-dictionary";
 
 // Time constants
 const SECONDS_PER_DAY = 86400;
@@ -1344,21 +1345,27 @@ export const REPORT_GENERATORS: Record<string, (client: Client, nodeName: string
 };
 
 /**
- * Check IDs and titles
+ * Check IDs and titles.
+ *
+ * This mapping is built from the embedded checkup dictionary, which is
+ * fetched from https://postgres.ai/api/general/checkup_dictionary at build time.
+ *
+ * For the full dictionary (all available checks), use the checkup-dictionary module.
+ * CHECK_INFO is filtered to only include checks that have express-mode generators.
  */
-export const CHECK_INFO: Record<string, string> = {
-  A002: "Postgres major version",
-  A003: "Postgres settings",
-  A004: "Cluster information",
-  A007: "Altered settings",
-  A013: "Postgres minor version",
-  D004: "pg_stat_statements and pg_stat_kcache settings",
-  F001: "Autovacuum: current settings",
-  G001: "Memory-related settings",
-  H001: "Invalid indexes",
-  H002: "Unused indexes",
-  H004: "Redundant indexes",
-};
+export const CHECK_INFO: Record<string, string> = (() => {
+  // Build the full dictionary map
+  const fullMap = buildCheckInfoMap();
+
+  // Filter to only include checks that have express-mode generators
+  const expressCheckIds = Object.keys(REPORT_GENERATORS);
+  const filtered: Record<string, string> = {};
+  for (const checkId of expressCheckIds) {
+    // Use dictionary title if available, otherwise use a fallback
+    filtered[checkId] = fullMap[checkId] || checkId;
+  }
+  return filtered;
+})();
 
 /**
  * Generate all available health check reports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.14.0-dev.76",
+  "version": "0.14.0-dev.78",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,
@@ -26,15 +26,17 @@
   },
   "scripts": {
     "embed-metrics": "bun run scripts/embed-metrics.ts",
-    "build": "bun run embed-metrics && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\" && cp -r ./sql ./dist/sql",
+    "embed-checkup-dictionary": "bun run scripts/embed-checkup-dictionary.ts",
+    "embed-all": "bun run embed-metrics && bun run embed-checkup-dictionary",
+    "build": "bun run embed-all && bun build ./bin/postgres-ai.ts --outdir ./dist/bin --target node && node -e \"const fs=require('fs');const f='./dist/bin/postgres-ai.js';fs.writeFileSync(f,fs.readFileSync(f,'utf8').replace('#!/usr/bin/env bun','#!/usr/bin/env node'))\" && cp -r ./sql ./dist/sql",
     "prepublishOnly": "npm run build",
     "start": "bun ./bin/postgres-ai.ts --help",
     "start:node": "node ./dist/bin/postgres-ai.js --help",
-    "dev": "bun run embed-metrics && bun --watch ./bin/postgres-ai.ts",
-    "test": "bun run embed-metrics && bun test",
-    "test:fast": "bun run embed-metrics && bun test --coverage=false",
-    "test:coverage": "bun run embed-metrics && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
-    "typecheck": "bun run embed-metrics && bunx tsc --noEmit"
+    "dev": "bun run embed-all && bun --watch ./bin/postgres-ai.ts",
+    "test": "bun run embed-all && bun test",
+    "test:fast": "bun run embed-all && bun test",
+    "test:coverage": "bun run embed-all && bun test --coverage && echo 'Coverage report: cli/coverage/lcov-report/index.html'",
+    "typecheck": "bun run embed-all && bunx tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",

package/scripts/embed-checkup-dictionary.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * Build script to fetch checkup dictionary from API and embed it.
+ *
+ * This script fetches from https://postgres.ai/api/general/checkup_dictionary
+ * and generates cli/lib/checkup-dictionary-embedded.ts with the data embedded.
+ *
+ * The generated file is NOT committed to git - it's regenerated at build time.
+ *
+ * Usage: bun run scripts/embed-checkup-dictionary.ts
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+// API endpoint - always available without auth
+const DICTIONARY_URL = "https://postgres.ai/api/general/checkup_dictionary";
+
+// Output path relative to cli/ directory
+const CLI_DIR = path.resolve(__dirname, "..");
+const OUTPUT_PATH = path.resolve(CLI_DIR, "lib/checkup-dictionary-embedded.ts");
+
+// Request timeout (10 seconds)
+const FETCH_TIMEOUT_MS = 10_000;
+
+interface CheckupDictionaryEntry {
+  code: string;
+  title: string;
+  description: string;
+  category: string;
+  sort_order: number | null;
+  is_system_report: boolean;
+}
+
+function generateTypeScript(data: CheckupDictionaryEntry[], sourceUrl: string): string {
+  const lines: string[] = [
+    "// AUTO-GENERATED FILE - DO NOT EDIT",
+    `// Generated from: ${sourceUrl}`,
+    `// Generated at: ${new Date().toISOString()}`,
+    "// To regenerate: bun run embed-checkup-dictionary",
+    "",
+    'import { CheckupDictionaryEntry } from "./checkup-dictionary";',
+    "",
+    "/**",
+    " * Embedded checkup dictionary data fetched from API at build time.",
+    " * Contains all available checkup report codes, titles, and metadata.",
+    " */",
+    `export const CHECKUP_DICTIONARY_DATA: CheckupDictionaryEntry[] = ${JSON.stringify(data, null, 2)};`,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+async function fetchWithTimeout(url: string, timeoutMs: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    return response;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+async function main() {
+  console.log(`Fetching checkup dictionary from: ${DICTIONARY_URL}`);
+
+  try {
+    const response = await fetchWithTimeout(DICTIONARY_URL, FETCH_TIMEOUT_MS);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data: CheckupDictionaryEntry[] = await response.json();
+
+    if (!Array.isArray(data)) {
+      throw new Error("Expected array response from API");
+    }
+
+    // Validate entries have required fields
+    for (const entry of data) {
+      if (!entry.code || !entry.title) {
+        throw new Error(`Invalid entry missing code or title: ${JSON.stringify(entry)}`);
+      }
+    }
+
+    const tsCode = generateTypeScript(data, DICTIONARY_URL);
+    fs.writeFileSync(OUTPUT_PATH, tsCode, "utf8");
+
+    console.log(`Generated: ${OUTPUT_PATH}`);
+    console.log(`Dictionary contains ${data.length} entries`);
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.warn(`Warning: Failed to fetch checkup dictionary: ${errorMsg}`);
+    console.warn("Generating empty dictionary as fallback");
+
+    // Generate empty dictionary to allow build to proceed
+    const fallbackTs = generateTypeScript([], `N/A (fetch failed: ${errorMsg})`);
+    fs.writeFileSync(OUTPUT_PATH, fallbackTs, "utf8");
+    console.log(`Generated fallback dictionary at ${OUTPUT_PATH}`);
+  }
+}
+
+main();

package/test/checkup.test.ts

@@ -85,28 +85,27 @@ describe("createBaseReport", () => {
 
 // Tests for CHECK_INFO
 describe("CHECK_INFO and REPORT_GENERATORS", () => {
-  const expectedChecks: Record<string, string> = {
-    A002: "Postgres major version",
-    A003: "Postgres settings",
-    A004: "Cluster information",
-    A007: "Altered settings",
-    A013: "Postgres minor version",
-    D004: "pg_stat_statements and pg_stat_kcache settings",
-    F001: "Autovacuum: current settings",
-    G001: "Memory-related settings",
-    H001: "Invalid indexes",
-    H002: "Unused indexes",
-    H004: "Redundant indexes",
-  };
-
-  test("CHECK_INFO contains all expected checks with correct descriptions", () => {
-    for (const [checkId, description] of Object.entries(expectedChecks)) {
-      expect(checkup.CHECK_INFO[checkId]).toBe(description);
+  // Express-mode checks that have generators
+  const expressCheckIds = ["A002", "A003", "A004", "A007", "A013", "D004", "F001", "G001", "H001", "H002", "H004"];
+
+  test("CHECK_INFO contains all express-mode checks", () => {
+    for (const checkId of expressCheckIds) {
+      expect(checkup.CHECK_INFO[checkId]).toBeDefined();
+      expect(typeof checkup.CHECK_INFO[checkId]).toBe("string");
+      expect(checkup.CHECK_INFO[checkId].length).toBeGreaterThan(0);
     }
   });
 
+  test("CHECK_INFO titles are loaded from embedded dictionary", () => {
+    // Verify a few known titles match the API dictionary
+    // These are canonical titles from postgres.ai/api/general/checkup_dictionary
+    expect(checkup.CHECK_INFO["A002"]).toBe("Postgres major version");
+    expect(checkup.CHECK_INFO["H001"]).toBe("Invalid indexes");
+    expect(checkup.CHECK_INFO["H002"]).toBe("Unused indexes");
+  });
+
   test("REPORT_GENERATORS has function for each check", () => {
-    for (const checkId of Object.keys(expectedChecks)) {
+    for (const checkId of expressCheckIds) {
       expect(typeof checkup.REPORT_GENERATORS[checkId]).toBe("function");
     }
   });

package/lib/metrics-embedded.ts

@@ -1,79 +0,0 @@
-// AUTO-GENERATED FILE - DO NOT EDIT
-// Generated from config/pgwatch-prometheus/metrics.yml by scripts/embed-metrics.ts
-// Generated at: 2026-01-13T04:02:15.672Z
-
-/**
- * Metric definition from metrics.yml
- */
-export interface MetricDefinition {
-  description?: string;
-  sqls: Record<number, string>;  // PG major version -> SQL query
-  gauges?: string[];
-  statement_timeout_seconds?: number;
-}
-
-/**
- * Embedded metrics for express mode reports.
- * Only includes metrics required for CLI checkup reports.
- */
-export const METRICS: Record<string, MetricDefinition> = {
-  "settings": {
-    description: "This metric collects various PostgreSQL server settings and configurations. It provides insights into the server's configuration, including version, memory settings, and other important parameters. This metric is useful for monitoring server settings and ensuring optimal performance. Note: For lock_timeout and statement_timeout, we use reset_val instead of setting because pgwatch overrides these during metric collection, which would mask the actual configured values.",
-    sqls: {
-      11: "with base as ( /* pgwatch_generated */\n  select\n    name,\n    -- Use reset_val for lock_timeout/statement_timeout because pgwatch overrides them\n    -- during collection (lock_timeout=100ms, statement_timeout per-metric).\n    case\n      when name in ('lock_timeout', 'statement_timeout') then reset_val\n      else setting\n    end as effective_setting,\n    unit,\n    category,\n    vartype,\n    -- For lock_timeout/statement_timeout, compare reset_val with boot_val\n    -- since source becomes 'session' during collection.\n    case\n      when name in ('lock_timeout', 'statement_timeout') then (reset_val = boot_val)\n      else (source = 'default')\n    end as is_default_bool\n  from pg_settings\n), with_numeric as (\n  select\n    *,\n    case\n      when effective_setting ~ '^-?[0-9]+$' then effective_setting::bigint\n      else null\n    end as numeric_value\n  from base\n)\nselect\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  name as tag_setting_name,\n  effective_setting as tag_setting_value,\n  unit as tag_unit,\n  category as tag_category,\n  vartype as tag_vartype,\n  numeric_value,\n  case\n    when numeric_value is null then null\n    when unit = '8kB' then numeric_value * 8192\n    when unit = 'kB' then numeric_value * 1024\n    when unit = 'MB' then numeric_value * 1024 * 1024\n    when unit = 'B' then numeric_value\n    when unit = 'ms' then numeric_value::numeric / 1000\n    when unit = 's' then numeric_value::numeric\n    when unit = 'min' then numeric_value::numeric * 60\n    else null\n  end as setting_normalized,\n  case unit\n    when '8kB' then 'bytes'\n    when 'kB' then 'bytes'\n    when 'MB' then 'bytes'\n    when 'B' then 'bytes'\n    when 'ms' then 'seconds'\n    when 's' then 'seconds'\n    when 'min' then 'seconds'\n    else null\n  end as unit_normalized,\n  case when is_default_bool then 1 else 0 end as is_default,\n  1 as configured\nfrom with_numeric",
-    },
-    gauges: ["*"],
-    statement_timeout_seconds: 15,
-  },
-  "db_stats": {
-    description: "Retrieves key statistics from the PostgreSQL `pg_stat_database` view, providing insights into the current database's performance. It returns the number of backends, transaction commits and rollbacks, buffer reads and hits, tuple statistics, conflicts, temporary files and bytes, deadlocks, block read and write times, postmaster uptime, backup duration, recovery status, system identifier, and invalid indexes. This metric helps administrators monitor database activity and performance.",
-    sqls: {
-      11: "select /* pgwatch_generated */\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  numbackends,\n  xact_commit,\n  xact_rollback,\n  blks_read,\n  blks_hit,\n  tup_returned,\n  tup_fetched,\n  tup_inserted,\n  tup_updated,\n  tup_deleted,\n  conflicts,\n  temp_files,\n  temp_bytes,\n  deadlocks,\n  blk_read_time,\n  blk_write_time,\n  extract(epoch from (now() - pg_postmaster_start_time()))::int8 as postmaster_uptime_s,\n  case when pg_is_in_recovery() then 1 else 0 end as in_recovery_int,\n  system_identifier::text as tag_sys_id,\n  (select count(*) from pg_index i\n    where not indisvalid\n    and not exists ( /* leave out ones that are being actively rebuilt */\n      select * from pg_locks l\n      join pg_stat_activity a using (pid)\n      where l.relation = i.indexrelid\n      and a.state = 'active'\n      and a.query ~* 'concurrently'\n  )) as invalid_indexes\nfrom\n  pg_stat_database, pg_control_system()\nwhere\n  datname = current_database()",
-      12: "select /* pgwatch_generated */\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  numbackends,\n  xact_commit,\n  xact_rollback,\n  blks_read,\n  blks_hit,\n  tup_returned,\n  tup_fetched,\n  tup_inserted,\n  tup_updated,\n  tup_deleted,\n  conflicts,\n  temp_files,\n  temp_bytes,\n  deadlocks,\n  blk_read_time,\n  blk_write_time,\n  extract(epoch from (now() - pg_postmaster_start_time()))::int8 as postmaster_uptime_s,\n  extract(epoch from (now() - pg_backup_start_time()))::int8 as backup_duration_s,\n  checksum_failures,\n  extract(epoch from (now() - checksum_last_failure))::int8 as checksum_last_failure_s,\n  case when pg_is_in_recovery() then 1 else 0 end as in_recovery_int,\n  system_identifier::text as tag_sys_id,\n  (select count(*) from pg_index i\n    where not indisvalid\n    and not exists ( /* leave out ones that are being actively rebuilt */\n      select * from pg_locks l\n      join pg_stat_activity a using (pid)\n      where l.relation = i.indexrelid\n      and a.state = 'active'\n      and a.query ~* 'concurrently'\n  )) as invalid_indexes\nfrom\n  pg_stat_database, pg_control_system()\nwhere\n  datname = current_database()",
-      14: "select /* pgwatch_generated */\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  numbackends,\n  xact_commit,\n  xact_rollback,\n  blks_read,\n  blks_hit,\n  tup_returned,\n  tup_fetched,\n  tup_inserted,\n  tup_updated,\n  tup_deleted,\n  conflicts,\n  temp_files,\n  temp_bytes,\n  deadlocks,\n  blk_read_time,\n  blk_write_time,\n  extract(epoch from (now() - pg_postmaster_start_time()))::int8 as postmaster_uptime_s,\n  extract(epoch from (now() - pg_backup_start_time()))::int8 as backup_duration_s,\n  checksum_failures,\n  extract(epoch from (now() - checksum_last_failure))::int8 as checksum_last_failure_s,\n  case when pg_is_in_recovery() then 1 else 0 end as in_recovery_int,\n  system_identifier::text as tag_sys_id,\n  session_time::int8,\n  active_time::int8,\n  idle_in_transaction_time::int8,\n  sessions,\n  sessions_abandoned,\n  sessions_fatal,\n  sessions_killed,\n  (select count(*) from pg_index i\n    where not indisvalid\n    and not exists ( /* leave out ones that are being actively rebuilt */\n      select * from pg_locks l\n      join pg_stat_activity a using (pid)\n      where l.relation = i.indexrelid\n      and a.state = 'active'\n      and a.query ~* 'concurrently'\n  )) as invalid_indexes\nfrom\n  pg_stat_database, pg_control_system()\nwhere\n  datname = current_database()",
-      15: "select /* pgwatch_generated */\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  numbackends,\n  xact_commit,\n  xact_rollback,\n  blks_read,\n  blks_hit,\n  tup_returned,\n  tup_fetched,\n  tup_inserted,\n  tup_updated,\n  tup_deleted,\n  conflicts,\n  temp_files,\n  temp_bytes,\n  deadlocks,\n  blk_read_time,\n  blk_write_time,\n  extract(epoch from (now() - pg_postmaster_start_time()))::int8 as postmaster_uptime_s,\n  checksum_failures,\n  extract(epoch from (now() - checksum_last_failure))::int8 as checksum_last_failure_s,\n  case when pg_is_in_recovery() then 1 else 0 end as in_recovery_int,\n  system_identifier::text as tag_sys_id,\n  session_time::int8,\n  active_time::int8,\n  idle_in_transaction_time::int8,\n  sessions,\n  sessions_abandoned,\n  sessions_fatal,\n  sessions_killed,\n  (select count(*) from pg_index i\n    where not indisvalid\n    and not exists ( /* leave out ones that are being actively rebuilt */\n      select * from pg_locks l\n      join pg_stat_activity a using (pid)\n      where l.relation = i.indexrelid\n      and a.state = 'active'\n      and a.query ~* 'concurrently'\n  )) as invalid_indexes\nfrom\n  pg_stat_database, pg_control_system()\nwhere\n  datname = current_database()",
-    },
-    gauges: ["*"],
-    statement_timeout_seconds: 15,
-  },
-  "db_size": {
-    description: "Retrieves the size of the current database and the size of the `pg_catalog` schema, providing insights into the storage usage of the database. It returns the size in bytes for both the current database and the catalog schema. This metric helps administrators monitor database size and storage consumption.",
-    sqls: {
-      11: "select /* pgwatch_generated */\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  pg_database_size(current_database()) as size_b,\n  (select sum(pg_total_relation_size(c.oid))::int8\n    from pg_class c join pg_namespace n on n.oid = c.relnamespace\n    where nspname = 'pg_catalog' and relkind = 'r'\n  ) as catalog_size_b",
-    },
-    gauges: ["*"],
-    statement_timeout_seconds: 300,
-  },
-  "pg_invalid_indexes": {
-    description: "This metric identifies invalid indexes in the database with decision tree data for remediation. It provides insights into whether to DROP (if duplicate exists), RECREATE (if backs constraint), or flag as UNCERTAIN (if additional RCA is needed to check query plans). Decision tree: 1) Valid duplicate exists -> DROP, 2) Backs PK/UNIQUE constraint -> RECREATE, 3) Table < 10K rows -> RECREATE (small tables rebuild quickly, typically under 1 second), 4) Otherwise -> UNCERTAIN (need query plan analysis to assess impact).",
-    sqls: {
-      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    schemaname as schema_name,\n    indexrelid,\n    (indexrelid::regclass)::text as index_name,\n    (relid::regclass)::text as table_name,\n    (confrelid::regclass)::text as fk_table_ref,\n    array_to_string(indclass, ', ') as opclasses\n  from pg_stat_all_indexes\n  join pg_index using (indexrelid)\n  left join pg_constraint\n    on array_to_string(indkey, ',') = array_to_string(conkey, ',')\n      and schemaname = (connamespace::regnamespace)::text\n      and conrelid = relid\n      and contype = 'f'\n  where idx_scan = 0\n    and indisunique is false\n    and conkey is not null\n),\n-- Find valid indexes that could be duplicates (same table, same columns)\nvalid_duplicates as (\n  select\n    inv.indexrelid as invalid_indexrelid,\n    val.indexrelid as valid_indexrelid,\n    (val.indexrelid::regclass)::text as valid_index_name,\n    pg_get_indexdef(val.indexrelid) as valid_index_definition\n  from pg_index inv\n  join pg_index val on inv.indrelid = val.indrelid  -- same table\n    and inv.indkey = val.indkey  -- same columns (in same order)\n    and inv.indexrelid != val.indexrelid  -- different index\n    and val.indisvalid = true  -- valid index\n  where inv.indisvalid = false\n),\ndata as (\n  select\n    pci.relname as tag_index_name,\n    pn.nspname as tag_schema_name,\n    pct.relname as tag_table_name,\n    coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,\n    pg_get_indexdef(pidx.indexrelid) as index_definition,\n    pg_relation_size(pidx.indexrelid) as index_size_bytes,\n    -- Constraint info\n    pidx.indisprimary as is_pk,\n    pidx.indisunique as is_unique,\n    con.conname as constraint_name,\n    -- Table row estimate\n    pct.reltuples::bigint as table_row_estimate,\n    -- Valid duplicate check\n    (vd.valid_indexrelid is not null) as has_valid_duplicate,\n    vd.valid_index_name,\n    vd.valid_index_definition,\n    -- FK support check\n    ((\n      select count(1)\n      from fk_indexes fi\n      where fi.fk_table_ref = pct.relname\n        and fi.opclasses like (array_to_string(pidx.indclass, ', ') || '%')\n    ) > 0)::int as supports_fk\n  from pg_index pidx\n  join pg_class pci on pci.oid = pidx.indexrelid\n  join pg_class pct on pct.oid = pidx.indrelid\n  left join pg_namespace pn on pn.oid = pct.relnamespace\n  left join pg_constraint con on con.conindid = pidx.indexrelid\n  left join valid_duplicates vd on vd.invalid_indexrelid = pidx.indexrelid\n  where pidx.indisvalid = false\n),\nnum_data as (\n  select\n    row_number() over () as num,\n    data.*\n  from data\n)\nselect\n  (extract(epoch from now()) * 1e9)::int8 as epoch_ns,\n  current_database() as tag_datname,\n  num_data.*\nfrom num_data\nlimit 1000;\n",
-    },
-    gauges: ["*"],
-    statement_timeout_seconds: 15,
-  },
-  "unused_indexes": {
-    description: "This metric identifies unused indexes in the database. It provides insights into the number of unused indexes and their details. This metric helps administrators identify and fix unused indexes to improve database performance.",
-    sqls: {
-      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    n.nspname as schema_name,\n    ci.relname as index_name,\n    cr.relname as table_name,\n    (confrelid::regclass)::text as fk_table_ref,\n    array_to_string(indclass, ', ') as opclasses\n  from pg_index i\n  join pg_class ci on ci.oid = i.indexrelid and ci.relkind = 'i'\n  join pg_class cr on cr.oid = i.indrelid and cr.relkind = 'r'\n  join pg_namespace n on n.oid = ci.relnamespace\n  join pg_constraint cn on cn.conrelid = cr.oid\n  left join pg_stat_all_indexes as si on si.indexrelid = i.indexrelid\n  where\n    contype = 'f'\n    and i.indisunique is false\n    and conkey is not null\n    and ci.relpages > 5\n    and si.idx_scan < 10\n), table_scans as (\n  select relid,\n      tables.idx_scan + tables.seq_scan as all_scans,\n      ( tables.n_tup_ins + tables.n_tup_upd + tables.n_tup_del ) as writes,\n    pg_relation_size(relid) as table_size\n      from pg_stat_all_tables as tables\n      join pg_class c on c.oid = relid\n      where c.relpages > 5\n), indexes as (\n  select\n    i.indrelid,\n    i.indexrelid,\n    n.nspname as schema_name,\n    cr.relname as table_name,\n    ci.relname as index_name,\n    si.idx_scan,\n    pg_relation_size(i.indexrelid) as index_bytes,\n    ci.relpages,\n    (case when a.amname = 'btree' then true else false end) as idx_is_btree,\n    array_to_string(i.indclass, ', ') as opclasses\n  from pg_index i\n    join pg_class ci on ci.oid = i.indexrelid and ci.relkind = 'i'\n    join pg_class cr on cr.oid = i.indrelid and cr.relkind = 'r'\n    join pg_namespace n on n.oid = ci.relnamespace\n    join pg_am a on ci.relam = a.oid\n    left join pg_stat_all_indexes as si on si.indexrelid = i.indexrelid\n  where\n    i.indisunique = false\n    and i.indisvalid = true\n    and ci.relpages > 5\n), index_ratios as (\n  select\n    i.indexrelid as index_id,\n    i.schema_name,\n    i.table_name,\n    i.index_name,\n    idx_scan,\n    all_scans,\n    round(( case when all_scans = 0 then 0.0::numeric\n      else idx_scan::numeric/all_scans * 100 end), 2) as index_scan_pct,\n    writes,\n    round((case when writes = 0 then idx_scan::numeric else idx_scan::numeric/writes end), 2)\n      as scans_per_write,\n    index_bytes as index_size_bytes,\n    table_size as table_size_bytes,\n    i.relpages,\n    idx_is_btree,\n    i.opclasses,\n    (\n      select count(1)\n      from fk_indexes fi\n      where fi.fk_table_ref = i.table_name\n        and fi.schema_name = i.schema_name\n        and fi.opclasses like (i.opclasses || '%')\n    ) > 0 as supports_fk\n  from indexes i\n  join table_scans ts on ts.relid = i.indrelid\n)\nselect\n  'Never Used Indexes' as tag_reason,\n  current_database() as tag_datname,\n  index_id,\n  schema_name as tag_schema_name,\n  table_name as tag_table_name,\n  index_name as tag_index_name,\n  pg_get_indexdef(index_id) as index_definition,\n  idx_scan,\n  all_scans,\n  index_scan_pct,\n  writes,\n  scans_per_write,\n  index_size_bytes,\n  table_size_bytes,\n  relpages,\n  idx_is_btree,\n  opclasses as tag_opclasses,\n  supports_fk\nfrom index_ratios\nwhere\n  idx_scan = 0\n  and idx_is_btree\norder by index_size_bytes desc\nlimit 1000;\n",
-    },
-    gauges: ["*"],
-    statement_timeout_seconds: 15,
-  },
-  "redundant_indexes": {
-    description: "This metric identifies redundant indexes that can potentially be dropped to save storage space and improve write performance. It analyzes index relationships and finds indexes that are covered by other indexes, considering column order, operator classes, and foreign key constraints. Uses the exact logic from tmp.sql with JSON aggregation and proper thresholds.",
-    sqls: {
-      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    n.nspname as schema_name,\n    ci.relname as index_name,\n    cr.relname as table_name,\n    (confrelid::regclass)::text as fk_table_ref,\n    array_to_string(indclass, ', ') as opclasses\n  from pg_index i\n  join pg_class ci on ci.oid = i.indexrelid and ci.relkind = 'i'\n  join pg_class cr on cr.oid = i.indrelid and cr.relkind = 'r'\n  join pg_namespace n on n.oid = ci.relnamespace\n  join pg_constraint cn on cn.conrelid = cr.oid\n  left join pg_stat_all_indexes as si on si.indexrelid = i.indexrelid\n  where\n    contype = 'f'\n    and i.indisunique is false\n    and conkey is not null\n    and ci.relpages > 5\n    and si.idx_scan < 10\n),\n-- Redundant indexes\nindex_data as (\n  select\n    *,\n    indkey::text as columns,\n    array_to_string(indclass, ', ') as opclasses\n  from pg_index i\n  join pg_class ci on ci.oid = i.indexrelid and ci.relkind = 'i'\n  where indisvalid = true and ci.relpages > 5\n), redundant_indexes as (\n  select\n    i2.indexrelid as index_id,\n    tnsp.nspname as schema_name,\n    trel.relname as table_name,\n    pg_relation_size(trel.oid) as table_size_bytes,\n    irel.relname as index_name,\n    am1.amname as access_method,\n    (i1.indexrelid::regclass)::text as reason,\n    i1.indexrelid as reason_index_id,\n    pg_get_indexdef(i1.indexrelid) main_index_def,\n    pg_relation_size(i1.indexrelid) main_index_size_bytes,\n    pg_get_indexdef(i2.indexrelid) index_def,\n    pg_relation_size(i2.indexrelid) index_size_bytes,\n    s.idx_scan as index_usage,\n    quote_ident(tnsp.nspname) as formated_schema_name,\n    coalesce(nullif(quote_ident(tnsp.nspname), 'public') || '.', '') || quote_ident(irel.relname) as formated_index_name,\n    quote_ident(trel.relname) as formated_table_name,\n    coalesce(nullif(quote_ident(tnsp.nspname), 'public') || '.', '') || quote_ident(trel.relname) as formated_relation_name,\n    i2.opclasses\n  from (\n    select indrelid, indexrelid, opclasses, indclass, indexprs, indpred, indisprimary, indisunique, columns\n      from index_data\n      order by indexrelid\n    ) as i1\n    join index_data as i2 on (\n        i1.indrelid = i2.indrelid -- same table\n        and i1.indexrelid <> i2.indexrelid -- NOT same index\n    )\n    inner join pg_opclass op1 on i1.indclass[0] = op1.oid\n    inner join pg_opclass op2 on i2.indclass[0] = op2.oid\n    inner join pg_am am1 on op1.opcmethod = am1.oid\n    inner join pg_am am2 on op2.opcmethod = am2.oid\n    join pg_stat_all_indexes as s on s.indexrelid = i2.indexrelid\n    join pg_class as trel on trel.oid = i2.indrelid\n    join pg_namespace as tnsp on trel.relnamespace = tnsp.oid\n    join pg_class as irel on irel.oid = i2.indexrelid\n  where\n    not i2.indisprimary -- index 1 is not primary\n    and not i2.indisunique -- index 1 is not unique (unique indexes serve constraint purpose)\n    and  am1.amname = am2.amname -- same access type\n    and i1.columns like (i2.columns || '%') -- index 2 includes all columns from index 1\n    and i1.opclasses like (i2.opclasses || '%')\n    -- index expressions is same\n    and pg_get_expr(i1.indexprs, i1.indrelid) is not distinct from pg_get_expr(i2.indexprs, i2.indrelid)\n    -- index predicates is same\n    and pg_get_expr(i1.indpred, i1.indrelid) is not distinct from pg_get_expr(i2.indpred, i2.indrelid)\n), redundant_indexes_fk as (\n  select\n    ri.*,\n    ((\n      select count(1)\n      from fk_indexes fi\n      where\n        fi.fk_table_ref = ri.table_name\n        and fi.opclasses like (ri.opclasses || '%')\n    ) > 0)::int as supports_fk\n  from redundant_indexes ri\n),\n-- Cut recursive links\nredundant_indexes_tmp_num as (\n  select row_number() over () num, rig.*\n  from redundant_indexes_fk rig\n), redundant_indexes_tmp_links as (\n    select\n    ri1.*,\n    ri2.num as r_num\n    from redundant_indexes_tmp_num ri1\n    left join redundant_indexes_tmp_num ri2 on ri2.reason_index_id = ri1.index_id and ri1.reason_index_id = ri2.index_id\n), redundant_indexes_tmp_cut as (\n    select\n    *\n    from redundant_indexes_tmp_links\n    where num < r_num or r_num is null\n), redundant_indexes_cut_grouped as (\n  select\n    distinct(num),\n    *\n  from redundant_indexes_tmp_cut\n  order by index_size_bytes desc\n), redundant_indexes_grouped as (\n  select\n    index_id,\n    schema_name as tag_schema_name,\n    table_name,\n    table_size_bytes,\n    index_name as tag_index_name,\n    access_method as tag_access_method,\n    string_agg(distinct reason, ', ') as tag_reason,\n    index_size_bytes,\n    index_usage,\n    index_def as index_definition,\n    formated_index_name as tag_index_name,\n    formated_schema_name as tag_schema_name,\n    formated_table_name as tag_table_name,\n    formated_relation_name as tag_relation_name,\n    supports_fk::int as supports_fk,\n    json_agg(\n      distinct jsonb_build_object(\n        'index_name', reason,\n        'index_definition', main_index_def,\n        'index_size_bytes', main_index_size_bytes\n      )\n    )::text as redundant_to_json\n  from redundant_indexes_cut_grouped\n  group by\n    index_id,\n    table_size_bytes,\n    schema_name,\n    table_name,\n    index_name,\n    access_method,\n    index_def,\n    index_size_bytes,\n    index_usage,\n    formated_index_name,\n    formated_schema_name,\n    formated_table_name,\n    formated_relation_name,\n    supports_fk\n  order by index_size_bytes desc\n)\nselect * from redundant_indexes_grouped\nlimit 1000;\n",
-    },
-    gauges: ["*"],
-    statement_timeout_seconds: 15,
-  },
-  "stats_reset": {
-    description: "This metric tracks when statistics were last reset at the database level. It provides visibility into the freshness of statistics data, which is essential for understanding the reliability of usage metrics. A recent reset time indicates that usage statistics may not reflect long-term patterns. Note that Postgres tracks stats resets at the database level, not per-index or per-table.",
-    sqls: {
-      11: "select /* pgwatch_generated */\n  datname as tag_database_name,\n  extract(epoch from stats_reset)::int as stats_reset_epoch,\n  extract(epoch from now() - stats_reset)::int as seconds_since_reset\nfrom pg_stat_database\nwhere datname = current_database()\n  and stats_reset is not null;\n",
-    },
-    gauges: ["stats_reset_epoch","seconds_since_reset"],
-    statement_timeout_seconds: 15,
-  },
-};