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

package/test/compose-cmd.test.ts

@@ -0,0 +1,120 @@
+import { describe, test, expect } from "bun:test";
+
+/**
+ * Test getComposeCmd() selection logic.
+ * WARNING: This replicates the logic from postgres-ai.ts. If the production
+ * function changes, this replica must be updated to match.
+ * Since the function is internal to postgres-ai.ts, we replicate its logic
+ * with an injectable command checker (same pattern as monitoring.test.ts).
+ */
+function getComposeCmd(
+  tryCmd: (cmd: string, args: string[]) => boolean,
+): string[] | null {
+  if (tryCmd("docker", ["compose", "version"])) return ["docker", "compose"];
+  if (tryCmd("docker-compose", ["version"])) return ["docker-compose"];
+  return null;
+}
+
+describe("getComposeCmd", () => {
+  test("prefers docker compose V2 when both are available", () => {
+    const result = getComposeCmd(() => true);
+    expect(result).toEqual(["docker", "compose"]);
+  });
+
+  test("falls back to docker-compose V1 when V2 is unavailable", () => {
+    const result = getComposeCmd((cmd, args) => {
+      // V2 plugin fails, V1 standalone succeeds
+      if (cmd === "docker" && args[0] === "compose") return false;
+      if (cmd === "docker-compose") return true;
+      return false;
+    });
+    expect(result).toEqual(["docker-compose"]);
+  });
+
+  test("returns null when neither is available", () => {
+    const result = getComposeCmd(() => false);
+    expect(result).toBeNull();
+  });
+
+  test("does not check V1 when V2 succeeds", () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    getComposeCmd((cmd, args) => {
+      calls.push({ cmd, args });
+      return cmd === "docker" && args[0] === "compose";
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toEqual({ cmd: "docker", args: ["compose", "version"] });
+  });
+
+  test("checks V2 first, then V1", () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    getComposeCmd((cmd, args) => {
+      calls.push({ cmd, args });
+      return false;
+    });
+    expect(calls).toHaveLength(2);
+    expect(calls[0]).toEqual({ cmd: "docker", args: ["compose", "version"] });
+    expect(calls[1]).toEqual({ cmd: "docker-compose", args: ["version"] });
+  });
+});
+
+/**
+ * Test the monitoring startup sequence's container cleanup logic.
+ * Before "up --force-recreate", stopped containers from "run --rm" dependencies
+ * (e.g. config-init) must be removed to avoid docker-compose v1's
+ * KeyError: 'ContainerConfig' bug.
+ *
+ * We replicate the relevant sequence from the monitoring start command
+ * with an injectable runCompose to verify ordering and error tolerance.
+ */
+async function monitoringStartSequence(
+  runCompose: (args: string[]) => Promise<number>,
+): Promise<number> {
+  // Best-effort: remove stopped containers left by "run --rm" dependencies
+  await runCompose(["rm", "-f", "-s", "config-init"]);
+  // Start services
+  const code = await runCompose(["up", "-d", "--force-recreate"]);
+  return code;
+}
+
+describe("monitoring start: config-init cleanup", () => {
+  test("calls rm before up", async () => {
+    const calls: string[][] = [];
+    await monitoringStartSequence(async (args) => {
+      calls.push(args);
+      return 0;
+    });
+    expect(calls).toHaveLength(2);
+    expect(calls[0]).toEqual(["rm", "-f", "-s", "config-init"]);
+    expect(calls[1]).toEqual(["up", "-d", "--force-recreate"]);
+  });
+
+  test("continues to up even when rm fails", async () => {
+    const calls: string[][] = [];
+    await monitoringStartSequence(async (args) => {
+      calls.push(args);
+      // rm returns non-zero (container doesn't exist)
+      if (args[0] === "rm") return 1;
+      return 0;
+    });
+    expect(calls).toHaveLength(2);
+    expect(calls[0][0]).toBe("rm");
+    expect(calls[1][0]).toBe("up");
+  });
+
+  test("returns up exit code, not rm exit code", async () => {
+    // rm fails but up succeeds → overall success
+    const result1 = await monitoringStartSequence(async (args) => {
+      if (args[0] === "rm") return 1;
+      return 0;
+    });
+    expect(result1).toBe(0);
+
+    // rm succeeds but up fails → overall failure
+    const result2 = await monitoringStartSequence(async (args) => {
+      if (args[0] === "up") return 2;
+      return 0;
+    });
+    expect(result2).toBe(2);
+  });
+});

