@checkstack/healthcheck-postgres-backend 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @checkstack/healthcheck-postgres-backend
 
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Refactored health check strategies to use `createClient()` pattern with built-in collectors.
+
+  **Strategy Changes:**
+
+  - Replaced `execute()` with `createClient()` that returns a transport client
+  - Strategy configs now only contain connection parameters
+  - Collector configs handle what to do with the connection
+
+  **Built-in Collectors Added:**
+
+  - DNS: `LookupCollector` for hostname resolution
+  - gRPC: `HealthCollector` for gRPC health protocol
+  - HTTP: `RequestCollector` for HTTP requests
+  - MySQL: `QueryCollector` for database queries
+  - Ping: `PingCollector` for ICMP ping
+  - Postgres: `QueryCollector` for database queries
+  - Redis: `CommandCollector` for Redis commands
+  - Script: `ExecuteCollector` for script execution
+  - SSH: `CommandCollector` for SSH commands
+  - TCP: `BannerCollector` for TCP banner grabbing
+  - TLS: `CertificateCollector` for certificate inspection
+
+### Patch Changes
+
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+  - @checkstack/backend-api@0.1.0
+  - @checkstack/healthcheck-common@0.1.0
+  - @checkstack/common@0.0.3
+
 ## 0.0.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-postgres-backend",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/index.ts

@@ -1,9 +1,7 @@
-import {
-  createBackendPlugin,
-  coreServices,
-} from "@checkstack/backend-api";
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { PostgresHealthCheckStrategy } from "./strategy";
 import { pluginMetadata } from "./plugin-metadata";
