feat(H001): add decision support fields and recommendations for invalid indexes

claude · claude · commit a668a770d004 · 2026-01-05T21:49:01.000Z
Extends H001 check with data to support the decision flowchart for invalid
index remediation:

- Add SQL fields: is_unique_constraint, is_primary_key, table_row_estimate,
  has_valid_covering_index
- Add recommendation object with action (drop/recreate/uncertain), reason, and SQL
- Decision logic:
  1. If valid index on same columns exists → DROP (duplicate)
  2. If backs UNIQUE/PK constraint → REINDEX INDEX CONCURRENTLY
  3. If table &lt; 10K rows → DROP INDEX CONCURRENTLY and monitor
  4. Otherwise → uncertain (needs RCA to check query patterns)
- All SQL commands use CONCURRENTLY to avoid blocking
- Updates both express (TypeScript CLI) and full (Python reporter) paths
diff --git a/cli/lib/checkup.ts b/cli/lib/checkup.ts
@@ -107,6 +107,18 @@ export interface ClusterMetric {
   description: string;
 }
 
+/**
+ * Recommendation for invalid index remediation (H001)
+ */
+export interface InvalidIndexRecommendation {
+  /** Recommended action: drop (safe to remove), recreate (use REINDEX INDEX CONCURRENTLY), or uncertain (needs additional RCA) */
+  action: "drop" | "recreate" | "uncertain";
+  /** Human-readable explanation for the recommendation */
+  reason: string;
+  /** SQL command to execute (DROP INDEX CONCURRENTLY or REINDEX INDEX CONCURRENTLY) */
+  sql?: string;
+}
+
 /**
  * Invalid index entry (H001) - matches H001.schema.json invalidIndex
  */
@@ -120,6 +132,16 @@ export interface InvalidIndex {
   /** Full CREATE INDEX statement from pg_get_indexdef(), useful for DROP/CREATE migrations */
   index_definition: string;
   supports_fk: boolean;
+  /** True if index backs a UNIQUE constraint */
+  is_unique_constraint: boolean;
+  /** True if index backs a PRIMARY KEY constraint */
+  is_primary_key: boolean;
+  /** Estimated number of rows in the table (from pg_class.reltuples) */
+  table_row_estimate: number;
+  /** True if a valid index exists on the same columns (duplicate) */
+  has_valid_covering_index: boolean;
+  /** Recommendation for handling this invalid index */
+  recommendation: InvalidIndexRecommendation;
 }
 
 /**
@@ -562,29 +584,104 @@ export async function getClusterInfo(client: Client, pgMajorVersion: number = 16
   return info;
 }
 
+/**
+ * Generate recommendation for an invalid index based on decision flowchart.
+ *
+ * Decision tree:
+ * 1. If valid index on same columns exists → DROP (it's a duplicate)
+ * 2. Else if backs UNIQUE or PK constraint → RECREATE
+ * 3. Else if table < 10K rows → DROP and monitor
+ * 4. Else → UNCERTAIN (need to investigate if queries filter on this column)
+ */
+function generateInvalidIndexRecommendation(
+  schemaName: string,
+  indexName: string,
+  hasValidCoveringIndex: boolean,
+  isUniqueConstraint: boolean,
+  isPrimaryKey: boolean,
+  tableRowEstimate: number
+): InvalidIndexRecommendation {
+  const qualifiedName = schemaName === "public"
+    ? `"${indexName}"`
+    : `"${schemaName}"."${indexName}"`;
+
+  // 1. Valid index on same columns exists → DROP (duplicate)
+  if (hasValidCoveringIndex) {
+    return {
+      action: "drop",
+      reason: "A valid index already exists on the same column(s). This invalid index is a duplicate and can be safely dropped.",
+      sql: `DROP INDEX CONCURRENTLY ${qualifiedName};`,
+    };
+  }
+
+  // 2. Backs UNIQUE or PK constraint → RECREATE
+  if (isUniqueConstraint || isPrimaryKey) {
+    const constraintType = isPrimaryKey ? "PRIMARY KEY" : "UNIQUE";
+    return {
+      action: "recreate",
+      reason: `This index backs a ${constraintType} constraint and must be recreated to restore constraint enforcement.`,
+      sql: `REINDEX INDEX CONCURRENTLY ${qualifiedName};`,
+    };
+  }
+
+  // 3. Small table (< 10K rows) → DROP and monitor
+  if (tableRowEstimate < 10000) {
+    return {
+      action: "drop",
+      reason: `The table has only ~${tableRowEstimate.toLocaleString()} rows. For small tables, it's safe to drop the invalid index and monitor query performance. If needed, recreate with REINDEX INDEX CONCURRENTLY.`,
+      sql: `DROP INDEX CONCURRENTLY ${qualifiedName};`,
+    };
+  }
+
+  // 4. Large table, no constraint → UNCERTAIN (need to investigate query patterns)
+  return {
+    action: "uncertain",
+    reason: `The table has ~${tableRowEstimate.toLocaleString()} rows. Additional investigation is needed to determine if queries filter on the indexed column(s). If queries depend on this index, use REINDEX INDEX CONCURRENTLY to recreate it. Otherwise, DROP INDEX CONCURRENTLY and monitor.`,
+  };
+}
+
 /**
  * Get invalid indexes from the database (H001).
  * Invalid indexes are indexes that failed to build (e.g., due to CONCURRENTLY failure).
  *
  * @param client - Connected PostgreSQL client
  * @param pgMajorVersion - PostgreSQL major version (default: 16)
- * @returns Array of invalid index entries with size and FK support info
+ * @returns Array of invalid index entries with size, FK support info, and remediation recommendation
  */
 export async function getInvalidIndexes(client: Client, pgMajorVersion: number = 16): Promise<InvalidIndex[]> {
   const sql = getMetricSql(METRIC_NAMES.H001, pgMajorVersion);
   const result = await client.query(sql);
   return result.rows.map((row) => {
     const transformed = transformMetricRow(row);
     const indexSizeBytes = parseInt(String(transformed.index_size_bytes || 0), 10);
+    const schemaName = String(transformed.schema_name || "");
+    const indexName = String(transformed.index_name || "");
+    const isUniqueConstraint = toBool(transformed.is_unique_constraint);
+    const isPrimaryKey = toBool(transformed.is_primary_key);
+    const tableRowEstimate = parseInt(String(transformed.table_row_estimate || 0), 10);
+    const hasValidCoveringIndex = toBool(transformed.has_valid_covering_index);
+
     return {
-      schema_name: String(transformed.schema_name || ""),
+      schema_name: schemaName,
       table_name: String(transformed.table_name || ""),
-      index_name: String(transformed.index_name || ""),
+      index_name: indexName,
       relation_name: String(transformed.relation_name || ""),
       index_size_bytes: indexSizeBytes,
       index_size_pretty: formatBytes(indexSizeBytes),
       index_definition: String(transformed.index_definition || ""),
       supports_fk: toBool(transformed.supports_fk),
+      is_unique_constraint: isUniqueConstraint,
+      is_primary_key: isPrimaryKey,
+      table_row_estimate: tableRowEstimate,
+      has_valid_covering_index: hasValidCoveringIndex,
+      recommendation: generateInvalidIndexRecommendation(
+        schemaName,
+        indexName,
+        hasValidCoveringIndex,
+        isUniqueConstraint,
+        isPrimaryKey,
+        tableRowEstimate
+      ),
     };
   });
 }