package/test/config-consistency.test.ts

@@ -3,10 +3,127 @@
  * Catches schema mismatches like pg_statistic in wrong schema.
  */
 import { describe, test, expect } from "bun:test";
-import { readFileSync } from "fs";
+import { readdirSync, readFileSync } from "fs";
 import { resolve } from "path";
 
+type PgwatchConfig = {
+  metrics: Record<string, unknown>;
+  presets?: Record<string, { metrics?: Record<string, unknown> }>;
+};
+
+type GrafanaDatasource = {
+  name?: unknown;
+  orgId?: unknown;
+  uid?: unknown;
+  editable?: unknown;
+  basicAuth?: unknown;
+};
+
+type GrafanaDatasourceConfig = {
+  deleteDatasources?: Array<{ name?: unknown; orgId?: unknown }>;
+  datasources?: GrafanaDatasource[];
+};
+
+type DockerComposeConfig = {
+  services?: Record<string, { restart?: unknown }>;
+};
+
+// These UIDs are referenced by provisioned Grafana dashboards.
+// Changing them without updating dashboard JSON silently breaks panels.
+const expectedGrafanaDatasourceUids = new Map([
+  ["PGWatch-PostgreSQL", "P031DD592934B2F1F"],
+  ["PGWatch-Prometheus", "P7A0D6631BB10B34F"],
+  ["Infinity", "aerffb0z8rjlsc"],
+]);
+
+/**
+ * Normalizes raw Grafana datasource orgId values to a positive integer.
+ *
+ * Grafana treats omitted/null orgId as org 1 in the default single-org setup.
+ * Numeric strings are accepted because YAML or API callers may preserve them
+ * as strings. Booleans, objects, empty strings, non-positive values, and
+ * non-integers are rejected because Grafana cannot address those orgs.
+ */
+const normalizeGrafanaOrgId = (orgId: unknown) => {
+  if (orgId === undefined || orgId === null) {
+    return 1;
+  }
+  if (typeof orgId === "boolean" || typeof orgId === "object" || orgId === "") {
+    throw new Error(`Invalid Grafana datasource orgId: ${orgId}`);
+  }
+
+  const normalizedOrgId = Number(orgId);
+  if (!Number.isInteger(normalizedOrgId) || normalizedOrgId < 1) {
+    throw new Error(`Invalid Grafana datasource orgId: ${orgId}`);
+  }
+  return normalizedOrgId;
+};
+
+// Normalize orgId so omitted/null orgId and explicit orgId: 1 map to the same
+// datasource key, matching Grafana's implicit single-org behavior.
+const datasourceKey = (name: unknown, orgId: unknown) =>
+  `${name}:${normalizeGrafanaOrgId(orgId)}`;
+
 const configDir = resolve(import.meta.dir, "../../config");
