Health Check API

The Health Check API provides system status monitoring for operational health verification, load balancer health probes, and backup validation.

Overview

Data Border exposes health check endpoints that verify connectivity to critical system components:

• SQLite Database: Core data store connectivity
• Tigris Storage: S3-compatible object storage for labels and files
• Litestream Backups: Continuous database replication status

Endpoints

Basic Health Check

Returns operational status of core Data Border components.

GET /health-check

Authentication

None required. This endpoint is public for load balancer probes.

Query Parameters

Response

All systems healthy:

{
  "success": true,
  "database": "connected",
  "storage": "connected",
  "timestamp": 1704067200000
}

Health check failed:

{
  "success": false,
  "error": "Health check failed"
}

Status: 500 Internal Server Error

Example Request

curl https://adb.example.com/health-check

Litestream Health Check

Extended health check that includes Litestream backup status verification.

GET /health-check/litestream

Authentication

None required.

Response

All systems healthy with backup:

{
  "success": true,
  "database": "connected",
  "storage": "connected",
  "litestream": "backup-found",
  "timestamp": 1704067200000
}

Healthy but no backup found:

{
  "success": true,
  "database": "connected",
  "storage": "connected",
  "litestream": "no-backup",
  "timestamp": 1704067200000
}

Backup check failed:

{
  "success": true,
  "database": "connected",
  "storage": "connected",
  "litestream": "check-failed",
  "timestamp": 1704067200000
}

Litestream Status Values

Example Request

curl https://adb.example.com/health-check/litestream

Health Check Components

Database Connectivity

Verifies SQLite database is accessible and responding:

SELECT 1

If this fails, the entire health check returns a 500 error.

Storage Connectivity

Verifies Tigris S3-compatible storage is accessible by checking for the installation marker file:

GET s3://bucket/.well-known/app-installed.txt

Litestream Backup Verification

Checks for the presence of Litestream WAL backup files:

LIST s3://bucket/litestream/ (MaxKeys: 1)

Litestream continuously streams SQLite WAL (Write-Ahead Log) changes to object storage, providing point-in-time recovery capability.

Usage Patterns

Load Balancer Health Probes

Configure your load balancer to probe the basic health check:

# Fly.io example (fly.toml)
[[services.http_checks]]
  interval = "10s"
  timeout = "2s"
  grace_period = "5s"
  method = "GET"
  path = "/health-check"

Consul Health Checks

Data Border automatically reduces log verbosity for Consul health checks:

User-Agent: Consul Health Check

When this header is present and the response is 200, logs are set to debug level to reduce noise.

Monitoring Integration

Integrate with monitoring systems for alerting:

# Prometheus-compatible check
curl -s https://adb.example.com/health-check | jq -e '.success == true'

Backup Validation

Use the Litestream endpoint for backup monitoring:

#!/bin/bash
# Backup monitoring script
response=$(curl -s https://adb.example.com/health-check/litestream)
litestream_status=$(echo "$response" | jq -r '.litestream')

if [ "$litestream_status" != "backup-found" ]; then
  echo "ALERT: Litestream backup status: $litestream_status"
  exit 1
fi

Response Times

Expected response times under normal conditions:

Error Scenarios

Database Unavailable

If the SQLite database is inaccessible (file locked, corrupted, missing):

• Health check returns 500 Internal Server Error
• Logged as type: "health_check" with error details
• Application should be restarted or investigated

Storage Unavailable

If Tigris storage is inaccessible:

• Basic health check returns 500 Internal Server Error
• Use ?skipStorage=true to check database only
• Check Tigris service status and credentials

Litestream Not Configured

If Litestream isn't running or configured:

• /health-check/litestream returns "litestream": "no-backup"
• This is expected for new deployments
• Verify Litestream configuration in litestream.yml

Related Documentation

• Deployment Security - Deployment configuration
• Backup Policy - Backup procedures and SLAs