postgresai 0.16.0-dev.10 → 0.16.0-dev.11

package/lib/checkup-summary.ts

@@ -41,6 +41,8 @@ export function generateCheckSummary(checkId: string, report: any): CheckSummary
     case 'D004': return summarizeD004(nodeData);
     case 'F001': return summarizeF001(nodeData);
     case 'F003': return summarizeF003(nodeData);
+    case 'F004': return summarizeBloat(nodeData, 'table');
+    case 'F005': return summarizeBloat(nodeData, 'index');
     case 'G001': return summarizeG001(nodeData);
     case 'G003': return summarizeG003(nodeData);
     default:
@@ -273,6 +275,29 @@ function summarizeF003(nodeData: any): CheckSummary {
   return { status: 'warning', message: parts.join(', ') };
 }
 
+function summarizeBloat(nodeData: any, kind: 'table' | 'index'): CheckSummary {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData as any;
+    if (dbEntry?.status?.ok === false) {
+      const reason = String(dbEntry.status.reason || 'query_error').replaceAll('_', ' ');
+      return { status: 'warning', message: `Bloat estimate degraded: ${reason}` };
+    }
+    totalCount += dbEntry?.total_count || 0;
+  }
+
+  if (totalCount === 0) {
+    return { status: 'ok', message: `No bloated ${kind}${kind === 'index' ? 'es' : 's'} found` };
+  }
+
+  return {
+    status: 'warning',
+    message: `Found ${totalCount} bloated ${kind}${totalCount === 1 ? '' : kind === 'index' ? 'es' : 's'}`,
+  };
+}
+
 function summarizeG001(nodeData: any): CheckSummary {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;

package/lib/checkup.ts

@@ -1498,6 +1498,74 @@ async function generateF003(client: Client, nodeName: string): Promise<Report> {
  * Uses pg_stats for column statistics to estimate row sizes.
  * SQL loaded from config/pgwatch-prometheus/metrics.yml (pg_table_bloat metric).
  */
+type BloatCheckReason = "missing_schema" | "missing_view" | "missing_grant" | "query_error";
+
+interface BloatCheckStatus {
+  ok: boolean;
+  reason: BloatCheckReason | null;
+  error: string | null;
+}
+
+function bloatErrorStatus(err: unknown): BloatCheckStatus {
+  const error = err instanceof Error ? err.message : String(err);
+  const code = typeof err === "object" && err !== null && "code" in err
+    ? String((err as { code?: unknown }).code || "")
+    : "";
+  const normalized = error.toLowerCase();
+
+  let reason: BloatCheckReason = "query_error";
+  if (code === "3F000" || normalized.includes('schema "postgres_ai" does not exist')) {
+    reason = "missing_schema";
+  } else if (code === "42P01" || normalized.includes('relation "postgres_ai.pg_statistic" does not exist')) {
+    reason = "missing_view";
+  } else if (code === "42501" || normalized.includes("permission denied")) {
+    reason = "missing_grant";
+  }
+
+  return { ok: false, reason, error };
+}
+
+async function getBloatCheckStatus(client: Client): Promise<BloatCheckStatus> {
+  try {
+    const result = await client.query(`
+      select
+        to_regnamespace('postgres_ai') is not null as schema_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as schema_usage,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as view_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          when to_regclass('postgres_ai.pg_statistic') is null then false
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'SELECT')
+        end as view_select
+    `);
+    const capability = result.rows[0] || {};
+
+    if (!capability.schema_exists) {
+      return { ok: false, reason: "missing_schema", error: 'schema "postgres_ai" does not exist' };
+    }
+    if (!capability.schema_usage) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for schema postgres_ai" };
+    }
+    if (!capability.view_exists) {
+      return { ok: false, reason: "missing_view", error: 'relation "postgres_ai.pg_statistic" does not exist' };
+    }
+    if (!capability.view_select) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for relation postgres_ai.pg_statistic" };
+    }
+    return { ok: true, reason: null, error: null };
+  } catch (err) {
+    return bloatErrorStatus(err);
+  }
+}
+
 async function generateF004(client: Client, nodeName: string): Promise<Report> {
   const report = createBaseReport("F004", "Autovacuum: heap bloat (estimated)", nodeName);
   const postgresVersion = await getPostgresVersion(client);
@@ -1520,8 +1588,15 @@ async function generateF004(client: Client, nodeName: string): Promise<Report> {
   }
 
   let bloatedTables: BloatedTable[] = [];
+  let status = await getBloatCheckStatus(client);
 
   try {
+    if (!status.ok) throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+      code: status.reason === "missing_schema" ? "3F000"
+        : status.reason === "missing_view" ? "42P01"
+        : status.reason === "missing_grant" ? "42501"
+        : undefined,
+    });
     // Get bloat data
     const sql = getMetricSql(METRIC_NAMES.F004, pgMajorVersion);
     const bloatResult = await client.query(sql);