+const metricsPath = resolve(configDir, "pgwatch-prometheus/metrics.yml");
+const datasourcePath = resolve(
+  configDir,
+  "grafana/provisioning/datasources/datasources.yml"
+);
+const composePath = resolve(import.meta.dir, "../../docker-compose.yml");
+const envExamplePath = resolve(import.meta.dir, "../../.env.example");
+const dashboardDir = resolve(configDir, "grafana/dashboards");
+const dashboardGeneratedMetricRefs = new Set([
+  // Exported by monitoring_flask_backend/app.py and joined into query dashboards.
+  "query_info",
+]);
+const pgwatchMetricRefPattern = /\bpgwatch_([a-zA-Z_:][a-zA-Z0-9_:]*)\b/g;
+
+const loadPgwatchConfig = () =>
+  Bun.YAML.parse(readFileSync(metricsPath, "utf8")) as PgwatchConfig;
+
+const parseGrafanaDatasourceConfig = (content: string) =>
+  Bun.YAML.parse(content) as GrafanaDatasourceConfig;
+
+const grafanaQueryStringKeys = new Set(["expr", "definition", "query"]);
+
+const collectStringValuesByKeys = (
+  value: unknown,
+  keys: Set<string>
+): string[] => {
+  const matches: string[] = [];
+
+  const visit = (node: unknown) => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item);
+      }
+      return;
+    }
+
+    if (node && typeof node === "object") {
+      const record = node as Record<string, unknown>;
+      for (const [recordKey, item] of Object.entries(record)) {
+        if (keys.has(recordKey) && typeof item === "string") {
+          matches.push(item);
+        }
+
+        visit(item);
+      }
+    }
+  };
+
+  visit(value);
+  return matches;
+};
+
+const resolveMetricReference = (
+  metricRef: string,
+  metricNamesByLength: string[]
+) =>
+  metricNamesByLength.find((metricName) =>
+    metricRef === metricName || metricRef.startsWith(`${metricName}_`)
+  );
 
 describe("Config consistency", () => {
   test("target-db/init.sql creates pg_statistic in postgres_ai schema", () => {
@@ -24,13 +141,212 @@ describe("Config consistency", () => {
   });
 
   test("pgwatch metrics.yml uses postgres_ai.pg_statistic", () => {
-    const metricsYml = readFileSync(
-      resolve(configDir, "pgwatch-prometheus/metrics.yml"),
-      "utf8"
-    );
+    const metricsYml = readFileSync(metricsPath, "utf8");
 
     // Should reference postgres_ai.pg_statistic, not public.pg_statistic
     expect(metricsYml).not.toMatch(/public\.pg_statistic/);
     expect(metricsYml).toMatch(/postgres_ai\.pg_statistic/);
   });
+
+  test("Grafana datasource YAML parser rejects malformed config", () => {
+    expect(() =>
+      parseGrafanaDatasourceConfig("apiVersion: 1\ndatasources:\n  - name: [")
+    ).toThrow();
+  });
+
+  test("Grafana orgId normalization rejects invalid values", () => {
+    for (const orgId of [undefined, null, 1, "1"]) {
+      expect(normalizeGrafanaOrgId(orgId)).toBe(1);
+    }
+    expect(normalizeGrafanaOrgId("2")).toBe(2);
+
+    for (const orgId of [
+      0,
+      -1,
+      true,
+      "",
+      1.5,
+      "0",
+      "-1",
+      "1.5",
+      "abc",
+      NaN,
+      Infinity,
+    ]) {
+      expect(() => normalizeGrafanaOrgId(orgId)).toThrow();
+    }
+  });
+
+  test("datasources.yml delete entries match stable non-editable datasources", () => {
+    const datasourceConfig = parseGrafanaDatasourceConfig(
+      readFileSync(datasourcePath, "utf8")
+    );
+    const deleteDatasources = datasourceConfig.deleteDatasources ?? [];
+    const datasources = datasourceConfig.datasources ?? [];
+    const deletedKeys = new Set(
+      deleteDatasources.map((datasource) =>
+        datasourceKey(datasource.name, datasource.orgId)
+      )
+    );
+    const datasourceByNameAndOrg = new Map(
+      datasources.map((datasource) => [
+        datasourceKey(datasource.name, datasource.orgId),
+        datasource,
+      ])
+    );
+
+    expect(deleteDatasources.length).toBeGreaterThan(0);
+    expect(deleteDatasources.length).toBe(datasources.length);
+    expect(datasourceByNameAndOrg.size).toBe(datasources.length);
+
+    for (const deletedDatasource of deleteDatasources) {
+      const datasource = datasourceByNameAndOrg.get(
+        datasourceKey(deletedDatasource.name, deletedDatasource.orgId)
+      );
+      const expectedUid = expectedGrafanaDatasourceUids.get(
+        String(deletedDatasource.name)
+      );
+      expect(datasource).toBeDefined();
+      expect(expectedUid).toBeDefined();
+      expect(datasource?.uid).toBe(expectedUid);
+      expect(datasource?.editable).toBe(false);
+    }
+
+    for (const datasource of datasources) {
+      const expectedUid = expectedGrafanaDatasourceUids.get(
+        String(datasource.name)
+      );
+      expect(deletedKeys.has(datasourceKey(datasource.name, datasource.orgId))).toBe(
+        true
+      );
+      expect(expectedUid).toBeDefined();
+      expect(datasource.uid).toBe(expectedUid);
+      expect(datasource.editable).toBe(false);
+    }
+  });
+
+  test("Grafana Prometheus datasource requires VM auth environment", () => {
+    const datasourceConfig = parseGrafanaDatasourceConfig(
+      readFileSync(datasourcePath, "utf8")
+    );
+    const composeYml = readFileSync(composePath, "utf8");
+    const prometheusDatasource = datasourceConfig.datasources?.find(
+      (datasource) => datasource.name === "PGWatch-Prometheus"
+    ) as
+      | {
+          basicAuth?: unknown;
+          basicAuthUser?: unknown;
+          secureJsonData?: { basicAuthPassword?: unknown };
+        }
+      | undefined;
+
+    expect(prometheusDatasource?.basicAuth).toBe(true);
+    expect(prometheusDatasource?.basicAuthUser).toBe("${VM_AUTH_USERNAME}");
+    expect(prometheusDatasource?.secureJsonData?.basicAuthPassword).toBe(
+      "${VM_AUTH_PASSWORD}"
+    );
+    expect(composeYml).toContain(
+      "VM_AUTH_USERNAME: ${VM_AUTH_USERNAME:?VM_AUTH_USERNAME is required for Grafana datasource provisioning}"
+    );
+    expect(composeYml).toContain(
+      "VM_AUTH_PASSWORD: ${VM_AUTH_PASSWORD:?VM_AUTH_PASSWORD is required for Grafana datasource provisioning}"
+    );
+  });
+
+  test(".env.example documents direct Docker Compose credentials", () => {
+    const envExample = readFileSync(envExamplePath, "utf8");
+
+    expect(envExample).toContain("REPLICATOR_PASSWORD=");
+    expect(envExample).toContain("VM_AUTH_USERNAME=vmauth");
+    expect(envExample).toContain("VM_AUTH_PASSWORD=");
+    expect(envExample).toContain("openssl rand -hex 32");
+    expect(envExample).toContain("openssl rand -base64 18");
+  });
+
+  test("long-running Docker Compose services survive host reboot", () => {
+    const composeConfig = Bun.YAML.parse(
+      readFileSync(composePath, "utf8")
+    ) as DockerComposeConfig;
+    const services = composeConfig.services ?? {};
+
+    // All services should survive host reboot unless they are one-shot setup jobs.
+    const oneShotServices = new Set(["config-init", "sources-generator"]);
+    const serviceEntries = Object.entries(services);
+
+    expect(serviceEntries.length).toBeGreaterThan(0);
+
+    for (const serviceName of oneShotServices) {
+      expect(services[serviceName]).toBeDefined();
+      expect(services[serviceName]?.restart).toBeUndefined();
+    }
+
+    for (const [serviceName, serviceConfig] of serviceEntries) {
+      if (oneShotServices.has(serviceName)) {
+        continue;
+      }
+
+      expect(serviceConfig.restart).toBe("unless-stopped");
+    }
+  });
+
+  test("pgwatch presets only reference configured metrics", () => {
+    const pgwatchConfig = loadPgwatchConfig();
+    const metricNames = new Set(Object.keys(pgwatchConfig.metrics));
+    const presetNames = Object.keys(pgwatchConfig.presets ?? {});
+    const unknownPresetMetrics = new Set<string>();
+
+    expect(metricNames.size).toBeGreaterThan(0);
+    expect(presetNames.length).toBeGreaterThan(0);
+
+    for (const [presetName, preset] of Object.entries(pgwatchConfig.presets ?? {})) {
+      for (const metricName of Object.keys(preset.metrics ?? {})) {
+        if (!metricNames.has(metricName)) {
+          unknownPresetMetrics.add(`${presetName}.${metricName}`);
+        }
+      }
+    }
+
+    expect([...unknownPresetMetrics].sort()).toEqual([]);
+  });
+
+  test("Grafana dashboard pgwatch metric references exist in metrics.yml", () => {
+    const pgwatchConfig = loadPgwatchConfig();
+    const metricNamesByLength = Object.keys(pgwatchConfig.metrics).sort(
+      (a, b) => b.length - a.length
+    );
+    const dashboardFiles = readdirSync(dashboardDir).filter((file) =>
+      file.endsWith(".json")
+    );
+    const unknownDashboardMetrics = new Set<string>();
+    let observedDashboardMetricRefs = 0;
+
+    expect(metricNamesByLength.length).toBeGreaterThan(0);
+    expect(dashboardFiles.length).toBeGreaterThan(0);
+
+    for (const dashboardFile of dashboardFiles) {
+      const dashboard = JSON.parse(
+        readFileSync(resolve(dashboardDir, dashboardFile), "utf8")
+      );
+
+      for (const queryString of collectStringValuesByKeys(
+        dashboard,
+        grafanaQueryStringKeys
+      )) {
+        for (const match of queryString.matchAll(pgwatchMetricRefPattern)) {
+          observedDashboardMetricRefs += 1;
+          const metricRef = match[1];
+          if (dashboardGeneratedMetricRefs.has(metricRef)) {
+            continue;
+          }
+
+          if (!resolveMetricReference(metricRef, metricNamesByLength)) {
+            unknownDashboardMetrics.add(`${dashboardFile}: pgwatch_${metricRef}`);
+          }
+        }
+      }
+    }
+
+    expect(observedDashboardMetricRefs).toBeGreaterThan(0);
+    expect([...unknownDashboardMetrics].sort()).toEqual([]);
+  });
 });

package/test/init.integration.test.ts

@@ -10,6 +10,8 @@ import * as path from "path";
 import * as net from "net";
 import { Client } from "pg";
 
+const TEST_TIMEOUT = 30000; // 30 seconds
+
 function sqlLiteral(value: string): string {
   return `'${String(value).replace(/'/g, "''")}'`;
 }
@@ -215,7 +217,7 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     } finally {
       await pg.cleanup();
     }
-  }, { timeout: 15000 });
+  }, { timeout: TEST_TIMEOUT });
 
   test("requires explicit monitoring password in non-interactive mode", async () => {
     pg = await createTempPostgres();
@@ -239,7 +241,7 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     } finally {
       await pg.cleanup();
     }
-  }, { timeout: 15000 });
+  }, { timeout: TEST_TIMEOUT });
 
   test(
     "fixes slightly-off permissions idempotently",
@@ -296,21 +298,19 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
         await pg.cleanup();
       }
     },
