@openstatus/health-postgres

PostgreSQL probe for @openstatus/health. Runs select 1 through the client you already have — a pg pool or client, a postgres.js sql instance, @neondatabase/serverless or @vercel/postgres — and fails the check when the round trip does.

deno add jsr:@openstatus/health jsr:@openstatus/health-postgres
npm install @openstatus/health @openstatus/health-postgres

import { Pool } from "pg";
import { createHealthHandler } from "@openstatus/health";
import { postgresProbe } from "@openstatus/health-postgres";

const pool = new Pool({ connectionString: env.DATABASE_URL });

Deno.serve(
  createHealthHandler({ probes: [postgresProbe({ client: pool })] }),
);

The probe picks the first method the client exposes:

| Client | Call | | ------ | ---- | | pg Pool / Client, @vercel/postgres sql, Neon Pool / Client / neon() | client.query("select 1") | | postgres.js sql | sql.unsafe("select 1") |

Pass a pool rather than a single connection where you can: a pool checks a connection out per probe and hands it back, so the health endpoint never holds one open and never collides with request traffic on a shared client.

A timed-out check is reported timeout and the round moves on; the driver query is not cancelled, because none of the supported clients expose a portable abort (pg and @vercel/postgres take query text only, and postgres.js cancels through the pending query's .cancel() rather than a signal). With a pool, the connection returns to it once the query settles.

postgresProbe({
  client: pool,
  // optional overrides from the Probe contract
  name: "primary",
  critical: false,
  timeoutMs: 2000,
  skip: () => env.DATABASE_URL == null,
});

Critical by default: a Postgres that does not answer usually means requests cannot be served, so the report turns unhealthy and the instance is taken out of rotation. Set critical: false for a replica or reporting database.

The client is typed structurally as { query(text) } or { unsafe(text) }, so pg and postgres are optional peer dependencies for their types only and the probe adds no runtime import of either. The factory throws ProbeConfigError at construction when the client has neither method.

About openstatus

openstatus is the open-source uptime monitoring and status page platform. This package is part of @openstatus/health, the /health endpoints behind openstatus's own services, extracted so any JavaScript server can expose one. Point an openstatus monitor at the endpoint and assert on status in the body to be alerted on degraded before it becomes unhealthy.

Source: github.com/openstatusHQ/health. Issues and PRs welcome.

License

MIT