Health Check Guide

MDDB provides health check endpoints for monitoring and orchestration tools like Docker, Kubernetes, and load balancers.

Health Check Endpoints

`/health`

Simple health check endpoint that verifies database connectivity.

Response (Healthy):

{
  "status": "healthy",
  "mode": "wr"
}

Response (Unhealthy):

{
  "status": "unhealthy",
  "error": "database connection error"
}

HTTP Status Codes:

200 OK - Service is healthy
503 Service Unavailable - Service is unhealthy

`/v1/health`

Alias for /health endpoint (same functionality).

`/v1/stats`

Detailed statistics endpoint (can also be used for health checks, but returns more data).

Docker Health Checks

Docker Run

docker run -d \
  --name mddb \
  -p 11023:11023 \
  -p 11024:11024 \
  --health-cmd="wget --no-verbose --tries=1 --spider http://localhost:11023/health || exit 1" \
  --health-interval=30s \
  --health-timeout=3s \
  --health-retries=3 \
  --health-start-period=5s \
  tradik/mddb:latest

Docker Compose

services:
  mddb:
    image: tradik/mddb:latest
    ports:
      - "11023:11023"
      - "11024:11024"
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:11023/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Check Container Health

docker ps

docker inspect --format='{{json .State.Health}}' mddb | jq

docker-compose up -d
docker-compose ps

Kubernetes Health Checks

Liveness and Readiness Probes

apiVersion: v1
kind: Pod
metadata:
  name: mddb
spec:
  containers:
  - name: mddb
    image: tradik/mddb:latest
    ports:
    - containerPort: 11023
      name: http
    - containerPort: 11024
      name: grpc
    env:
    - name: MDDB_EXTREME
      value: "true"
    livenessProbe:
      httpGet:
        path: /health
        port: 11023
      initialDelaySeconds: 10
      periodSeconds: 30
      timeoutSeconds: 3
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /health
        port: 11023
      initialDelaySeconds: 5
      periodSeconds: 10
      timeoutSeconds: 3
      failureThreshold: 3

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mddb
  labels:
    app: mddb
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mddb
  template:
    metadata:
      labels:
        app: mddb
    spec:
      containers:
      - name: mddb
        image: tradik/mddb:latest
        ports:
        - containerPort: 11023
          name: http
          protocol: TCP
        - containerPort: 11024
          name: grpc
          protocol: TCP
        env:
        - name: MDDB_PATH
          value: "/data/mddb.db"
        - name: MDDB_MODE
          value: "wr"
        - name: MDDB_EXTREME
          value: "true"
        volumeMounts:
        - name: data
          mountPath: /data
        livenessProbe:
          httpGet:
            path: /health
            port: 11023
          initialDelaySeconds: 10
          periodSeconds: 30
          timeoutSeconds: 3
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /health
            port: 11023
          initialDelaySeconds: 5
          periodSeconds: 10
          timeoutSeconds: 3
          failureThreshold: 3
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: mddb-data
---
apiVersion: v1
kind: Service
metadata:
  name: mddb
spec:
  selector:
    app: mddb
  ports:
  - name: http
    port: 11023
    targetPort: 11023
  - name: grpc
    port: 11024
    targetPort: 11024
  type: ClusterIP
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mddb-data
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Manual Health Checks

Using curl

curl http://localhost:11023/health

curl -v http://localhost:11023/health

curl -s -o /dev/null -w "%{http_code}" http://localhost:11023/health

Using wget

wget -q -O- http://localhost:11023/health

wget --no-verbose --tries=1 --spider http://localhost:11023/health

Using httpie

http GET http://localhost:11023/health

Load Balancer Configuration

Nginx

upstream mddb_backend {
    server mddb1:11023 max_fails=3 fail_timeout=30s;
    server mddb2:11023 max_fails=3 fail_timeout=30s;
}

server {
    listen 80;
    server_name mddb.example.com;

    location /health {
        access_log off;
        proxy_pass http://mddb_backend/health;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location / {
        proxy_pass http://mddb_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

HAProxy

frontend mddb_frontend
    bind *:80
    default_backend mddb_backend

backend mddb_backend
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200
    server mddb1 mddb1:11023 check inter 30s fall 3 rise 2
    server mddb2 mddb2:11023 check inter 30s fall 3 rise 2

Traefik (Docker Labels)

services:
  mddb:
    image: tradik/mddb:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mddb.rule=Host(`mddb.example.com`)"
      - "traefik.http.services.mddb.loadbalancer.server.port=11023"
      - "traefik.http.services.mddb.loadbalancer.healthcheck.path=/health"
      - "traefik.http.services.mddb.loadbalancer.healthcheck.interval=30s"
      - "traefik.http.services.mddb.loadbalancer.healthcheck.timeout=3s"

Monitoring Integration

Prometheus

scrape_configs:
  - job_name: 'mddb'
    metrics_path: '/health'
    static_configs:
      - targets: ['mddb:11023']

Grafana Alert

- alert: MDDBUnhealthy
  expr: up{job="mddb"} == 0
  for: 1m
  labels:
    severity: critical
  annotations:
    summary: "MDDB instance is down"
    description: "MDDB instance {{ $labels.instance }} has been down for more than 1 minute."

Health Check Best Practices

Timing Configuration

Docker/Docker Compose:

interval: 30s (how often to check)
timeout: 3-10s (max time to wait for response)
retries: 3 (failures before marking unhealthy)
start_period: 5-10s (grace period on startup)

Kubernetes:

initialDelaySeconds: 5-10s (wait before first check)
periodSeconds: 10-30s (how often to check)
timeoutSeconds: 3s (max time to wait)
failureThreshold: 3 (failures before restart)

Recommendations

Use /health for orchestration - Lightweight, fast response
Use /v1/stats for monitoring - Detailed metrics for dashboards
Set appropriate timeouts - Balance between responsiveness and false positives
Configure start period - Allow time for database initialization
Monitor health check logs - Track failures and patterns
Test health checks - Verify configuration before deployment

Troubleshooting

Health Check Fails Immediately

docker ps

docker logs mddb

curl http://localhost:11023/health

Health Check Times Out

Container Keeps Restarting

docker inspect mddb | jq '.[] | .Config.Healthcheck'

docker inspect mddb | jq '.[] | .State.Health'