postgresai 0.14.0-beta.3 → 0.14.0-beta.4

package/lib/issues.ts

@@ -1,6 +1,4 @@
-import * as https from "https";
-import { URL } from "url";
-import { maskSecret, normalizeBaseUrl } from "./util";
+import { formatHttpError, maskSecret, normalizeBaseUrl } from "./util";
 
 export interface IssueActionItem {
   id: string;
@@ -75,59 +73,33 @@ export async function fetchIssues(params: FetchIssuesParams): Promise<IssueListI
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    // eslint-disable-next-line no-console
     console.log(`Debug: Resolved API base URL: ${base}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: GET URL: ${url.toString()}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Auth scheme: access-token`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
-  return new Promise((resolve, reject) => {
-    const req = https.request(
-      url,
-      {
-        method: "GET",
-        headers,
-      },
-      (res) => {
-        let data = "";
-        res.on("data", (chunk) => (data += chunk));
-        res.on("end", () => {
-          if (debug) {
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response status: ${res.statusCode}`);
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response headers: ${JSON.stringify(res.headers)}`);
-          }
-          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
-            try {
-              const parsed = JSON.parse(data) as IssueListItem[];
-              resolve(parsed);
-            } catch {
-              reject(new Error(`Failed to parse issues response: ${data}`));
-            }
-          } else {
-            let errMsg = `Failed to fetch issues: HTTP ${res.statusCode}`;
-            if (data) {
-              try {
-                const errObj = JSON.parse(data);
-                errMsg += `\n${JSON.stringify(errObj, null, 2)}`;
-              } catch {
-                errMsg += `\n${data}`;
-              }
-            }
-            reject(new Error(errMsg));
-          }
-        });
-      }
-    );
-
-    req.on("error", (err: Error) => reject(err));
-    req.end();
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers,
   });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as IssueListItem[];
+    } catch {
+      throw new Error(`Failed to parse issues response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch issues", response.status, data));
+  }
 }
 
 
@@ -158,59 +130,33 @@ export async function fetchIssueComments(params: FetchIssueCommentsParams): Prom
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    // eslint-disable-next-line no-console
     console.log(`Debug: Resolved API base URL: ${base}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: GET URL: ${url.toString()}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Auth scheme: access-token`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
-  return new Promise((resolve, reject) => {
-    const req = https.request(
-      url,
-      {
-        method: "GET",
-        headers,
-      },
-      (res) => {
-        let data = "";
-        res.on("data", (chunk) => (data += chunk));
-        res.on("end", () => {
-          if (debug) {
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response status: ${res.statusCode}`);
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response headers: ${JSON.stringify(res.headers)}`);
-          }
-          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
-            try {
-              const parsed = JSON.parse(data) as IssueComment[];
-              resolve(parsed);
-            } catch {
-              reject(new Error(`Failed to parse issue comments response: ${data}`));
-            }
-          } else {
-            let errMsg = `Failed to fetch issue comments: HTTP ${res.statusCode}`;
-            if (data) {
-              try {
-                const errObj = JSON.parse(data);
-                errMsg += `\n${JSON.stringify(errObj, null, 2)}`;
-              } catch {
-                errMsg += `\n${data}`;
-              }
-            }
-            reject(new Error(errMsg));
-          }
-        });
-      }
-    );
-
-    req.on("error", (err: Error) => reject(err));
-    req.end();
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers,
   });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as IssueComment[];
+    } catch {
+      throw new Error(`Failed to parse issue comments response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch issue comments", response.status, data));
+  }
 }
 
 export interface FetchIssueParams {
@@ -243,63 +189,38 @@ export async function fetchIssue(params: FetchIssueParams): Promise<IssueDetail
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    // eslint-disable-next-line no-console
     console.log(`Debug: Resolved API base URL: ${base}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: GET URL: ${url.toString()}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Auth scheme: access-token`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
   }
 
-  return new Promise((resolve, reject) => {
-    const req = https.request(
-      url,
-      {
-        method: "GET",
-        headers,
-      },
-      (res) => {
-        let data = "";
-        res.on("data", (chunk) => (data += chunk));
-        res.on("end", () => {
-          if (debug) {
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response status: ${res.statusCode}`);
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response headers: ${JSON.stringify(res.headers)}`);
-          }
-          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
-            try {
-              const parsed = JSON.parse(data);
-              if (Array.isArray(parsed)) {
-                resolve((parsed[0] as IssueDetail) ?? null);
-              } else {
-                resolve(parsed as IssueDetail);
-              }
-            } catch {
-              reject(new Error(`Failed to parse issue response: ${data}`));
-            }
-          } else {
-            let errMsg = `Failed to fetch issue: HTTP ${res.statusCode}`;
-            if (data) {
-              try {
-                const errObj = JSON.parse(data);
-                errMsg += `\n${JSON.stringify(errObj, null, 2)}`;
-              } catch {
-                errMsg += `\n${data}`;
-              }
-            }
-            reject(new Error(errMsg));
-          }
-        });
-      }
-    );
-
-    req.on("error", (err: Error) => reject(err));
-    req.end();
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers,
   });