@@ -1572,7 +1647,8 @@ async function generateF004(client: Client, nodeName: string): Promise<Report> {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     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.`);
@@ -1587,6 +1663,7 @@ async function generateF004(client: Client, nodeName: string): Promise<Report> {
   const totalBloatSizeBytes = bloatedTables.reduce((sum, t) => sum + t.bloat_size, 0);
 
   const dbEntry = {
+    status,
     bloated_tables: bloatedTables,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -1634,8 +1711,15 @@ async function generateF005(client: Client, nodeName: string): Promise<Report> {
   }
 
   let bloatedIndexes: BloatedIndex[] = [];
+  let status = await getBloatCheckStatus(client);
 
   try {
+    if (!status.ok) throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+      code: status.reason === "missing_schema" ? "3F000"
+        : status.reason === "missing_view" ? "42P01"
+        : status.reason === "missing_grant" ? "42501"
+        : undefined,
+    });
     // Get bloat data
     const sql = getMetricSql(METRIC_NAMES.F005, pgMajorVersion);
     const bloatResult = await client.query(sql);
@@ -1690,7 +1774,8 @@ async function generateF005(client: Client, nodeName: string): Promise<Report> {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     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.`);
@@ -1705,6 +1790,7 @@ async function generateF005(client: Client, nodeName: string): Promise<Report> {
   const totalBloatSizeBytes = bloatedIndexes.reduce((sum, idx) => sum + idx.bloat_size, 0);
 
   const dbEntry = {
+    status,
     bloated_indexes: bloatedIndexes,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,

package/lib/init.ts

@@ -1019,10 +1019,28 @@ export async function checkCurrentUserPermissions(
 
       union all
 
+      select
+        'postgres_ai schema exists' as permission_name,
+        'optional' as status,
+        to_regnamespace('postgres_ai') is not null as granted
+
+      union all
+
+      select
+        'usage on postgres_ai schema' as permission_name,
+        'optional' as status,
+        case
+          when to_regnamespace('postgres_ai') is null then null
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as granted
+
+      union all
+
       select
         'postgres_ai.pg_statistic view exists' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           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
@@ -1033,6 +1051,7 @@ export async function checkCurrentUserPermissions(
         'select on postgres_ai.pg_statistic' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           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')
@@ -1052,6 +1071,10 @@ export async function checkCurrentUserPermissions(
             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 schema exists' and granted = false then
+          '-- run postgresai prepare-db or create the postgres_ai schema and pg_statistic view manually'
+        when permission_name = 'usage on postgres_ai schema' and granted = false then
+          format('grant usage on schema postgres_ai to %I;', current_user)
         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
@@ -1097,6 +1120,12 @@ export function formatPermissionCheckMessages(result: PreflightPermissionResult)
   const errors: string[] = [];
 
   for (const row of result.missingOptional) {
+    if (row.permission_name === "postgres_ai schema exists") {
+      warnings.push(
+        "Warning: optional: postgres_ai schema not found — F004/F005 (bloat estimates) will be skipped; run prepare-db or create the view manually to enable them."
+      );
+      continue;
+    }
     const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
     warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
   }