-    { timeout: 15000 }
+    { timeout: TEST_TIMEOUT }
   );
 
-  test(
-    "reports nicely when lacking permissions",
-    async () => {
-      pg = await createTempPostgres();
+  test("reports nicely when lacking permissions", async () => {
+    pg = await createTempPostgres();
 
-      try {
-        // Create limited user that can connect but cannot create roles / grant.
-        const limitedPw = "limitedpw";
-        {
-          const c = new Client({ connectionString: pg.adminUri });
-          await c.connect();
-          await c.query(`do $$ begin
+    try {
+      // Create limited user that can connect but cannot create roles / grant.
+      const limitedPw = "limitedpw";
+      {
+        const c = new Client({ connectionString: pg.adminUri });
+        await c.connect();
+        await c.query(`do $$ begin
           if not exists (select 1 from pg_roles where rolname='limited') then
             begin
               create role limited login password ${sqlLiteral(limitedPw)};
@@ -323,18 +323,16 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
           await c.end();
         }
 
-        const limitedUri = `postgresql://limited:${limitedPw}@127.0.0.1:${pg.port}/testdb`;
-        const r = runCliInit([limitedUri, "--password", "monpw", "--skip-optional-permissions"]);
-        expect(r.status).not.toBe(0);
-        expect(r.stderr).toMatch(/Error: prepare-db:/);
-        expect(r.stderr).toMatch(/Failed at step "/);
-        expect(r.stderr).toMatch(/Fix: connect as a superuser/i);
-      } finally {
-        await pg.cleanup();
-      }
-    },
-    { timeout: 15000 }
-  );
+      const limitedUri = `postgresql://limited:${limitedPw}@127.0.0.1:${pg.port}/testdb`;
+      const r = runCliInit([limitedUri, "--password", "monpw", "--skip-optional-permissions"]);
+      expect(r.status).not.toBe(0);
+      expect(r.stderr).toMatch(/Error: prepare-db:/);
+      expect(r.stderr).toMatch(/Failed at step "/);
+      expect(r.stderr).toMatch(/Fix: connect as a superuser/i);
+    } finally {
+      await pg.cleanup();
+    }
+  }, { timeout: TEST_TIMEOUT });
 
   test(
     "--verify returns 0 when ok and non-zero when missing",
@@ -372,7 +370,8 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
       } finally {
         await pg.cleanup();
       }
-    }
+    },
+    { timeout: TEST_TIMEOUT }
   );
 
   // 15s timeout for PostgreSQL startup + two CLI init commands in slow CI
@@ -406,7 +405,7 @@ describe.skipIf(skipTests)("integration: prepare-db", () => {
     } finally {
       await pg.cleanup();
     }
-  }, { timeout: 15000 });
+  }, { timeout: TEST_TIMEOUT });
 
   // 60s timeout for PostgreSQL startup + multiple SQL queries in slow CI
   test("explain_generic validates input and prevents SQL injection", async () => {