Merge branch 'claude/add-index-definition-to-h001' into 'main'

feat(reporter): add index_definition to H001 invalid indexes report

See merge request postgres-ai/postgres_ai!134

Author: Dementii Priadko

cli/lib/checkup.ts

@@ -117,6 +117,8 @@ export interface InvalidIndex {
   relation_name: string;
   index_size_bytes: number;
   index_size_pretty: string;
+  /** Full CREATE INDEX statement from pg_get_indexdef(), useful for DROP/CREATE migrations */
+  index_definition: string;
   supports_fk: boolean;
 }
 
@@ -581,6 +583,7 @@ export async function getInvalidIndexes(client: Client, pgMajorVersion: number =
       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),
     };
   });

cli/test/checkup.integration.test.ts

@@ -253,6 +253,52 @@ 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 () => {
+    // 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);
+      CREATE INDEX IF NOT EXISTS test_invalid_idx ON test_invalid_idx_table(value);
+    `);
+
+    // Mark the index as invalid (simulating a failed CONCURRENTLY build)
+    await client.query(`
+      UPDATE pg_index SET indisvalid = false
+      WHERE indexrelid = 'test_invalid_idx'::regclass;
+    `);
+
+    try {
+      const report = await checkup.generateH001(client, "test-node");
+      validateAgainstSchema(report, "H001");
+
+      const nodeResult = report.results["test-node"];
+      const dbName = Object.keys(nodeResult.data)[0];
+      expect(dbName).toBeTruthy();
+
+      const dbData = nodeResult.data[dbName] as any;
+      expect(dbData.invalid_indexes).toBeDefined();
+      expect(dbData.invalid_indexes.length).toBeGreaterThan(0);
+
+      // Find our test index
+      const testIndex = dbData.invalid_indexes.find(
+        (idx: any) => idx.index_name === "test_invalid_idx"
+      );
+      expect(testIndex).toBeDefined();
+
+      // Verify index_definition contains the actual CREATE INDEX statement
+      expect(testIndex.index_definition).toMatch(/^CREATE INDEX/);
+      expect(testIndex.index_definition).toContain("test_invalid_idx");
+      expect(testIndex.index_definition).toContain("test_invalid_idx_table");
+    } finally {
+      // Cleanup: restore the index and drop test objects
+      await client.query(`
+        UPDATE pg_index SET indisvalid = true
+        WHERE indexrelid = 'test_invalid_idx'::regclass;
+        DROP INDEX IF EXISTS test_invalid_idx;
+        DROP TABLE IF EXISTS test_invalid_idx_table;
+      `);
+    }
+  });
+
   test("H002 (unused indexes) has correct data structure", async () => {
     const report = await checkup.generateH002(client, "test-node");
     validateAgainstSchema(report, "H002");

cli/test/checkup.test.ts

@@ -480,7 +480,7 @@ describe("H001 - Invalid indexes", () => {
   test("getInvalidIndexes returns invalid indexes", async () => {
     const mockClient = createMockClient({
       invalidIndexesRows: [
-        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", supports_fk: false },
+        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", index_definition: "CREATE INDEX users_email_idx ON public.users USING btree (email)", supports_fk: false },
       ],
     });
 
@@ -491,6 +491,7 @@ describe("H001 - Invalid indexes", () => {
     expect(indexes[0].index_name).toBe("users_email_idx");
     expect(indexes[0].index_size_bytes).toBe(1048576);
     expect(indexes[0].index_size_pretty).toBeTruthy();
+    expect(indexes[0].index_definition).toMatch(/^CREATE INDEX/);
     expect(indexes[0].relation_name).toBe("users");
     expect(indexes[0].supports_fk).toBe(false);
   });
@@ -502,7 +503,7 @@ describe("H001 - Invalid indexes", () => {
         { name: "server_version_num", setting: "160003" },
       ],
         invalidIndexesRows: [
-          { schema_name: "public", table_name: "orders", index_name: "orders_status_idx", relation_name: "orders", index_size_bytes: "2097152", supports_fk: false },
+          { schema_name: "public", table_name: "orders", index_name: "orders_status_idx", relation_name: "orders", index_size_bytes: "2097152", index_definition: "CREATE INDEX orders_status_idx ON public.orders USING btree (status)", supports_fk: false },
         ],
       }
     );

cli/test/schema-validation.test.ts

@@ -30,7 +30,7 @@ const indexTestData = {
     emptyRows: { invalidIndexesRows: [] },
     dataRows: {
       invalidIndexesRows: [
-        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", supports_fk: false },
+        { schema_name: "public", table_name: "users", index_name: "users_email_idx", relation_name: "users", index_size_bytes: "1048576", index_definition: "CREATE INDEX users_email_idx ON public.users USING btree (email)", supports_fk: false },
       ],
     },
   },

config/pgwatch-prometheus/metrics.yml

@@ -1604,6 +1604,7 @@ metrics:
             quote_ident(pci.relname) as tag_index_name,
             quote_ident(pct.relname) as tag_table_name,
             coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,
+            pg_get_indexdef(pidx.indexrelid) as index_definition,
             pg_relation_size(pidx.indexrelid) index_size_bytes,
             ((
               select count(1)

reporter/postgres_reports.py

@@ -622,6 +622,8 @@ def generate_h001_invalid_indexes_report(self, cluster: str = "local", node_name
 
         invalid_indexes_by_db = {}
         for db_name in databases:
+            # Fetch index definitions from the sink for this database (used to aid remediation)
+            index_definitions = self.get_index_definitions_from_sink(db_name)
             # Query invalid indexes for each database
             invalid_indexes_query = f'last_over_time(pgwatch_pg_invalid_indexes{{cluster="{cluster}", node_name="{node_name}", datname="{db_name}"}}[3h])'
             result = self.query_instant(invalid_indexes_query)
@@ -648,6 +650,7 @@ def generate_h001_invalid_indexes_report(self, cluster: str = "local", node_name
                         "relation_name": relation_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))
                     }
 
@@ -755,7 +758,7 @@ def generate_h002_unused_indexes_report(self, cluster: str = "local", node_name:
                         'result') else 0
 
                     # Get index definition from collected metrics
-                    index_definition = index_definitions.get(index_name, 'Definition not available')
+                    index_definition = index_definitions.get(index_name, "Definition not available")
 
                     index_data = {
                         "schema_name": schema_name,
@@ -885,7 +888,7 @@ def generate_h004_redundant_indexes_report(self, cluster: str = "local", node_na
                     for idx_name in [r.strip() for r in reason.split(',') if r.strip()]:
                         redundant_to.append({
                             "index_name": idx_name,
-                            "index_definition": index_definitions.get(idx_name, 'Definition not available'),
+                            "index_definition": index_definitions.get(idx_name, "Definition not available"),
                             "index_size_bytes": 0,
                             "index_size_pretty": "N/A"
                         })
@@ -901,7 +904,7 @@ def generate_h004_redundant_indexes_report(self, cluster: str = "local", node_na
                         "table_size_bytes": table_size_bytes,
                         "index_usage": index_usage,
                         "supports_fk": supports_fk,
-                        "index_definition": index_definitions.get(index_name, 'Definition not available'),
+                        "index_definition": index_definitions.get(index_name, "Definition not available"),
                         "index_size_pretty": self.format_bytes(index_size_bytes),
                         "table_size_pretty": self.format_bytes(table_size_bytes),
                         "redundant_to": redundant_to

reporter/schemas/H001.schema.json

@@ -49,6 +49,7 @@
         "relation_name",
         "index_size_bytes",
         "index_size_pretty",
+        "index_definition",
         "supports_fk"
       ],
       "properties": {
@@ -58,6 +59,7 @@
         "relation_name": { "type": "string" },
         "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" }
       }
     },

tests/reporter/test_generators_unit.py

@@ -467,6 +467,7 @@ def test_generate_h001_invalid_indexes_report(
     prom_result,
 ) -> None:
     monkeypatch.setattr(generator, "get_all_databases", lambda *args, **kwargs: ["maindb"])
+    monkeypatch.setattr(generator, "get_index_definitions_from_sink", lambda db: {"idx_invalid": "CREATE INDEX idx_invalid ON public.tbl USING btree (col)"})
 
     responses = {
         "pgwatch_pg_invalid_indexes": prom_result(
@@ -494,6 +495,7 @@ def test_generate_h001_invalid_indexes_report(
     entry = db_data["invalid_indexes"][0]
     assert entry["index_name"] == "idx_invalid"
     assert entry["index_size_pretty"].endswith("KiB")
+    assert entry["index_definition"].startswith("CREATE INDEX")
     assert entry["supports_fk"] is True
 
 

tests/reporter/test_report_schemas.py

@@ -358,6 +358,7 @@ def test_schema_h001(
 ) -> None:
     monkeypatch.setattr(generator, "_get_postgres_version_info", lambda *args, **kwargs: fixed_pg_version)
     monkeypatch.setattr(generator, "get_all_databases", lambda *args, **kwargs: ["maindb"])
+    monkeypatch.setattr(generator, "get_index_definitions_from_sink", lambda db: {"idx_invalid": "CREATE INDEX idx_invalid ON public.tbl USING btree (col)"})
     responses = {
         "pgwatch_db_size_size_b": prom_result([{"metric": {"datname": "maindb"}, "value": [0, "8192"]}]),
         "pgwatch_pg_invalid_indexes": prom_result(