postgresai 0.15.0-dev.1 → 0.15.0-dev.11

package/instances.demo.yml

@@ -0,0 +1,14 @@
+# Demo PostgreSQL instance for `pgai mon local-install --demo`
+# This file is copied to instances.yml during demo mode setup.
+
+- name: target_database
+  conn_str: postgresql://monitor:monitor_pass@target-db:5432/target_database
+  preset_metrics: full
+  custom_metrics:
+  is_enabled: true
+  group: default
+  custom_tags:
+    env: demo
+    cluster: local
+    node_name: node-01
+    sink_type: ~sink_type~  # sed token substituted by generate-pgwatch-sources.sh; values: postgres, prometheus

package/lib/checkup-api.ts

@@ -1,3 +1,4 @@
+import * as http from "http";
 import * as https from "https";
 import { URL } from "url";
 import { normalizeBaseUrl } from "./util";
@@ -27,7 +28,7 @@ function isRetryableError(err: unknown): boolean {
     // Retry on server errors (5xx), not on client errors (4xx)
     return err.statusCode >= 500 && err.statusCode < 600;
   }
-  
+
   // Check for Node.js error codes (works on Error and Error-like objects)
   if (typeof err === "object" && err !== null && "code" in err) {
     const code = String((err as { code: unknown }).code);
@@ -35,7 +36,7 @@ function isRetryableError(err: unknown): boolean {
       return true;
     }
   }
-  
+
   if (err instanceof Error) {
     const msg = err.message.toLowerCase();
     // Retry on network-related errors based on message content
@@ -49,7 +50,7 @@ function isRetryableError(err: unknown): boolean {
       msg.includes("network")
     );
   }
-  
+
   return false;
 }
 
