@multisystemsuite/db-health-check

Compute a database health score from connection, replication, storage, and custom checks. Ideal for load balancers, Kubernetes probes, and status pages.

Version: 1.0.1 · License: MIT

npm readme: @multisystemsuite/db-health-check on npm

Installation

pnpm add @multisystemsuite/db-health-check

Quick start

import { DbHealthCheck } from '@multisystemsuite/db-health-check';

const health = new DbHealthCheck({ latencyThresholdMs: 500 });

health.registerConnectionCheck(async () => {
  const start = Date.now();
  await db.query('SELECT 1');
  return Date.now() - start;
});

health.registerReplicationCheck(async () => getReplicationLagMs());
health.registerStorageCheck(async () => getDiskUsedPercent());

const report = await health.run();
console.log(report);

Example output:

{
  "score": 92,
  "status": "healthy",
  "checks": [...],
  "timestamp": "2026-05-31T12:00:00.000Z"
}

Status bands

| Score | Status | |-------|--------| | ≥ 80 | healthy | | 50–79 | degraded | | < 50 | unhealthy |

Built-in check registrars

Connection

health.registerConnectionCheck(async () => pingLatencyMs);

Fails if latency ≥ latencyThresholdMs (default 500).

Replication

health.registerReplicationCheck(async () => lagMs, maxLag?);
// default maxLag: 5000 ms

Storage

health.registerStorageCheck(async () => usedPercent, maxUsed?);
// default maxUsed: 90%

Custom checks

health.register({
  name: 'custom-cache',
  weight: 20,
  run: async () => ({
    name: 'custom-cache',
    passed: true,
    score: 100,
    message: 'Redis OK',
  }),
});

Score is weighted average across all checks.

Kubernetes probe example

app.get('/healthz', async (_req, res) => {
  const report = await health.run();
  res.status(report.status === 'healthy' ? 200 : 503).json(report);
});

Related packages

See the @multisystemsuite org on npm.

npm

• Package: @multisystemsuite/db-health-check
• Install: npm install @multisystemsuite/db-health-check