+
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
+
+  if (response.ok) {
+    try {
+      const parsed = JSON.parse(data);
+      if (Array.isArray(parsed)) {
+        return (parsed[0] as IssueDetail) ?? null;
+      } else {
+        return parsed as IssueDetail;
+      }
+    } catch {
+      throw new Error(`Failed to parse issue response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch issue", response.status, data));
+  }
 }
 
 export interface CreateIssueCommentParams {
@@ -339,67 +260,37 @@ export async function createIssueComment(params: CreateIssueCommentParams): Prom
     "access-token": apiKey,
     "Prefer": "return=representation",
     "Content-Type": "application/json",
-    "Content-Length": Buffer.byteLength(body).toString(),
   };
 
   if (debug) {
     const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
-    // eslint-disable-next-line no-console
     console.log(`Debug: Resolved API base URL: ${base}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: POST URL: ${url.toString()}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Auth scheme: access-token`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-    // eslint-disable-next-line no-console
     console.log(`Debug: Request body: ${body}`);
   }
 
-  return new Promise((resolve, reject) => {
-    const req = https.request(
-      url,
-      {
-        method: "POST",
-        headers,
-      },
-      (res) => {
-        let data = "";
-        res.on("data", (chunk) => (data += chunk));
-        res.on("end", () => {
-          if (debug) {
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response status: ${res.statusCode}`);
-            // eslint-disable-next-line no-console
-            console.log(`Debug: Response headers: ${JSON.stringify(res.headers)}`);
-          }
-          if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
-            try {
-              const parsed = JSON.parse(data) as IssueComment;
-              resolve(parsed);
-            } catch {
-              reject(new Error(`Failed to parse create comment response: ${data}`));
-            }
-          } else {
-            let errMsg = `Failed to create issue comment: HTTP ${res.statusCode}`;
-            if (data) {
-              try {
-                const errObj = JSON.parse(data);
-                errMsg += `\n${JSON.stringify(errObj, null, 2)}`;
-              } catch {
-                errMsg += `\n${data}`;
-              }
-            }
-            reject(new Error(errMsg));
-          }
-        });
-      }
-    );
-
-    req.on("error", (err: Error) => reject(err));
-    req.write(body);
-    req.end();
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body,
   });
-}
 
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+
+  const data = await response.text();
 