+import { QueryCollector } from "./query-collector";
 
 export default createBackendPlugin({
   metadata: pluginMetadata,
@@ -11,13 +9,17 @@ export default createBackendPlugin({
     env.registerInit({
       deps: {
         healthCheckRegistry: coreServices.healthCheckRegistry,
+        collectorRegistry: coreServices.collectorRegistry,
         logger: coreServices.logger,
       },
-      init: async ({ healthCheckRegistry, logger }) => {
+      init: async ({ healthCheckRegistry, collectorRegistry, logger }) => {
         logger.debug("🔌 Registering PostgreSQL Health Check Strategy...");
         const strategy = new PostgresHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
+        collectorRegistry.register(new QueryCollector());
       },
     });
   },
 });
+
+export { pluginMetadata } from "./plugin-metadata";

package/src/query-collector.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it, mock } from "bun:test";
+import { QueryCollector, type QueryConfig } from "./query-collector";
+import type { PostgresTransportClient } from "./transport-client";
+
+describe("QueryCollector", () => {
+  const createMockClient = (
+    response: {
+      rowCount?: number;
+      error?: string;
+    } = {}
+  ): PostgresTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        rowCount: response.rowCount ?? 1,
+        error: response.error,
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should execute query successfully", async () => {
+      const collector = new QueryCollector();
+      const client = createMockClient({ rowCount: 10 });
+
+      const result = await collector.execute({
+        config: { query: "SELECT * FROM users" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.rowCount).toBe(10);
+      expect(result.result.success).toBe(true);
+      expect(result.result.executionTimeMs).toBeGreaterThanOrEqual(0);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("should return error for failed query", async () => {
+      const collector = new QueryCollector();
+      const client = createMockClient({ error: "Relation does not exist" });
+
+      const result = await collector.execute({
+        config: { query: "SELECT * FROM nonexistent" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.success).toBe(false);
+      expect(result.error).toBe("Relation does not exist");
+    });
+
+    it("should pass query to client", async () => {
+      const collector = new QueryCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { query: "SELECT COUNT(*) FROM orders" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith({
+        query: "SELECT COUNT(*) FROM orders",
+      });
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average execution time and success rate", () => {
+      const collector = new QueryCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { rowCount: 1, executionTimeMs: 50, success: true },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { rowCount: 5, executionTimeMs: 100, success: true },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgExecutionTimeMs).toBe(75);
+      expect(aggregated.successRate).toBe(100);
+    });
+
+    it("should calculate success rate correctly", () => {
+      const collector = new QueryCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { rowCount: 1, executionTimeMs: 50, success: true },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { rowCount: 0, executionTimeMs: 100, success: false },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.successRate).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new QueryCollector();
+
+      expect(collector.id).toBe("query");
+      expect(collector.displayName).toBe("SQL Query");
+      expect(collector.allowMultiple).toBe(true);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/query-collector.ts

@@ -0,0 +1,141 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultBoolean,
+} from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "./plugin-metadata";
+import type { PostgresTransportClient } from "./transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const queryConfigSchema = z.object({
+  query: z.string().min(1).default("SELECT 1").describe("SQL query to execute"),
+});
+
+export type QueryConfig = z.infer<typeof queryConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const queryResultSchema = z.object({
+  rowCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Row Count",
+  }),
+  executionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Execution Time",
+    "x-chart-unit": "ms",
+  }),
+  success: healthResultBoolean({
+    "x-chart-type": "boolean",
+    "x-chart-label": "Success",
+  }),
+});
+
+export type QueryResult = z.infer<typeof queryResultSchema>;
+
+const queryAggregatedSchema = z.object({
+  avgExecutionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Execution Time",
+    "x-chart-unit": "ms",
+  }),
+  successRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Success Rate",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type QueryAggregatedResult = z.infer<typeof queryAggregatedSchema>;
+
+// ============================================================================
+// QUERY COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in PostgreSQL query collector.
+ * Executes SQL queries and checks results.
+ */
+export class QueryCollector
+  implements
+    CollectorStrategy<
+      PostgresTransportClient,
+      QueryConfig,
+      QueryResult,
+      QueryAggregatedResult
+    >
+{
+  id = "query";
+  displayName = "SQL Query";
+  description = "Execute a SQL query and check the result";
+
+  supportedPlugins = [pluginMetadata];
+
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: queryConfigSchema });
+  result = new Versioned({ version: 1, schema: queryResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: queryAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: QueryConfig;
+    client: PostgresTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<QueryResult>> {
+    const startTime = Date.now();
+
+    const response = await client.exec({ query: config.query });
+    const executionTimeMs = Date.now() - startTime;
+
+    return {
+      result: {
+        rowCount: response.rowCount,
+        executionTimeMs,
+        success: !response.error,
+      },
+      error: response.error,
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<QueryResult>[]
+  ): QueryAggregatedResult {
+    const times = runs
+      .map((r) => r.metadata?.executionTimeMs)
+      .filter((v): v is number => typeof v === "number");
+
+    const successes = runs
+      .map((r) => r.metadata?.success)
+      .filter((v): v is boolean => typeof v === "boolean");
+
+    const successCount = successes.filter(Boolean).length;
+
+    return {
+      avgExecutionTimeMs:
+        times.length > 0
+          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
+          : 0,
+      successRate:
+        successes.length > 0
+          ? Math.round((successCount / successes.length) * 100)
+          : 0,
+    };
+  }
+}

package/src/strategy.test.ts

@@ -24,11 +24,11 @@ describe("PostgresHealthCheckStrategy", () => {
     ),
   });
 
-  describe("execute", () => {
-    it("should return healthy for successful connection", async () => {
+  describe("createClient", () => {
+    it("should return a connected client for successful connection", async () => {
       const strategy = new PostgresHealthCheckStrategy(createMockClient());
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 5432,
         database: "test",
@@ -37,17 +37,35 @@ describe("PostgresHealthCheckStrategy", () => {
         timeout: 5000,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.connected).toBe(true);
-      expect(result.metadata?.querySuccess).toBe(true);
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
+
+      connectedClient.close();
     });
 
-    it("should return unhealthy for connection error", async () => {
+    it("should throw for connection error", async () => {
       const strategy = new PostgresHealthCheckStrategy(
         createMockClient({ connectError: new Error("Connection refused") })
       );
 
-      const result = await strategy.execute({
+      await expect(
+        strategy.createClient({
+          host: "localhost",
+          port: 5432,
+          database: "test",
+          user: "postgres",
+          password: "secret",
+          timeout: 5000,
+        })
+      ).rejects.toThrow("Connection refused");
+    });
+  });
+
+  describe("client.exec", () => {
+    it("should execute query successfully", async () => {
+      const strategy = new PostgresHealthCheckStrategy(createMockClient());
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 5432,
         database: "test",
@@ -56,17 +74,20 @@ describe("PostgresHealthCheckStrategy", () => {
         timeout: 5000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Connection refused");
-      expect(result.metadata?.connected).toBe(false);
+      const result = await connectedClient.client.exec({
+        query: "SELECT 1",
+      });
+
+      expect(result.rowCount).toBe(1);
+
+      connectedClient.close();
     });
 
-    it("should return unhealthy for query error", async () => {
+    it("should return error for query error", async () => {
       const strategy = new PostgresHealthCheckStrategy(
         createMockClient({ queryError: new Error("Syntax error") })
       );
-
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 5432,
         database: "test",
@@ -75,81 +96,35 @@ describe("PostgresHealthCheckStrategy", () => {
         timeout: 5000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.metadata?.querySuccess).toBe(false);
-    });
-
-    it("should pass connectionTime assertion when below threshold", async () => {
-      const strategy = new PostgresHealthCheckStrategy(createMockClient());
-
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 5432,
-        database: "test",
-        user: "postgres",
-        password: "secret",
-        timeout: 5000,
-        assertions: [
-          { field: "connectionTime", operator: "lessThan", value: 5000 },
-        ],
+      const result = await connectedClient.client.exec({
+        query: "INVALID SQL",
       });
 
-      expect(result.status).toBe("healthy");
+      expect(result.error).toContain("Syntax error");
+
+      connectedClient.close();
     });
 
-    it("should pass rowCount assertion", async () => {
+    it("should return custom row count", async () => {
       const strategy = new PostgresHealthCheckStrategy(
         createMockClient({ rowCount: 5 })
       );
-
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({
         host: "localhost",
         port: 5432,
         database: "test",
         user: "postgres",
         password: "secret",
         timeout: 5000,
-        assertions: [
-          { field: "rowCount", operator: "greaterThanOrEqual", value: 1 },
-        ],
       });
 
-      expect(result.status).toBe("healthy");
-    });
-
-    it("should fail rowCount assertion when no rows", async () => {
-      const strategy = new PostgresHealthCheckStrategy(
-        createMockClient({ rowCount: 0 })
-      );
-
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 5432,
-        database: "test",
-        user: "postgres",
-        password: "secret",
-        timeout: 5000,
-        assertions: [{ field: "rowCount", operator: "greaterThan", value: 0 }],
+      const result = await connectedClient.client.exec({
+        query: "SELECT * FROM users",
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Assertion failed");
-    });
-
-    it("should pass querySuccess assertion", async () => {
-      const strategy = new PostgresHealthCheckStrategy(createMockClient());
-
-      const result = await strategy.execute({
-        host: "localhost",
-        port: 5432,
-        database: "test",
-        user: "postgres",
-        password: "secret",
-        timeout: 5000,
-        assertions: [{ field: "querySuccess", operator: "isTrue" }],
-      });
+      expect(result.rowCount).toBe(5);
 
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
   });
 
@@ -166,9 +141,7 @@ describe("PostgresHealthCheckStrategy", () => {
           metadata: {
             connected: true,
             connectionTimeMs: 50,
-            queryTimeMs: 10,
             rowCount: 1,
-            querySuccess: true,
           },
         },
         {
@@ -180,9 +153,7 @@ describe("PostgresHealthCheckStrategy", () => {
           metadata: {
             connected: true,
             connectionTimeMs: 100,
-            queryTimeMs: 20,
             rowCount: 5,
-            querySuccess: true,
           },
         },
       ];
@@ -190,7 +161,6 @@ describe("PostgresHealthCheckStrategy", () => {
       const aggregated = strategy.aggregateResult(runs);
 
       expect(aggregated.avgConnectionTime).toBe(75);
-      expect(aggregated.avgQueryTime).toBe(15);
       expect(aggregated.successRate).toBe(100);
       expect(aggregated.errorCount).toBe(0);
     });
@@ -207,7 +177,6 @@ describe("PostgresHealthCheckStrategy", () => {
           metadata: {
             connected: false,
             connectionTimeMs: 100,
-            querySuccess: false,
             error: "Connection refused",
           },
         },

package/src/strategy.ts

@@ -1,40 +1,29 @@
 import { Client, type ClientConfig } from "pg";
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  timeThresholdField,
-  numericField,
-  booleanField,
-  evaluateAssertions,
   configString,
   configNumber,
   configBoolean,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type {
+  PostgresTransportClient,
+  SqlQueryRequest,
+  SqlQueryResult,
+} from "./transport-client";
 
 // ============================================================================
 // SCHEMAS
 // ============================================================================
 
-/**
- * Assertion schema for PostgreSQL health checks using shared factories.
- */
-const postgresAssertionSchema = z.discriminatedUnion("field", [
-  timeThresholdField("connectionTime"),
-  timeThresholdField("queryTime"),
-  numericField("rowCount", { min: 0 }),
-  booleanField("querySuccess"),
-]);
-
-export type PostgresAssertion = z.infer<typeof postgresAssertionSchema>;
-
 /**
  * Configuration schema for PostgreSQL health checks.
  */
@@ -47,22 +36,13 @@ export const postgresConfigSchema = z.object({
     .default(5432)
     .describe("PostgreSQL port"),
   database: configString({}).describe("Database name"),
-  user: configString({}).describe("Username for authentication"),
-  password: configString({ "x-secret": true }).describe(
-    "Password for authentication"
-  ),
-  ssl: configBoolean({}).default(false).describe("Use SSL/TLS connection"),
+  user: configString({}).describe("Database user"),
+  password: configString({ "x-secret": true }).describe("Database password"),
+  ssl: configBoolean({}).default(false).describe("Use SSL connection"),
   timeout: configNumber({})
     .min(100)
     .default(10_000)
     .describe("Connection timeout in milliseconds"),
-  query: configString({})
-    .default("SELECT 1")
-    .describe("Health check query to execute"),
-  assertions: z
-    .array(postgresAssertionSchema)
-    .optional()
-    .describe("Validation conditions"),
 });
 
 export type PostgresConfig = z.infer<typeof postgresConfigSchema>;
@@ -81,31 +61,13 @@ const postgresResultSchema = z.object({
     "x-chart-label": "Connection Time",
     "x-chart-unit": "ms",
   }),
-  queryTimeMs: healthResultNumber({
-    "x-chart-type": "line",
-    "x-chart-label": "Query Time",
-    "x-chart-unit": "ms",
-  }).optional(),
-  rowCount: healthResultNumber({
-    "x-chart-type": "counter",
-    "x-chart-label": "Row Count",
-  }).optional(),
-  serverVersion: healthResultString({
-    "x-chart-type": "text",
-    "x-chart-label": "Server Version",
-  }).optional(),
-  querySuccess: healthResultBoolean({
-    "x-chart-type": "boolean",
-    "x-chart-label": "Query Success",
-  }),
-  failedAssertion: postgresAssertionSchema.optional(),
   error: healthResultString({
     "x-chart-type": "status",
     "x-chart-label": "Error",
   }).optional(),
 });
 
-export type PostgresResult = z.infer<typeof postgresResultSchema>;
+type PostgresResult = z.infer<typeof postgresResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -116,9 +78,9 @@ const postgresAggregatedSchema = z.object({
     "x-chart-label": "Avg Connection Time",
     "x-chart-unit": "ms",
   }),
-  avgQueryTime: healthResultNumber({
+  maxConnectionTime: healthResultNumber({
     "x-chart-type": "line",
-    "x-chart-label": "Avg Query Time",
+    "x-chart-label": "Max Connection Time",
     "x-chart-unit": "ms",
   }),
   successRate: healthResultNumber({
@@ -132,13 +94,13 @@ const postgresAggregatedSchema = z.object({
   }),
 });
 
-export type PostgresAggregatedResult = z.infer<typeof postgresAggregatedSchema>;
+type PostgresAggregatedResult = z.infer<typeof postgresAggregatedSchema>;
 
 // ============================================================================
 // DATABASE CLIENT INTERFACE (for testability)
 // ============================================================================
 
-export interface DbQueryResult {
+interface DbQueryResult {
   rowCount: number | null;
 }
 
@@ -154,7 +116,6 @@ const defaultDbClient: DbClient = {
   async connect(config) {
     const client = new Client(config);
     await client.connect();
-
     return {
       async query(sql: string): Promise<DbQueryResult> {
         const result = await client.query(sql);
@@ -175,6 +136,7 @@ export class PostgresHealthCheckStrategy
   implements
     HealthCheckStrategy<
       PostgresConfig,
+      PostgresTransportClient,
       PostgresResult,
       PostgresAggregatedResult
     >
@@ -190,13 +152,29 @@ export class PostgresHealthCheckStrategy
   }
 
   config: Versioned<PostgresConfig> = new Versioned({
-    version: 1,
+    version: 2,
     schema: postgresConfigSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no config changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   result: Versioned<PostgresResult> = new Versioned({
-    version: 1,
+    version: 2,
     schema: postgresResultSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult: Versioned<PostgresAggregatedResult> = new Versioned({
@@ -207,133 +185,84 @@ export class PostgresHealthCheckStrategy
   aggregateResult(
     runs: HealthCheckRunForAggregation<PostgresResult>[]
   ): PostgresAggregatedResult {
-    let totalConnectionTime = 0;
-    let totalQueryTime = 0;
-    let successCount = 0;
-    let errorCount = 0;
-    let validRuns = 0;
-    let queryRuns = 0;
+    const validRuns = runs.filter((r) => r.metadata);
 
-    for (const run of runs) {
-      if (run.metadata?.error) {
-        errorCount++;
-        continue;
-      }
-      if (run.status === "healthy") {
-        successCount++;
-      }
-      if (run.metadata) {
-        totalConnectionTime += run.metadata.connectionTimeMs;
-        if (run.metadata.queryTimeMs !== undefined) {
-          totalQueryTime += run.metadata.queryTimeMs;
-          queryRuns++;
-        }
-        validRuns++;
-      }
+    if (validRuns.length === 0) {
+      return {
+        avgConnectionTime: 0,
+        maxConnectionTime: 0,
+        successRate: 0,
+        errorCount: 0,
+      };
     }
 
+    const connectionTimes = validRuns
+      .map((r) => r.metadata?.connectionTimeMs)
+      .filter((t): t is number => typeof t === "number");
+
+    const avgConnectionTime =
+      connectionTimes.length > 0
+        ? Math.round(
+            connectionTimes.reduce((a, b) => a + b, 0) / connectionTimes.length
+          )
+        : 0;
+
+    const maxConnectionTime =
+      connectionTimes.length > 0 ? Math.max(...connectionTimes) : 0;
+
+    const successCount = validRuns.filter(
+      (r) => r.metadata?.connected === true
+    ).length;
+    const successRate = Math.round((successCount / validRuns.length) * 100);
+
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
+
     return {
-      avgConnectionTime: validRuns > 0 ? totalConnectionTime / validRuns : 0,
-      avgQueryTime: queryRuns > 0 ? totalQueryTime / queryRuns : 0,
-      successRate: runs.length > 0 ? (successCount / runs.length) * 100 : 0,
+      avgConnectionTime,
+      maxConnectionTime,
+      successRate,
       errorCount,
     };
   }
 
-  async execute(
+  async createClient(
     config: PostgresConfigInput
-  ): Promise<HealthCheckResult<PostgresResult>> {
+  ): Promise<ConnectedClient<PostgresTransportClient>> {
     const validatedConfig = this.config.validate(config);
-    const start = performance.now();
-
-    try {
-      // Connect to database
-      const connection = await this.dbClient.connect({
-        host: validatedConfig.host,
-        port: validatedConfig.port,
-        database: validatedConfig.database,
-        user: validatedConfig.user,
-        password: validatedConfig.password,
-        ssl: validatedConfig.ssl ? { rejectUnauthorized: false } : false,
-        connectionTimeoutMillis: validatedConfig.timeout,
-      });
-
-      const connectionTimeMs = Math.round(performance.now() - start);
-
-      // Execute health check query
-      const queryStart = performance.now();
-      let querySuccess = false;
-      let rowCount: number | undefined;
-      let queryTimeMs: number | undefined;
-
-      try {
-        const result = await connection.query(validatedConfig.query);
-        querySuccess = true;
-        rowCount = result.rowCount ?? 0;
-        queryTimeMs = Math.round(performance.now() - queryStart);
-      } catch {
-        querySuccess = false;
-        queryTimeMs = Math.round(performance.now() - queryStart);
-      }
-
-      await connection.end();
-
-      const result: Omit<PostgresResult, "failedAssertion" | "error"> = {
-        connected: true,
-        connectionTimeMs,
-        queryTimeMs,
-        rowCount,
-        querySuccess,
-      };
-
-      // Evaluate assertions using shared utility
-      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
-        connectionTime: connectionTimeMs,
-        queryTime: queryTimeMs ?? 0,
-        rowCount: rowCount ?? 0,
-        querySuccess,
-      });
-
-      if (failedAssertion) {
-        return {
-          status: "unhealthy",
-          latencyMs: connectionTimeMs + (queryTimeMs ?? 0),
-          message: `Assertion failed: ${failedAssertion.field} ${
-            failedAssertion.operator
-          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
-          metadata: { ...result, failedAssertion },
-        };
-      }
 
-      if (!querySuccess) {
-        return {
-          status: "unhealthy",
-          latencyMs: connectionTimeMs + (queryTimeMs ?? 0),
-          message: "Health check query failed",
-          metadata: result,
-        };
-      }
+    const connection = await this.dbClient.connect({
+      host: validatedConfig.host,
+      port: validatedConfig.port,
+      database: validatedConfig.database,
+      user: validatedConfig.user,
+      password: validatedConfig.password,
+      ssl: validatedConfig.ssl ? { rejectUnauthorized: false } : undefined,
+      connectionTimeoutMillis: validatedConfig.timeout,
+    });
+
+    const client: PostgresTransportClient = {
+      async exec(request: SqlQueryRequest): Promise<SqlQueryResult> {
+        try {
+          const result = await connection.query(request.query);
+          return { rowCount: result.rowCount ?? 0 };
+        } catch (error) {
+          return {
+            rowCount: 0,
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      },
+    };
 
-      return {
-        status: "healthy",
-        latencyMs: connectionTimeMs + (queryTimeMs ?? 0),
-        message: `PostgreSQL - query returned ${rowCount} row(s) in ${queryTimeMs}ms`,
-        metadata: result,
-      };
-    } catch (error: unknown) {
-      const end = performance.now();
-      const isError = error instanceof Error;
-      return {
-        status: "unhealthy",
-        latencyMs: Math.round(end - start),
-        message: isError ? error.message : "PostgreSQL connection failed",
-        metadata: {
-          connected: false,
-          connectionTimeMs: Math.round(end - start),
-          querySuccess: false,
-          error: isError ? error.name : "UnknownError",
-        },
-      };
-    }
+    return {
+      client,
+      close: () => {
+        connection.end().catch(() => {
+          // Ignore close errors
+        });
+      },
+    };
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,24 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * SQL query request.
+ */
+export interface SqlQueryRequest {
+  query: string;
+}
+
+/**
+ * SQL query result.
+ */
+export interface SqlQueryResult {
+  rowCount: number;
+  error?: string;
+}
+
+/**
+ * PostgreSQL transport client for query execution.
+ */
+export type PostgresTransportClient = TransportClient<
+  SqlQueryRequest,
+  SqlQueryResult
+>;