@@ -226,7 +227,25 @@ async function postRpc<T>(params: {
       resolve(value);
     };
 
-    const req = https.request(
+    // Transport is picked from the URL protocol so the CLI can talk to a
+    // local-dev PostgREST over plain HTTP. Production URLs are always HTTPS;
+    // to guard against typos (e.g. a missing 's' in 'https://') silently
+    // leaking the API key in cleartext, refuse HTTP to non-loopback hosts
+    // unless the operator explicitly opts in via CHECKUP_ALLOW_HTTP=1.
+    if (url.protocol === "http:") {
+      // WHATWG URL keeps IPv6 literals bracketed in .hostname
+      // (e.g. `[::1]`), so strip the brackets before matching the allowlist.
+      const hostname = url.hostname.replace(/^\[|\]$/g, "");
+      const isLoopback = ["localhost", "127.0.0.1", "::1"].includes(hostname);
+      if (!isLoopback && process.env.CHECKUP_ALLOW_HTTP !== "1") {
+        throw new Error(
+          `Refusing to send API key over plaintext HTTP to '${url.host}'. ` +
+          `Use https://, a loopback hostname, or set CHECKUP_ALLOW_HTTP=1.`
+        );
+      }
+    }
+    const transport = url.protocol === "http:" ? http : https;
+    const req = transport.request(
       url,
       {
         method: "POST",
@@ -277,7 +296,7 @@ async function postRpc<T>(params: {
       req.destroy();  // Backup: ensure request is terminated
       settledReject(new Error(`RPC ${rpcName} timed out after ${timeoutMs}ms (no response)`));
     }, timeoutMs);
-    
+
     req.on("error", (err: Error) => {
       // Handle abort as timeout (may already be rejected by timeout handler)
       if (err.name === "AbortError" || (err as any).code === "ABORT_ERR") {
@@ -295,7 +314,7 @@ async function postRpc<T>(params: {
         settledReject(err);
       }
     });
-    
+
     req.write(body);
     req.end();
   });

package/lib/checkup-dictionary.ts

@@ -57,17 +57,6 @@ 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.
  *

package/lib/checkup.ts

@@ -2,41 +2,41 @@
  * Express Checkup Module
  * ======================
  * Generates JSON health check reports directly from PostgreSQL without Prometheus.
- * 
+ *
  * ARCHITECTURAL DECISIONS
  * -----------------------
- * 
+ *
  * 1. SINGLE SOURCE OF TRUTH FOR SQL QUERIES
- *    Complex metrics (index health, settings, db_stats) are loaded from 
+ *    Complex metrics (index health, settings, db_stats) are loaded from
  *    config/pgwatch-prometheus/metrics.yml via getMetricSql() from metrics-loader.ts.
- *    
+ *
  *    Simple queries (version, database list, connection states, uptime) use
  *    inline SQL as they're trivial and CLI-specific.
- * 
+ *
  * 2. JSON SCHEMA COMPLIANCE
  *    All generated reports MUST comply with JSON schemas in reporter/schemas/.
  *    These schemas define the expected format for both:
  *    - Full-fledged monitoring reporter output
  *    - Express checkup output
- * 
+ *
  *    Before adding or modifying a report, verify the corresponding schema exists
  *    and ensure the output matches. Run schema validation tests to confirm.
- * 
+ *
  * 3. ERROR HANDLING STRATEGY
  *    Functions follow two patterns based on criticality:
- * 
+ *
  *    PROPAGATING (throws on error):
  *    - Core data functions: getPostgresVersion, getSettings, getAlteredSettings,
  *      getDatabaseSizes, getInvalidIndexes, getUnusedIndexes, getRedundantIndexes
  *    - If these fail, the entire report should fail (data is required)
  *    - Callers should handle errors at the report generation level
- * 
+ *
  *    GRACEFUL DEGRADATION (catches errors, includes error in output):
  *    - Optional/supplementary queries: pg_stat_statements, pg_stat_kcache checks,
  *      memory calculations, postmaster startup time
  *    - These are nice-to-have; missing data shouldn't fail the whole report
  *    - Errors are logged and included in report output for visibility
- * 
+ *
  * ADDING NEW REPORTS
  * ------------------
  * 1. Add/verify the metric exists in config/pgwatch-prometheus/metrics.yml
@@ -51,7 +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";
+import { buildCheckInfoMap } from "./checkup-dictionary";
 
 // Time constants
 const SECONDS_PER_DAY = 86400;
@@ -243,6 +243,50 @@ export interface RedundantIndex {
   redundant_to_parse_error?: string;
 }
 
+/**
+ * I/O statistics by backend type (I001) - matches I001.schema.json backendIOStats
+ */
+export interface BackendIOStats {
+  backend_type: string;
+  reads: number;
+  /** Read MiB. The historical `_mb` suffix is retained for schema compatibility. */
+  read_bytes_mb: number;
+  read_time_ms: number;
+  writes: number;
+  /** Written MiB. The historical `_mb` suffix is retained for schema compatibility. */
+  write_bytes_mb: number;
+  write_time_ms: number;
+  writebacks: number;
+  /** Writeback MiB. The historical `_mb` suffix is retained for schema compatibility. */
+  writeback_bytes_mb: number;
+  writeback_time_ms: number;
+  fsyncs: number;
+  fsync_time_ms: number;
+  /** Relation extension operations reported by pg_stat_io for PostgreSQL 16+. */
+  extends?: number;
+  /** Extended MiB; PG16 derives extends * op_bytes, PG18+ uses native extend_bytes. */
+  extend_bytes_mb?: number;
+  hits: number;
+  evictions: number;
+  reuses: number;
+}
+
+/**
+ * I/O statistics analysis summary (I001)
+ */
+export interface IOAnalysis {
+  total_read_mb: number;
+  total_write_mb: number;
+  /** read_time_ms + write_time_ms across backends. Excludes writeback and fsync time. */
+  total_io_time_ms: number;
+  /** Buffer hit ratio: hits / (hits + reads) * 100. */
+  read_hit_ratio_pct: number;
+  /** Average read latency, or null when there are no reads. */
+  avg_read_time_ms: number | null;
+  /** Average write latency, or null when there are no writes. */
+  avg_write_time_ms: number | null;
+}
+
 /**
  * Node result for reports
  */
@@ -284,7 +328,7 @@ export function parseVersionNum(versionNum: string): { major: string; minor: str
   } catch (err) {
     // parseInt shouldn't throw, but handle edge cases defensively
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[parseVersionNum] Warning: Failed to parse "${versionNum}": ${errorMsg}`);
+    console.error(`[parseVersionNum] Warning: Failed to parse "${versionNum}": ${errorMsg}`);
     return { major: "", minor: "" };
   }
 }
@@ -292,7 +336,7 @@ export function parseVersionNum(versionNum: string): { major: string; minor: str
 /**
  * Format bytes to human readable string using binary units (1024-based).
  * Uses IEC standard: KiB, MiB, GiB, etc.
- * 
+ *
  * Note: PostgreSQL's pg_size_pretty() uses kB/MB/GB with 1024 base (technically
  * incorrect SI usage), but we follow IEC binary units per project style guide.
  */
@@ -343,7 +387,7 @@ function formatSettingPrettyValue(
 /**
  * Get PostgreSQL version information.
  * Uses simple inline SQL (trivial query, CLI-specific).
- * 
+ *
  * @throws {Error} If database query fails (propagating - critical data)
  */
 export async function getPostgresVersion(client: Client): Promise<PostgresVersion> {
@@ -729,7 +773,7 @@ export async function getStatsReset(client: Client, pgMajorVersion: number = 16)
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
     postmasterStartupError = `Failed to query postmaster start time: ${errorMsg}`;
-    console.log(`[getStatsReset] Warning: ${postmasterStartupError}`);
+    console.error(`[getStatsReset] Warning: ${postmasterStartupError}`);
   }
   
   const statsResult: StatsReset = {
@@ -811,7 +855,7 @@ export async function getRedundantIndexes(client: Client, pgMajorVersion: number
       const errorMsg = err instanceof Error ? err.message : String(err);
       const indexName = String(transformed.index_name || "unknown");
       parseError = `Failed to parse redundant_to_json: ${errorMsg}`;
-      console.log(`[H004] Warning: ${parseError} for index "${indexName}"`);
+      console.error(`[H004] Warning: ${parseError} for index "${indexName}"`);
     }
     
     const result: RedundantIndex = {
@@ -905,7 +949,7 @@ function resolveBuildTs(): string | null {
     // package.json not found is expected in some environments (e.g., bundled) - debug only
     if (process.env.DEBUG) {
       const errorMsg = err instanceof Error ? err.message : String(err);
-      console.log(`[resolveBuildTs] Could not stat package.json, using current time: ${errorMsg}`);
+      console.error(`[resolveBuildTs] Could not stat package.json, using current time: ${errorMsg}`);
     }
     return new Date().toISOString();
   }
@@ -1040,7 +1084,7 @@ export const generateH004 = (client: Client, nodeName = "node-01") =>
 
 /**
  * Generate D004 report - pg_stat_statements and pg_stat_kcache settings.
- * 
+ *
  * Uses graceful degradation: extension queries are wrapped in try-catch
  * because extensions may not be installed. Errors are included in the
  * report output rather than failing the entire report.
@@ -1103,7 +1147,7 @@ async function generateD004(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[D004] Error querying pg_stat_statements: ${errorMsg}`);
+    console.error(`[D004] Error querying pg_stat_statements: ${errorMsg}`);
     pgssError = errorMsg;
   }
 
@@ -1156,7 +1200,7 @@ async function generateD004(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[D004] Error querying pg_stat_kcache: ${errorMsg}`);
+    console.error(`[D004] Error querying pg_stat_kcache: ${errorMsg}`);
     kcacheError = errorMsg;
   }
 
@@ -1324,7 +1368,10 @@ async function generateF004(client: Client, nodeName: string): Promise<Report> {
     });
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[F004] Error estimating table bloat: ${errorMsg}`);
+    console.error(`[F004] Error estimating table bloat: ${errorMsg}`);
+    if (errorMsg.includes("postgres_ai.")) {
+      console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
+    }
   }
 
   // Get database info
@@ -1439,7 +1486,10 @@ async function generateF005(client: Client, nodeName: string): Promise<Report> {
     });
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[F005] Error estimating index bloat: ${errorMsg}`);
+    console.error(`[F005] Error estimating index bloat: ${errorMsg}`);
+    if (errorMsg.includes("postgres_ai.")) {
+      console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
+    }
   }
 
   // Get database info
@@ -1564,7 +1614,7 @@ async function generateG001(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[G001] Error calculating memory usage: ${errorMsg}`);
+    console.error(`[G001] Error calculating memory usage: ${errorMsg}`);
     memoryError = errorMsg;
   }
 
