postgresai 0.15.0-dev.1 → 0.15.0-dev.10

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.ts

@@ -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: "" };
   }
 }
@@ -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();
   }
@@ -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;

package/lib/init.ts

@@ -127,8 +127,10 @@ export async function connectWithSslFallback(
   verbose?: boolean
 ): Promise<{ client: PgClient; usedSsl: boolean }> {
   const tryConnect = async (config: PgClientConfig): Promise<PgClient> => {
-    const client = new ClientClass(config);
+    const client = new ClientClass({ ...config, connectionTimeoutMillis: 10_000 } as any);
     await client.connect();
+    // Set a default statement timeout to prevent runaway queries
+    await client.query("SET statement_timeout = '30s'");
     return client;
   };
 
@@ -149,7 +151,7 @@ export async function connectWithSslFallback(
     }
 
     if (verbose) {
-      console.log("SSL connection failed, retrying without SSL...");
+      console.error("SSL connection failed, retrying without SSL...");
     }
 
     // Retry without SSL
@@ -454,8 +456,18 @@ export function resolveAdminConnection(opts: {
   return { clientConfig: cfg, display: describePgConfig(cfg), sslFallbackEnabled: true };
 }
 
+/**
+ * Generate a cryptographically secure random password for the monitoring role.
+ *
+ * Encoding note — bytes vs output length:
+ *   - hex:      N bytes → 2N characters  (24 bytes → 48 hex chars)
+ *   - base64:   N bytes → ⌈4N/3⌉ chars   (24 bytes → 32 base64url chars, no padding)
+ *
+ * We use base64url (RFC 4648 §5) because it is shorter than hex and safe in URLs,
+ * connection strings, and shell variables without quoting.
+ */
 function generateMonitoringPassword(): string {
-  // URL-safe and easy to copy/paste; 24 bytes => 32 base64url chars (no padding).
+  // 24 random bytes → 32 base64url characters (no padding).
   // Note: randomBytes() throws on failure; we add a tiny sanity check for unexpected output.
   const password = randomBytes(24).toString("base64url");
   if (password.length < 30) {
@@ -659,6 +671,36 @@ export type VerifyInitResult = {
   missingOptional: string[];
 };
 
+/** A single permission check result from the preflight query. */
+export type PermissionCheckRow = {
+  permission_name: string;
+  status: "required" | "optional";
+  /**
+   * Whether the permission is granted.
+   * - `true`  — permission is granted
+   * - `false` — permission is explicitly denied
+   * - `null`  — check was skipped (e.g., object does not exist, so the privilege
+   *             check is inapplicable — such as SELECT on a view that hasn't been created)
+   */
+  granted: boolean | null;
+  fix_command: string | null;
+};
+
+/**
+ * Result of the preflight permission check for the current DB user.
+ *
+ * - `ok` is `true` when `missingRequired` is empty.
+ * - `rows` contains every check (for inspection / logging).
+ * - `missingRequired` / `missingOptional` are filtered subsets of `rows`
+ *   where the permission is not granted (`granted !== true`).
+ */
+export type PreflightPermissionResult = {
+  ok: boolean;
+  rows: PermissionCheckRow[];
+  missingRequired: PermissionCheckRow[];
+  missingOptional: PermissionCheckRow[];
+};
+
 export type UninitPlan = {
   monitoringUser: string;
   database: string;
@@ -813,7 +855,12 @@ export async function verifyInitSetup(params: {
       missingRequired.push("USAGE on schema postgres_ai");
     }
 
-    const viewExistsRes = await params.client.query("select to_regclass('postgres_ai.pg_statistic') is not null as ok");
+    const viewExistsRes = await params.client.query(`
+      select case
+        when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+        else to_regclass('postgres_ai.pg_statistic') is not null
+      end as ok
+    `);
     if (!viewExistsRes.rows?.[0]?.ok) {
       missingRequired.push("view postgres_ai.pg_statistic exists");
     } else {
@@ -936,4 +983,149 @@ export async function verifyInitSetup(params: {
   }
 }
 
+/**
+ * Check that the currently connected DB user has sufficient permissions for
+ * monitoring operations. Returns structured results with fix commands.
+ *
+ * Required permissions cause startup to fail; optional ones produce warnings.
+ *
+ * @param client  An already-connected PostgreSQL client.
+ * @returns       A {@link PreflightPermissionResult} with per-check rows and
+ *                filtered `missingRequired` / `missingOptional` arrays.
+ * @throws        Propagates database errors (network, permission denied on catalog
+ *                tables, timeout) to the caller.
+ */
+export async function checkCurrentUserPermissions(
+  client: PgClient
+): Promise<PreflightPermissionResult> {
+  const sql = `
+    with permission_checks as (
+      select
+        format('connect on database %I', current_database()) as permission_name,
+        'required' as status,
+        has_database_privilege(current_user, current_database(), 'connect') as granted
+
+      union all
+
+      select
+        'pg_monitor role membership' as permission_name,
+        'required' as status,
+        -- CASE guarantees evaluation order: pg_has_role() is only called if the
+        -- pg_monitor role exists, avoiding ERROR on PostgreSQL < 10 or when dropped.
+        case
+          when not exists (select from pg_roles where rolname = 'pg_monitor')
+          then false
+          else pg_has_role(current_user, 'pg_monitor', 'member')
+        end as granted
+
+      union all
+
+      select
+        'select on pg_catalog.pg_index' as permission_name,
+        'required' as status,
+        has_table_privilege(current_user, 'pg_catalog.pg_index', 'select') as granted
+
+      union all
+
+      select
+        'postgres_ai.pg_statistic view exists' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as granted
+
+      union all
+
+      select
+        'select on postgres_ai.pg_statistic' as permission_name,
+        'optional' as status,
+        case
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
+          when to_regclass('postgres_ai.pg_statistic') is null then null
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
+        end as granted
+    )
+    select
+      permission_name,
+      status,
+      granted,
+      case
+        when status = 'required' and not coalesce(granted, false) then
+          case
+            when permission_name like 'connect%' then
+              format('grant connect on database %I to %I;', current_database(), current_user)
+            when permission_name = 'pg_monitor role membership' then
+              format('grant pg_monitor to %I;', current_user)
+            when permission_name like 'select on pg_catalog.pg_index' then
+              format('grant select on pg_catalog.pg_index to %I;', current_user)
+          end
+        when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
+          '-- create postgres_ai.pg_statistic view (see setup script)'
+        when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
+          format('grant select on postgres_ai.pg_statistic to %I;', current_user)
+        else null
+      end as fix_command
+    from permission_checks
+    order by
+      case status when 'required' then 1 else 2 end,
+      permission_name;
+  `;
+
+  const res = await client.query(sql);
+  const rows: PermissionCheckRow[] = res.rows;
+
+  // Required: treat null (skipped) as not-granted — fail safe.
+  // Optional: only explicit false counts as missing; null means the check was
+  //           skipped (e.g., view doesn't exist) and is not actionable.
+  const missingRequired = rows.filter((r) => r.status === "required" && r.granted !== true);
+  const missingOptional = rows.filter((r) => r.status === "optional" && r.granted === false);
+
+  return {
+    ok: missingRequired.length === 0,
+    rows,
+    missingRequired,
+    missingOptional,
+  };
+}
+
+/**
+ * Format permission check results into user-facing error/warning lines.
+ *
+ * @returns An object with `warnings` (for optional misses), `errors` (for
+ *          required misses including fix SQL), and `failed` (whether required
+ *          permissions are missing).
+ */
+export function formatPermissionCheckMessages(result: PreflightPermissionResult): {
+  failed: boolean;
+  warnings: string[];
+  errors: string[];
+} {
+  const warnings: string[] = [];
+  const errors: string[] = [];
+
+  for (const row of result.missingOptional) {
+    const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
+    warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
+  }
 
+  if (!result.ok) {
+    errors.push("Error: the database user is missing required permissions.\n");
+    errors.push("Missing permissions:");
+    for (const row of result.missingRequired) {
+      errors.push(`  - ${row.permission_name}`);
+    }
+    const fixes = result.missingRequired
+      .map((r) => r.fix_command)
+      .filter(Boolean);
+    if (fixes.length > 0) {
+      errors.push("\nTo fix, run the following as a superuser:\n");
+      for (const fix of fixes) {
+        errors.push(`  ${fix}`);
+      }
+    }
+    errors.push("\nAlternatively, run 'postgresai prepare-db' to set up permissions automatically.");
+  }
+
+  return { failed: !result.ok, warnings, errors };
+}