Health Checks - Quarkus Morphium Showcase

What Morphium Offers

The Quarkus Morphium extension auto-registers MicroProfile Health probes — liveness, readiness and startup — with zero configuration. The probes check MongoDB connectivity and report driver details, replica set status and connection pool health.

The Challenge

Health checks for database connections typically require custom CDI beans with manual probe implementations. The Quarkus extension handles this automatically, including proper status reporting for Kubernetes orchestration.

Morphium Features Used

How It Works

Zero configuration — Simply adding quarkus-smallrye-health to your project activates the Morphium health checks automatically. No code, no annotations, no beans to define.
Automatic probe registration — The quarkus-morphium deployment processor detects SmallRye Health on the classpath and registers three health check beans: one for liveness, one for readiness, and one for startup.
Disable if needed — Set quarkus.morphium.health.enabled=false in application.properties to disable the automatic health checks while keeping SmallRye Health for other checks.
All three probes check morphium.getDriver().isConnected() as the primary indicator. The readiness and startup checks additionally include pool statistics in their health response data.

Configuration

pom.xml (dependency) XML

<!-- Add SmallRye Health to activate Morphium health checks -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-health</artifactId>1
</dependency>

1 Adding quarkus-smallrye-health to the classpath is the only step required; the quarkus-morphium extension detects it and auto-registers all three health check beans.

application.properties Properties

# Health checks are enabled by default when SmallRye Health is present
quarkus.morphium.health.enabled=true1

# To disable Morphium health checks (keeps other health checks active):
# quarkus.morphium.health.enabled=false2

1 Health checks are enabled by default; no configuration is needed unless you want to disable them.

2 Setting health.enabled=false removes only the Morphium health checks while leaving any other SmallRye Health checks in place.

Driver APIs

Morphium Driver Health APIs Java

import de.caluga.morphium.driver.MorphiumDriver;
import de.caluga.morphium.driver.MorphiumDriver.DriverStatsKey;

MorphiumDriver driver = morphium.getDriver();1

// Liveness: is the driver connected to MongoDB?
boolean connected = driver.isConnected();2

// Pool statistics (Map<DriverStatsKey, Double>)
Map<DriverStatsKey, Double> stats = driver.getDriverStats();3
long inPool = stats.getOrDefault(DriverStatsKey.CONNECTIONS_IN_POOL, 0.0).longValue();4
long inUse  = stats.getOrDefault(DriverStatsKey.CONNECTIONS_IN_USE, 0.0).longValue();
long errors = stats.getOrDefault(DriverStatsKey.ERRORS, 0.0).longValue();5

// Per-host connection counts (Map<String, Integer>)
Map<String, Integer> hostConns = driver.getNumConnectionsByHost();6

1 morphium.getDriver() returns the active MorphiumDriver instance — the same object the health checks use internally.

2 isConnected() is the primary liveness signal; false causes the liveness probe to report DOWN and triggers a Kubernetes pod restart.

3 getDriverStats() returns a Map<DriverStatsKey, Double> with connection pool metrics used by the readiness and startup probes.

4 DriverStatsKey is an enum with keys such as CONNECTIONS_IN_POOL, CONNECTIONS_IN_USE, ERRORS, FAILOVERS, and more.

5 ERRORS counts connection-level errors since the driver started; a rising error count can indicate connectivity problems.

6 getNumConnectionsByHost() breaks down open connections per replica-set member, useful for diagnosing uneven load distribution.

Health Check Endpoints

Endpoint	Purpose	K8s Probe Type
`/q/health`	Combined health status (all checks)	—
`/q/health/live`	Is the MongoDB driver connected?	Liveness
`/q/health/ready`	Is the connection pool healthy and accepting requests?	Readiness
`/q/health/started`	Was the initial connection to MongoDB established?	Startup

MicroProfile Health