@@ -1642,7 +1692,7 @@ async function generateG003(client: Client, nodeName: string): Promise<Report> {
     }
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
-    console.log(`[G003] Error querying deadlock stats: ${errorMsg}`);
+    console.error(`[G003] Error querying deadlock stats: ${errorMsg}`);
     deadlockError = errorMsg;
   }
 
@@ -1658,6 +1708,186 @@ async function generateG003(client: Client, nodeName: string): Promise<Report> {
   return report;
 }
 
+/**
+ * Get I/O statistics from pg_stat_io (PostgreSQL 16+).
+ * Uses 'pg_stat_io' metric from metrics.yml.
+ *
+ * @param client - Connected PostgreSQL client
+ * @param pgMajorVersion - PostgreSQL major version; defaults to 0 so omitted versions return unavailable
+ * @param metricSqlOverride - Optional SQL override; empty or placeholder SQL returns [] without querying
+ * @returns Array of I/O stats by backend type, or empty array if unavailable
+ */
+export async function getIOStatistics(
+  client: Client,
+  pgMajorVersion: number = 0,
+  metricSqlOverride?: string
+): Promise<BackendIOStats[]> {
+  // pg_stat_io requires PostgreSQL 16+
+  if (pgMajorVersion < 16) {
+    return [];
+  }
+
+  try {
+    const sql = metricSqlOverride ?? getMetricSql(METRIC_NAMES.I001, pgMajorVersion);
+    // Skip if metric returns empty/placeholder SQL
+    if (!sql || sql.trim().startsWith(";")) {
+      return [];
+    }
+
+    const result = await client.query(sql);
+    return result.rows.map((row) => {
+      const transformed = transformMetricRow(row);
+      return {
+        backend_type: String(transformed.backend_type || "unknown"),
+        reads: parseInt(String(transformed.reads || 0), 10),
+        read_bytes_mb: parseInt(String(transformed.read_bytes_mb || 0), 10),
+        read_time_ms: parseInt(String(transformed.read_time_ms || 0), 10),
+        writes: parseInt(String(transformed.writes || 0), 10),
+        write_bytes_mb: parseInt(String(transformed.write_bytes_mb || 0), 10),
+        write_time_ms: parseInt(String(transformed.write_time_ms || 0), 10),
+        writebacks: parseInt(String(transformed.writebacks || 0), 10),
+        writeback_bytes_mb: parseInt(String(transformed.writeback_bytes_mb || 0), 10),
+        writeback_time_ms: parseInt(String(transformed.writeback_time_ms || 0), 10),
+        fsyncs: parseInt(String(transformed.fsyncs || 0), 10),
+        fsync_time_ms: parseInt(String(transformed.fsync_time_ms || 0), 10),
+        extends: parseInt(String(transformed.extends || 0), 10),
+        extend_bytes_mb: parseInt(String(transformed.extend_bytes_mb || 0), 10),
+        hits: parseInt(String(transformed.hits || 0), 10),
+        evictions: parseInt(String(transformed.evictions || 0), 10),
+        reuses: parseInt(String(transformed.reuses || 0), 10),
+      };
+    });
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    console.log(`[I001] Error fetching I/O statistics: ${errorMsg}`);
+    return [];
+  }
+}
+
+/**
+ * Generate I001 report - I/O statistics (pg_stat_io)
+ *
+ * This report collects I/O statistics from pg_stat_io (PostgreSQL 16+),
+ * providing insights into read/write operations by backend type.
+ *
+ * @param client - Connected PostgreSQL client
+ * @param nodeName - Node name for the report payload
+ * @returns I001 report payload
+ */
+async function generateI001(client: Client, nodeName: string): Promise<Report> {
+  const report = createBaseReport("I001", "I/O statistics (pg_stat_io)", nodeName);
+  const postgresVersion = await getPostgresVersion(client);
+  const parsedPgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
+  const pgMajorVersion = Number.isFinite(parsedPgMajorVersion) ? parsedPgMajorVersion : 0;
+
+  // pg_stat_io requires PostgreSQL 16+
+  if (pgMajorVersion < 16) {
+    report.results[nodeName] = {
+      data: {
+        available: false,
+        min_version_required: "16",
+        by_backend_type: [],
+        analysis: {
+          total_read_mb: 0,
+          total_write_mb: 0,
+          total_io_time_ms: 0,
+          read_hit_ratio_pct: 0,
+          avg_read_time_ms: null,
+          avg_write_time_ms: null,
+        },
+        stats_reset_s: null,
+      },
+      postgres_version: postgresVersion,
+    };
+    return report;
+  }
+
+  const ioStats = await getIOStatistics(client, pgMajorVersion);
+
+  // Sort by backend_type, putting 'total' first if present
+  ioStats.sort((a, b) => {
+    if (a.backend_type === "total") return -1;
+    if (b.backend_type === "total") return 1;
+    return a.backend_type.localeCompare(b.backend_type);
+  });
+
+  // Find 'total' row for analysis, or sum all rows if not present
+  let totalStats = ioStats.find((s) => s.backend_type === "total");
+  if (!totalStats && ioStats.length > 0) {
+    totalStats = {
+      backend_type: "total",
+      reads: ioStats.reduce((sum, s) => sum + s.reads, 0),
+      read_bytes_mb: ioStats.reduce((sum, s) => sum + s.read_bytes_mb, 0),
+      read_time_ms: ioStats.reduce((sum, s) => sum + s.read_time_ms, 0),
+      writes: ioStats.reduce((sum, s) => sum + s.writes, 0),
+      write_bytes_mb: ioStats.reduce((sum, s) => sum + s.write_bytes_mb, 0),
+      write_time_ms: ioStats.reduce((sum, s) => sum + s.write_time_ms, 0),
+      writebacks: ioStats.reduce((sum, s) => sum + s.writebacks, 0),
+      writeback_bytes_mb: ioStats.reduce((sum, s) => sum + s.writeback_bytes_mb, 0),
+      writeback_time_ms: ioStats.reduce((sum, s) => sum + s.writeback_time_ms, 0),
+      fsyncs: ioStats.reduce((sum, s) => sum + s.fsyncs, 0),
+      fsync_time_ms: ioStats.reduce((sum, s) => sum + s.fsync_time_ms, 0),
+      extends: ioStats.reduce((sum, s) => sum + (s.extends || 0), 0),
+      extend_bytes_mb: ioStats.reduce((sum, s) => sum + (s.extend_bytes_mb || 0), 0),
+      hits: ioStats.reduce((sum, s) => sum + s.hits, 0),
+      evictions: ioStats.reduce((sum, s) => sum + s.evictions, 0),
+      reuses: ioStats.reduce((sum, s) => sum + s.reuses, 0),
+    };
+  }
+
+  // Calculate analysis
+  const totalReadMb = totalStats?.read_bytes_mb || 0;
+  const totalWriteMb = totalStats?.write_bytes_mb || 0;
+  const totalReadTime = totalStats?.read_time_ms || 0;
+  const totalWriteTime = totalStats?.write_time_ms || 0;
+  const totalIoTimeMs = totalReadTime + totalWriteTime;
+  const totalReads = totalStats?.reads || 0;
+  const totalWrites = totalStats?.writes || 0;
+  const totalHits = totalStats?.hits || 0;
+
+  // Hit ratio: hits / (hits + reads) * 100
+  const totalRequests = totalHits + totalReads;
+  const readHitRatioPct = totalRequests > 0 ? Math.round((totalHits / totalRequests) * 10000) / 100 : 0;
+
+  // Average times
+  const avgReadTimeMs = totalReads > 0 ? Math.round((totalReadTime / totalReads) * 1000) / 1000 : null;
+  const avgWriteTimeMs = totalWrites > 0 ? Math.round((totalWriteTime / totalWrites) * 1000) / 1000 : null;
+
+  // Direct-connect checkup queries stats_reset separately instead of reading it from pgwatch metrics.
+  let statsResetS: number | null = null;
+  try {
+    const resetResult = await client.query(`
+      select max(extract(epoch from now() - stats_reset)::int) as stats_reset_s
+      from pg_stat_io
+    `);
+    if (resetResult.rows.length > 0 && resetResult.rows[0].stats_reset_s !== null) {
+      const parsedStatsResetS = parseInt(resetResult.rows[0].stats_reset_s, 10);
+      statsResetS = Number.isFinite(parsedStatsResetS) ? parsedStatsResetS : null;
+    }
+  } catch (err) {
+    // Ignore errors getting stats_reset - not critical
+  }
+
+  report.results[nodeName] = {
+    data: {
+      available: ioStats.length > 0,
+      by_backend_type: ioStats,
+      analysis: {
+        total_read_mb: totalReadMb,
+        total_write_mb: totalWriteMb,
+        total_io_time_ms: totalIoTimeMs,
+        read_hit_ratio_pct: readHitRatioPct,
+        avg_read_time_ms: avgReadTimeMs,
+        avg_write_time_ms: avgWriteTimeMs,
+      },
+      stats_reset_s: statsResetS,
+    },
+    postgres_version: postgresVersion,
+  };
+
+  return report;
+}
+
 /**
  * Available report generators
  */
@@ -1677,6 +1907,7 @@ export const REPORT_GENERATORS: Record<string, (client: Client, nodeName: string
   H001: generateH001,
   H002: generateH002,
   H004: generateH004,
+  I001: generateI001,
 };
 
 /**

package/lib/config.ts

@@ -8,6 +8,7 @@ import * as os from "os";
 export interface Config {
   apiKey: string | null;
   baseUrl: string | null;
+  storageBaseUrl: string | null;
   orgId: number | null;
   defaultProject: string | null;
   /** Docker Compose project name for monitoring stack */
@@ -48,6 +49,7 @@ export function readConfig(): Config {
   const config: Config = {
     apiKey: null,
     baseUrl: null,
+    storageBaseUrl: null,
     orgId: null,
     defaultProject: null,
     projectName: null,
@@ -61,6 +63,7 @@ export function readConfig(): Config {
       const parsed = JSON.parse(content);
       config.apiKey = parsed.apiKey ?? null;
       config.baseUrl = parsed.baseUrl ?? null;
+      config.storageBaseUrl = parsed.storageBaseUrl ?? null;
       config.orgId = parsed.orgId ?? null;
       config.defaultProject = parsed.defaultProject ?? null;
       config.projectName = parsed.projectName ?? null;