postgresai 0.14.0-dev.53 → 0.14.0-dev.55

package/test/init.integration.test.ts

@@ -326,41 +326,44 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     }
   });
 
-  test("--verify returns 0 when ok and non-zero when missing", async () => {
-    pg = await createTempPostgres();
-
-    try {
-      // Prepare: run init
-      {
-        const r = runCliInit([pg.adminUri, "--password", "monpw", "--skip-optional-permissions"]);
-        expect(r.status).toBe(0);
+  test(
+    "--verify returns 0 when ok and non-zero when missing",
+    async () => {
+      pg = await createTempPostgres();
+
+      try {
+        // Prepare: run init
+        {
+          const r = runCliInit([pg.adminUri, "--password", "monpw", "--skip-optional-permissions"]);
+          expect(r.status).toBe(0);
+        }
+
+        // Verify should pass
+        {
+          const r = runCliInit([pg.adminUri, "--verify", "--skip-optional-permissions"]);
+          expect(r.status).toBe(0);
+          expect(r.stdout).toMatch(/prepare-db verify: OK/i);
+        }
+
+        // Break a required privilege and ensure verify fails
+        {
+          const c = new Client({ connectionString: pg.adminUri });
+          await c.connect();
+          await c.query("revoke select on pg_catalog.pg_index from public");
+          await c.query("revoke select on pg_catalog.pg_index from postgres_ai_mon");
+          await c.end();
+        }
+        {
+          const r = runCliInit([pg.adminUri, "--verify", "--skip-optional-permissions"]);
+          expect(r.status).not.toBe(0);
+          expect(r.stderr).toMatch(/prepare-db verify failed/i);
+          expect(r.stderr).toMatch(/pg_catalog\.pg_index/i);
+        }
+      } finally {
+        await pg.cleanup();
       }
-
-      // Verify should pass
-      {
-        const r = runCliInit([pg.adminUri, "--verify", "--skip-optional-permissions"]);
-        expect(r.status).toBe(0);
-        expect(r.stdout).toMatch(/prepare-db verify: OK/i);
-      }
-
-      // Break a required privilege and ensure verify fails
-      {
-        const c = new Client({ connectionString: pg.adminUri });
-        await c.connect();
-        await c.query("revoke select on pg_catalog.pg_index from public");
-        await c.query("revoke select on pg_catalog.pg_index from postgres_ai_mon");
-        await c.end();
-      }
-      {
-        const r = runCliInit([pg.adminUri, "--verify", "--skip-optional-permissions"]);
-        expect(r.status).not.toBe(0);
-        expect(r.stderr).toMatch(/prepare-db verify failed/i);
-        expect(r.stderr).toMatch(/pg_catalog\.pg_index/i);
-      }
-    } finally {
-      await pg.cleanup();
     }
-  });
+  );
 
   test("--reset-password updates the monitoring role login password", async () => {
     pg = await createTempPostgres();

package/test/schema-validation.test.ts

@@ -0,0 +1,81 @@
+/**
+ * JSON Schema validation tests for express checkup reports.
+ * Validates that generated reports match schemas in reporter/schemas/.
+ */
+import { describe, test, expect } from "bun:test";
+import { resolve } from "path";
+import { readFileSync } from "fs";
+import Ajv2020 from "ajv/dist/2020";
+
+import * as checkup from "../lib/checkup";
+import { createMockClient } from "./test-utils";
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const schemasDir = resolve(import.meta.dir, "../../reporter/schemas");
+
+function validateAgainstSchema(report: any, checkId: string): void {
+  const schemaPath = resolve(schemasDir, `${checkId}.schema.json`);
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  const validate = ajv.compile(schema);
+  const valid = validate(report);
+  if (!valid) {
+    const errors = validate.errors?.map(e => `${e.instancePath}: ${e.message}`).join(", ");
+    throw new Error(`${checkId} schema validation failed: ${errors}`);
+  }
+}
+
+// Test data for index reports
+const indexTestData = {
+  H001: {
+    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 },
+      ],
+    },
+  },
+  H002: {
+    emptyRows: { unusedIndexesRows: [] },
+    dataRows: {
+      unusedIndexesRows: [
+        { schema_name: "public", table_name: "logs", index_name: "logs_created_idx", index_definition: "CREATE INDEX logs_created_idx ON public.logs USING btree (created_at)", reason: "Never Used Indexes", idx_scan: "0", index_size_bytes: "8388608", idx_is_btree: true, supports_fk: false },
+      ],
+    },
+  },
+  H004: {
+    emptyRows: { redundantIndexesRows: [] },
+    dataRows: {
+      redundantIndexesRows: [
+        { schema_name: "public", table_name: "orders", index_name: "orders_user_id_idx", relation_name: "orders", access_method: "btree", reason: "public.orders_user_id_created_idx", index_size_bytes: "2097152", table_size_bytes: "16777216", index_usage: "0", supports_fk: false, index_definition: "CREATE INDEX orders_user_id_idx ON public.orders USING btree (user_id)", redundant_to_json: JSON.stringify([{ index_name: "public.orders_user_id_created_idx", index_definition: "CREATE INDEX ...", index_size_bytes: 1048576 }]) },
+      ],
+    },
+  },
+};
+
+describe("Schema validation", () => {
+  // Index health checks (H001, H002, H004) - test empty and with data
+  for (const [checkId, testData] of Object.entries(indexTestData)) {
+    const generator = checkup.REPORT_GENERATORS[checkId];
+
+    test(`${checkId} validates with empty data`, async () => {
+      const mockClient = createMockClient(testData.emptyRows);
+      const report = await generator(mockClient as any, "node-01");
+      validateAgainstSchema(report, checkId);
+    });
+
+    test(`${checkId} validates with sample data`, async () => {
+      const mockClient = createMockClient(testData.dataRows);
+      const report = await generator(mockClient as any, "node-01");
+      validateAgainstSchema(report, checkId);
+    });
+  }
+
+  // Settings reports (D004, F001, G001) - single test each
+  for (const checkId of ["D004", "F001", "G001"]) {
+    test(`${checkId} validates against schema`, async () => {
+      const mockClient = createMockClient();
+      const report = await checkup.REPORT_GENERATORS[checkId](mockClient as any, "node-01");
+      validateAgainstSchema(report, checkId);
+    });
+  }
+});

package/test/test-utils.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared test utilities for CLI tests.
+ */
+
+export interface MockClientOptions {
+  /** Database name returned by current_database() queries (default: "testdb") */
+  databaseName?: string;
+  /** Version rows for pg_settings version query (default: PG 16.3) */
+  versionRows?: any[];
+  settingsRows?: any[];
+  databaseSizesRows?: any[];
+  dbStatsRows?: any[];
+  connectionStatesRows?: any[];
+  uptimeRows?: any[];
+  invalidIndexesRows?: any[];
+  unusedIndexesRows?: any[];
+  redundantIndexesRows?: any[];
+}
+
+const DEFAULT_VERSION_ROWS = [
+  { name: "server_version", setting: "16.3" },
+  { name: "server_version_num", setting: "160003" },
+];
+
+const defaultSettingsRows = [
+  { tag_setting_name: "shared_buffers", tag_setting_value: "128MB", tag_unit: "", tag_category: "Resource Usage / Memory", tag_vartype: "string", is_default: 1, setting_normalized: null, unit_normalized: null },
+  { tag_setting_name: "work_mem", tag_setting_value: "4MB", tag_unit: "", tag_category: "Resource Usage / Memory", tag_vartype: "string", is_default: 1, setting_normalized: null, unit_normalized: null },
+  { tag_setting_name: "autovacuum", tag_setting_value: "on", tag_unit: "", tag_category: "Autovacuum", tag_vartype: "bool", is_default: 1, setting_normalized: null, unit_normalized: null },
+  { tag_setting_name: "pg_stat_statements.max", tag_setting_value: "5000", tag_unit: "", tag_category: "Custom", tag_vartype: "integer", is_default: 0, setting_normalized: null, unit_normalized: null },
+];
+
+/**
+ * Create a mock PostgreSQL client for testing report generators.
+ * Routes SQL queries to appropriate mock data based on query patterns.
+ */
+export function createMockClient(options: MockClientOptions = {}) {
+  const {
+    databaseName = "testdb",
+    versionRows = DEFAULT_VERSION_ROWS,
+    settingsRows = defaultSettingsRows,
+    databaseSizesRows = [],
+    dbStatsRows = [],
+    connectionStatesRows = [],
+    uptimeRows = [],
+    invalidIndexesRows = [],
+    unusedIndexesRows = [],
+    redundantIndexesRows = [],
+  } = options;
+
+  return {
+    query: async (sql: string) => {
+      // Version query (simple inline - used by getPostgresVersion)
+      if (sql.includes("server_version") && sql.includes("server_version_num") && sql.includes("pg_settings") && !sql.includes("tag_setting_name")) {
+        return { rows: versionRows };
+      }
+      // Settings metric query (from metrics.yml - has tag_setting_name, tag_setting_value)
+      if (sql.includes("tag_setting_name") && sql.includes("tag_setting_value") && sql.includes("pg_settings")) {
+        return { rows: settingsRows };
+      }
+      // Database sizes (simple inline - lists all databases)
+      if (sql.includes("pg_database") && sql.includes("pg_database_size") && sql.includes("datistemplate")) {
+        return { rows: databaseSizesRows };
+      }
+      // db_size metric (current database size from metrics.yml)
+      if (sql.includes("pg_database_size(current_database())") && sql.includes("size_b")) {
+        return { rows: [{ tag_datname: databaseName, size_b: "1073741824" }] };
+      }
+      // db_stats metric (from metrics.yml)
+      if (sql.includes("pg_stat_database") && sql.includes("xact_commit") && sql.includes("pg_control_system")) {
+        return { rows: dbStatsRows };
+      }
+      // Stats reset metric (from metrics.yml)
+      if (sql.includes("stats_reset") && sql.includes("pg_stat_database") && sql.includes("seconds_since_reset")) {
+        return { rows: [{ tag_database_name: databaseName, stats_reset_epoch: "1704067200", seconds_since_reset: "2592000" }] };
+      }
+      // Postmaster startup time (simple inline - used by getStatsReset)
+      if (sql.includes("pg_postmaster_start_time") && sql.includes("postmaster_startup_epoch")) {
+        return { rows: [{ postmaster_startup_epoch: "1704067200", postmaster_startup_time: "2024-01-01 00:00:00+00" }] };
+      }
+      // Connection states (simple inline)
+      if (sql.includes("pg_stat_activity") && sql.includes("state") && sql.includes("group by")) {
+        return { rows: connectionStatesRows };
+      }
+      // Uptime info (simple inline)
+      if (sql.includes("pg_postmaster_start_time()") && sql.includes("uptime") && !sql.includes("postmaster_startup_epoch")) {
+        return { rows: uptimeRows };
+      }
+      // Invalid indexes (H001) - from metrics.yml
+      if (sql.includes("indisvalid = false") && sql.includes("fk_indexes")) {
+        return { rows: invalidIndexesRows };
+      }
+      // Unused indexes (H002) - from metrics.yml
+      if (sql.includes("Never Used Indexes") && sql.includes("idx_scan = 0")) {
+        return { rows: unusedIndexesRows };
+      }
+      // Redundant indexes (H004) - from metrics.yml
+      if (sql.includes("redundant_indexes_grouped") && sql.includes("columns like")) {
+        return { rows: redundantIndexesRows };
+      }
+      // D004: pg_stat_statements extension check
+      if (sql.includes("pg_extension") && sql.includes("pg_stat_statements")) {
+        return { rows: [] };
+      }
+      // D004: pg_stat_kcache extension check
+      if (sql.includes("pg_extension") && sql.includes("pg_stat_kcache")) {
+        return { rows: [] };
+      }
+      // G001: Memory settings query
+      if (sql.includes("pg_size_bytes") && sql.includes("shared_buffers") && sql.includes("work_mem")) {
+        return { rows: [{
+          shared_buffers_bytes: "134217728",
+          wal_buffers_bytes: "4194304",
+          work_mem_bytes: "4194304",
+          maintenance_work_mem_bytes: "67108864",
+          effective_cache_size_bytes: "4294967296",
+          max_connections: 100,
+        }] };
+      }
+      throw new Error(`Unexpected query: ${sql}`);
+    },
+  };
+}

package/dist/sql/01.role.sql

@@ -1,16 +0,0 @@
--- Role creation / password update (template-filled by cli/lib/init.ts)
---
--- Always uses a race-safe pattern (create if missing, then always alter to set the password):
---   do $$ begin
---     if not exists (select 1 from pg_catalog.pg_roles where rolname = '...') then
---       begin
---         create user "..." with password '...';
---       exception when duplicate_object then
---         null;
---       end;
---     end if;
---     alter user "..." with password '...';
---   end $$;
-{{ROLE_STMT}}
-
-

package/dist/sql/02.permissions.sql

@@ -1,37 +0,0 @@
--- Required permissions for postgres_ai monitoring user (template-filled by cli/lib/init.ts)
-
--- Allow connect
-grant connect on database {{DB_IDENT}} to {{ROLE_IDENT}};
-
--- Standard monitoring privileges
-grant pg_monitor to {{ROLE_IDENT}};
-grant select on pg_catalog.pg_index to {{ROLE_IDENT}};
-
--- Create postgres_ai schema for our objects
-create schema if not exists postgres_ai;
-grant usage on schema postgres_ai to {{ROLE_IDENT}};
-
--- For bloat analysis: expose pg_statistic via a view
-create or replace view postgres_ai.pg_statistic as
-select
-    n.nspname as schemaname,
-    c.relname as tablename,
-    a.attname,
-    s.stanullfrac as null_frac,
-    s.stawidth as avg_width,
-    false as inherited
-from pg_catalog.pg_statistic s
-join pg_catalog.pg_class c on c.oid = s.starelid
-join pg_catalog.pg_namespace n on n.oid = c.relnamespace
-join pg_catalog.pg_attribute a on a.attrelid = s.starelid and a.attnum = s.staattnum
-where a.attnum > 0 and not a.attisdropped;
-
-grant select on postgres_ai.pg_statistic to {{ROLE_IDENT}};
-
--- Hardened clusters sometimes revoke PUBLIC on schema public
-grant usage on schema public to {{ROLE_IDENT}};
-
--- Keep search_path predictable; postgres_ai first so our objects are found
-alter user {{ROLE_IDENT}} set search_path = postgres_ai, "$user", public, pg_catalog;
-
-

package/dist/sql/03.optional_rds.sql

@@ -1,6 +0,0 @@
--- Optional permissions for RDS Postgres / Aurora (best effort)
-
-create extension if not exists rds_tools;
-grant execute on function rds_tools.pg_ls_multixactdir() to {{ROLE_IDENT}};
-
-

package/dist/sql/04.optional_self_managed.sql

@@ -1,8 +0,0 @@
--- Optional permissions for self-managed Postgres (best effort)
-
-grant execute on function pg_catalog.pg_stat_file(text) to {{ROLE_IDENT}};
-grant execute on function pg_catalog.pg_stat_file(text, boolean) to {{ROLE_IDENT}};
-grant execute on function pg_catalog.pg_ls_dir(text) to {{ROLE_IDENT}};
-grant execute on function pg_catalog.pg_ls_dir(text, boolean, boolean) to {{ROLE_IDENT}};
-
-