+  if (response.ok) {
+    try {
+      return JSON.parse(data) as IssueComment;
+    } catch {
+      throw new Error(`Failed to parse create comment response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to create issue comment", response.status, data));
+  }
+}

package/lib/mcp-server.ts

@@ -1,12 +1,12 @@
-import * as pkg from "../package.json";
+import pkg from "../package.json";
 import * as config from "./config";
 import { fetchIssues, fetchIssueComments, createIssueComment, fetchIssue } from "./issues";
 import { resolveBaseUrls } from "./util";
 
-// MCP SDK imports
-import { Server } from "@modelcontextprotocol/sdk/server";
-import * as path from "path";
-// Types schemas will be loaded dynamically from the SDK's CJS bundle
+// MCP SDK imports - Bun handles these directly
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
 interface RootOptsLike {
   apiKey?: string;
@@ -14,16 +14,6 @@ interface RootOptsLike {
 }
 
 export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?: boolean }): Promise<void> {
-  // Resolve stdio transport at runtime to avoid subpath export resolution issues
-  const serverEntry = require.resolve("@modelcontextprotocol/sdk/server");
-  const stdioPath = path.join(path.dirname(serverEntry), "stdio.js");
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
-  const { StdioServerTransport } = require(stdioPath);
-  // Load schemas dynamically to avoid subpath export resolution issues
-  const typesPath = path.resolve(path.dirname(serverEntry), "../types.js");
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
-  const { CallToolRequestSchema, ListToolsRequestSchema } = require(typesPath);
-
   const server = new Server(
     { name: "postgresai-mcp", version: pkg.version },
     { capabilities: { tools: {} } }
@@ -85,6 +75,7 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
     };
   });
 
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   server.setRequestHandler(CallToolRequestSchema, async (req: any) => {
     const toolName = req.params.name;
     const args = (req.params.arguments as Record<string, unknown>) || {};
@@ -152,5 +143,3 @@ export async function startMcpServer(rootOpts?: RootOptsLike, extra?: { debug?:
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
-
-

package/lib/metrics-embedded.ts

@@ -0,0 +1,79 @@
+// AUTO-GENERATED FILE - DO NOT EDIT
+// Generated from config/pgwatch-prometheus/metrics.yml by scripts/embed-metrics.ts
+// Generated at: 2025-12-28T15:08:46.857Z
+
+/**
+ * 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. It provides insights into the number of invalid indexes and their details. This metric helps administrators identify and fix invalid indexes to improve database performance.",
+    sqls: {
+      11: "with fk_indexes as ( /* pgwatch_generated */\n  select\n    schemaname as tag_schema_name,\n    (indexrelid::regclass)::text as tag_index_name,\n    (relid::regclass)::text as tag_table_name,\n    (confrelid::regclass)::text as tag_fk_table_ref,\n    array_to_string(indclass, ', ') as tag_opclasses\n  from\n    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 --conkey is not null then true else false end as is_fk_idx\n), data 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    quote_ident(pn.nspname) as tag_schema_name,\n    quote_ident(pci.relname) as tag_index_name,\n    quote_ident(pct.relname) as tag_table_name,\n    coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,\n    pg_relation_size(pidx.indexrelid) index_size_bytes,\n    ((\n      select count(1)\n      from fk_indexes fi\n      where\n        fi.tag_fk_table_ref = pct.relname\n        and fi.tag_opclasses like (array_to_string(pidx.indclass, ', ') || '%')\n    ) > 0)::int as supports_fk\n  from pg_index pidx\n  join pg_class as pci on pci.oid = pidx.indexrelid\n  join pg_class as pct on pct.oid = pidx.indrelid\n  left join pg_namespace pn on pn.oid = pct.relnamespace\n  where pidx.indisvalid = false\n), data_total as (\n    select\n      sum(index_size_bytes) as index_size_bytes_sum\n    from data\n), num_data as (\n  select\n    row_number() over () 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,
+  },
+};

package/lib/metrics-loader.ts

@@ -0,0 +1,127 @@
+/**
+ * Metrics loader for express checkup reports
+ * 
+ * Loads SQL queries from embedded metrics data (generated from metrics.yml at build time).
+ * Provides version-aware query selection and row transformation utilities.
+ */
+
+import { METRICS, MetricDefinition } from "./metrics-embedded";
+
+/**
+ * Get SQL query for a specific metric, selecting the appropriate version.
+ * 
+ * @param metricName - Name of the metric (e.g., "settings", "db_stats")
+ * @param pgMajorVersion - PostgreSQL major version (default: 16)
+ * @returns SQL query string
+ * @throws Error if metric not found or no compatible version available
+ */
+export function getMetricSql(metricName: string, pgMajorVersion: number = 16): string {
+  const metric = METRICS[metricName];
+  
+  if (!metric) {
+    throw new Error(`Metric "${metricName}" not found. Available metrics: ${Object.keys(METRICS).join(", ")}`);
+  }
+  
+  // Find the best matching version: highest version <= pgMajorVersion
+  const availableVersions = Object.keys(metric.sqls)
+    .map(v => parseInt(v, 10))
+    .sort((a, b) => b - a); // Sort descending
+  
+  const matchingVersion = availableVersions.find(v => v <= pgMajorVersion);
+  
+  if (matchingVersion === undefined) {
+    throw new Error(
+      `No compatible SQL version for metric "${metricName}" with PostgreSQL ${pgMajorVersion}. ` +
+      `Available versions: ${availableVersions.join(", ")}`
+    );
+  }
+  
+  return metric.sqls[matchingVersion];
+}
+
+/**
+ * Get metric definition including all metadata.
+ * 
+ * @param metricName - Name of the metric
+ * @returns MetricDefinition or undefined if not found
+ */
+export function getMetricDefinition(metricName: string): MetricDefinition | undefined {
+  return METRICS[metricName];
+}
+
+/**
+ * List all available metric names.
+ */
+export function listMetricNames(): string[] {
+  return Object.keys(METRICS);
+}
+
+/**
+ * Metric names that correspond to express report checks.
+ * Maps check IDs and logical names to metric names in the METRICS object.
+ */
+export const METRIC_NAMES = {
+  // Index health checks
+  H001: "pg_invalid_indexes",
+  H002: "unused_indexes", 
+  H004: "redundant_indexes",
+  // Settings and version info (A002, A003, A007, A013)
+  settings: "settings",
+  // Database statistics (A004)
+  dbStats: "db_stats",
+  dbSize: "db_size",
+  // Stats reset info (H002)
+  statsReset: "stats_reset",
+} as const;
+
+/**
+ * Transform a row from metrics query output to JSON report format.
+ * Metrics use `tag_` prefix for dimensions; we strip it for JSON reports.
+ * Also removes Prometheus-specific fields like epoch_ns, num, tag_datname.
+ */
+export function transformMetricRow(row: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  
+  for (const [key, value] of Object.entries(row)) {
+    // Skip Prometheus-specific fields
+    if (key === "epoch_ns" || key === "num" || key === "tag_datname") {
+      continue;
+    }
+    
+    // Strip tag_ prefix
+    const newKey = key.startsWith("tag_") ? key.slice(4) : key;
+    result[newKey] = value;
+  }
+  
+  return result;
+}
+
+/**
+ * Transform settings metric row to the format expected by express reports.
+ * The settings metric returns one row per setting with tag_setting_name as key.
+ */
+export function transformSettingsRow(row: Record<string, unknown>): {
+  name: string;
+  setting: string;
+  unit: string;
+  category: string;
+  vartype: string;
+  is_default: boolean;
+} {
+  return {
+    name: String(row.tag_setting_name || ""),
+    setting: String(row.tag_setting_value || ""),
+    unit: String(row.tag_unit || ""),
+    category: String(row.tag_category || ""),
+    vartype: String(row.tag_vartype || ""),
+    is_default: row.is_default === 1 || row.is_default === true,
+  };
+}
+
+// Re-export types for convenience
+export type { MetricDefinition } from "./metrics-embedded";
+
+// Legacy export for backward compatibility
+export function loadMetricsYml(): { metrics: Record<string, unknown> } {
+  return { metrics: METRICS };
+}