Skip to content

Database health

Gate readiness on a real round-trip to the database — the module opening the pool attaches the indicator, and HealthModule runs it.

The readiness probe should fail when the database is unreachable. NestRS ships a SeaORM-backed indicator that runs DatabaseConnection::ping and plugs straight into nest-rs-health’s indicator registry — no glue code, no probe handler to write.

Import HealthModule beside the data layer:

apps/api/src/module.rs
use nest_rs::core::module;
use nest_rs::health::HealthModule;
use nest_rs::seaorm::SeaOrmDatabaseModule;
#[module(
imports = [
SeaOrmDatabaseModule,
HealthModule,
],
)]
pub struct ApiModule;

That’s it. SeaOrmModule, which the binding imports, attaches the pool’s indicator, seaorm, to both the readiness and the startup probe — HealthModule runs it beside every other indicator the app opened, and refuses the boot when a second one claims the name. A pool a feature opens is checked the same way: there is no health import to write, and two modules opening the pool report it once.

Two endpoints exit the box with the database wired in:

EndpointKeyFailure
GET /health/readyseaorm503 while unreachable
GET /health/startupseaorm503 until first ping succeeds

One key on both probes: the probe is the route, so the name says which resource answered — the crate that owns the pool — never which probe asked.

The liveness probe (GET /health/live) deliberately does not depend on the database — a brief DB outage should not kill the pod.

Terminal window
$ curl -s http://localhost:3000/health/ready
{"status":"up","info":{"seaorm":{"name":"seaorm","status":"up"}},"error":{},
"details":{"seaorm":{"name":"seaorm","status":"up"}}}

When the ping fails the indicator moves from info to error, the overall status switches to down, and the response is a 503. The body carries the fixed reason "check failed" — never the DbErr, which would put a DSN or an internal hostname on a routinely unauthenticated endpoint. The real error goes to the log instead: warn on nest_rs::health, with indicator, kind and error as fields. Indicators is the reference for that split; the shape itself is on Health.

  • Database — the slice the indicator hangs off.
  • Repo and executor — the DatabaseConnection the indicator pings.
  • Health — the indicator registry, the probe endpoints, custom indicators for other dependencies.