diff --git a/cli/test/checkup.integration.test.ts b/cli/test/checkup.integration.test.ts
@@ -255,7 +255,7 @@ describe.skipIf(!!skipReason)("checkup integration: express mode schema compatib
     expect(typeof nodeResult.data).toBe("object");
   });
 
-  test("H001 returns index_definition with CREATE INDEX statement", async () => {
+  test("H001 returns index_definition with CREATE INDEX statement and recommendation", async () => {
     // Create a table and an index, then mark the index as invalid
     await client.query(`
       CREATE TABLE IF NOT EXISTS test_invalid_idx_table (id serial PRIMARY KEY, value text);
@@ -290,6 +290,21 @@ describe.skipIf(!!skipReason)("checkup integration: express mode schema compatib
       expect(testIndex.index_definition).toMatch(/^CREATE INDEX/);
       expect(testIndex.index_definition).toContain("test_invalid_idx");
       expect(testIndex.index_definition).toContain("test_invalid_idx_table");
+
+      // Verify new decision support fields
+      expect(typeof testIndex.is_unique_constraint).toBe("boolean");
+      expect(typeof testIndex.is_primary_key).toBe("boolean");
+      expect(typeof testIndex.table_row_estimate).toBe("number");
+      expect(typeof testIndex.has_valid_covering_index).toBe("boolean");
+
+      // Verify recommendation object
+      expect(testIndex.recommendation).toBeDefined();
+      expect(["drop", "recreate", "uncertain"]).toContain(testIndex.recommendation.action);
+      expect(typeof testIndex.recommendation.reason).toBe("string");
+      // SQL is present for drop/recreate actions, absent for uncertain
+      if (testIndex.recommendation.action !== "uncertain") {
+        expect(testIndex.recommendation.sql).toMatch(/CONCURRENTLY/);
+      }
     } finally {
       // Cleanup: restore the index and drop test objects
       await client.query(`
diff --git a/config/pgwatch-prometheus/metrics.yml b/config/pgwatch-prometheus/metrics.yml
@@ -1575,6 +1575,7 @@ metrics:
       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.
+      Extended with decision-support fields: has_valid_covering_index, is_unique_constraint, is_primary_key, table_row_estimate.
     sqls:
       11: |
         with fk_indexes as ( /* pgwatch_generated */
@@ -1612,7 +1613,22 @@ metrics:
               where
                 fi.tag_fk_table_ref = pct.relname
                 and fi.tag_opclasses like (array_to_string(pidx.indclass, ', ') || '%')
-            ) > 0)::int as supports_fk
+            ) > 0)::int as supports_fk,
+            /* Decision support fields for invalid index remediation */
+            pidx.indisunique as is_unique_constraint,
+            pidx.indisprimary as is_primary_key,
+            pct.reltuples::bigint as table_row_estimate,
+            /* Check if there's a valid index covering the same columns */
+            exists(
+              select 1
+              from pg_index valid_idx
+              join pg_class valid_idx_class on valid_idx_class.oid = valid_idx.indexrelid
+              where valid_idx.indrelid = pidx.indrelid
+                and valid_idx.indisvalid = true
+                and valid_idx.indkey = pidx.indkey
+                and valid_idx.indclass = pidx.indclass
+                and valid_idx.indexrelid != pidx.indexrelid
+            )::int as has_valid_covering_index
           from pg_index pidx
           join pg_class as pci on pci.oid = pidx.indexrelid
           join pg_class as pct on pct.oid = pidx.indrelid
diff --git a/reporter/postgres_reports.py b/reporter/postgres_reports.py
@@ -596,17 +596,68 @@ def generate_a007_altered_settings_report(self, cluster: str = "local", node_nam
 
         return self.format_report_data("A007", altered_settings, node_name, postgres_version=self._get_postgres_version_info(cluster, node_name))
 
+    @staticmethod
+    def _generate_invalid_index_recommendation(
+        schema_name: str,
+        index_name: str,
+        has_valid_covering_index: bool,
+        is_unique_constraint: bool,
+        is_primary_key: bool,
+        table_row_estimate: int
+    ) -> Dict[str, Any]:
+        """
+        Generate recommendation for an invalid index based on decision flowchart.
+
+        Decision tree:
+        1. If valid index on same columns exists → DROP (it's a duplicate)
+        2. Else if backs UNIQUE or PK constraint → RECREATE
+        3. Else if table < 10K rows → DROP and monitor
+        4. Else → UNCERTAIN (need to investigate if queries filter on this column)
+        """
+        qualified_name = f'"{index_name}"' if schema_name == "public" else f'"{schema_name}"."{index_name}"'
+
+        # 1. Valid index on same columns exists → DROP (duplicate)
+        if has_valid_covering_index:
+            return {
+                "action": "drop",
+                "reason": "A valid index already exists on the same column(s). This invalid index is a duplicate and can be safely dropped.",
+                "sql": f"DROP INDEX CONCURRENTLY {qualified_name};"
+            }
+
+        # 2. Backs UNIQUE or PK constraint → RECREATE
+        if is_unique_constraint or is_primary_key:
+            constraint_type = "PRIMARY KEY" if is_primary_key else "UNIQUE"
+            return {
+                "action": "recreate",
+                "reason": f"This index backs a {constraint_type} constraint and must be recreated to restore constraint enforcement.",
+                "sql": f"REINDEX INDEX CONCURRENTLY {qualified_name};"
+            }
+
+        # 3. Small table (< 10K rows) → DROP and monitor
+        if table_row_estimate < 10000:
+            return {
+                "action": "drop",
+                "reason": f"The table has only ~{table_row_estimate:,} rows. For small tables, it's safe to drop the invalid index and monitor query performance. If needed, recreate with REINDEX INDEX CONCURRENTLY.",
+                "sql": f"DROP INDEX CONCURRENTLY {qualified_name};"
+            }
+
+        # 4. Large table, no constraint → UNCERTAIN (need to investigate query patterns)
+        return {
+            "action": "uncertain",
+            "reason": f"The table has ~{table_row_estimate:,} rows. Additional investigation is needed to determine if queries filter on the indexed column(s). If queries depend on this index, use REINDEX INDEX CONCURRENTLY to recreate it. Otherwise, DROP INDEX CONCURRENTLY and monitor."
+        }
+
     def generate_h001_invalid_indexes_report(self, cluster: str = "local", node_name: str = "node-01") -> Dict[
         str, Any]:
         """
         Generate H001 Invalid Indexes report.
-        
+
         Args:
             cluster: Cluster name
             node_name: Node name
-            
+
         Returns:
-            Dictionary containing invalid indexes information
+            Dictionary containing invalid indexes information with remediation recommendations
         """
         logger.info("Generating H001 Invalid Indexes report...")
 
@@ -647,6 +698,12 @@ def generate_h001_invalid_indexes_report(self, cluster: str = "local", node_name
                     index_size_bytes = float(item['value'][1]) if item.get('value') else 0
                     supports_fk = item['metric'].get('supports_fk', '0')
 
+                    # Decision support fields
+                    is_unique_constraint = bool(int(item['metric'].get('is_unique_constraint', '0')))
+                    is_primary_key = bool(int(item['metric'].get('is_primary_key', '0')))
+                    table_row_estimate = int(float(item['metric'].get('table_row_estimate', '0')))
+                    has_valid_covering_index = bool(int(item['metric'].get('has_valid_covering_index', '0')))
+
                     invalid_index = {
                         "schema_name": schema_name,
                         "table_name": table_name,
@@ -655,12 +712,24 @@ def generate_h001_invalid_indexes_report(self, cluster: str = "local", node_name
                         "index_size_bytes": index_size_bytes,
                         "index_size_pretty": self.format_bytes(index_size_bytes),
                         "index_definition": index_definitions.get(index_name, "Definition not available"),
-                        "supports_fk": bool(int(supports_fk))
+                        "supports_fk": bool(int(supports_fk)),
+                        "is_unique_constraint": is_unique_constraint,
+                        "is_primary_key": is_primary_key,
+                        "table_row_estimate": table_row_estimate,
+                        "has_valid_covering_index": has_valid_covering_index,
+                        "recommendation": self._generate_invalid_index_recommendation(
+                            schema_name,
+                            index_name,
+                            has_valid_covering_index,
+                            is_unique_constraint,
+                            is_primary_key,
+                            table_row_estimate
+                        )
                     }
 
                     invalid_indexes.append(invalid_index)
                     total_size += index_size_bytes
-            
+
             # Skip databases with no invalid indexes
             if not invalid_indexes:
                 continue
diff --git a/reporter/schemas/H001.schema.json b/reporter/schemas/H001.schema.json
@@ -39,6 +39,26 @@
         "server_minor_ver": { "type": "string" }
       }
     },
+    "recommendation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action", "reason"],
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["drop", "recreate", "uncertain"],
+          "description": "Recommended action: drop (safe to remove), recreate (use REINDEX INDEX CONCURRENTLY), or uncertain (needs additional RCA)"
+        },
+        "reason": {
+          "type": "string",
+          "description": "Human-readable explanation for the recommendation"
+        },
+        "sql": {
+          "type": "string",
+          "description": "SQL command to execute (DROP INDEX CONCURRENTLY or REINDEX INDEX CONCURRENTLY)"
+        }
+      }
+    },
     "invalidIndex": {
       "type": "object",
       "additionalProperties": false,
@@ -50,7 +70,12 @@
         "index_size_bytes",
         "index_size_pretty",
         "index_definition",
-        "supports_fk"
+        "supports_fk",
+        "is_unique_constraint",
+        "is_primary_key",
+        "table_row_estimate",
+        "has_valid_covering_index",
+        "recommendation"
       ],
       "properties": {
         "schema_name": { "type": "string" },
@@ -60,7 +85,12 @@
         "index_size_bytes": { "type": "number" },
         "index_size_pretty": { "type": "string" },
         "index_definition": { "type": "string", "description": "Full CREATE INDEX statement from pg_get_indexdef(), useful for DROP/CREATE migrations" },
-        "supports_fk": { "type": "boolean" }
+        "supports_fk": { "type": "boolean" },
+        "is_unique_constraint": { "type": "boolean", "description": "True if index backs a UNIQUE constraint" },
+        "is_primary_key": { "type": "boolean", "description": "True if index backs a PRIMARY KEY constraint" },
+        "table_row_estimate": { "type": "number", "description": "Estimated number of rows in the table (from pg_class.reltuples)" },
+        "has_valid_covering_index": { "type": "boolean", "description": "True if a valid index exists on the same columns (duplicate)" },
+        "recommendation": { "$ref": "#/$defs/recommendation" }
       }
     },
     "dbEntry": {
diff --git a/tests/reporter/test_generators_unit.py b/tests/reporter/test_generators_unit.py
diff --git a/tests/reporter/test_report_schemas.py b/tests/reporter/test_report_schemas.py
