Skip to main content

​
Overview

Monitor the health and status of your Duckling instance across all configured databases.

​
Endpoints

​
GET /health

Check database connectivity and overall system health for all databases. Authentication: Required (API key or JWT) Request Example: 
curl http://localhost:3001/health \
  -H "Authorization: Bearer $DUCKLING_API_KEY"
Response (Healthy): 
{
  "status": "healthy",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "databases": [
    {
      "databaseId": "lms",
      "name": "LMS Database",
      "status": "healthy",
      "services": {
        "mysql": "healthy",
        "duckdb": "healthy"
      }
    },
    {
      "databaseId": "analytics",
      "name": "Analytics Database",
      "status": "healthy",
      "services": {
        "mysql": "healthy",
        "duckdb": "healthy"
      }
    }
  ],
  "architecture": "sequential-appender",
  "features": [
    "atomic-transactions",
    "watermark-sync",
    "streaming-batches",
    "acid-compliance",
    "multi-database"
  ]
}
​
status
string
Overall system health status: healthy or unhealthy
​
databases
array
Health status for each configured database
​
databases[].status
string
Database health status: healthy or unhealthy
​
databases[].services.mysql
string
MySQL connection status
​
databases[].services.duckdb
string
DuckDB connection status
​
architecture
string
Current architecture mode: sequential-appender
​
features
array
List of enabled system features
Response (Unhealthy): 
{
  "status": "unhealthy",
  "timestamp": "2024-01-20T10:30:00.000Z",
  "databases": [
    {
      "databaseId": "lms",
      "name": "LMS Database",
      "status": "unhealthy",
      "error": "MySQL connection failed: ECONNREFUSED"
    }
  ],
  "architecture": "sequential-appender",
  "features": ["atomic-transactions", "watermark-sync"]
}
Status Codes:
  • 200 - System is healthy
  • 503 - System is unhealthy (one or more databases failed health check)

​
GET /status

Get detailed system status including uptime, memory usage, and table counts. Authentication: Required (API key or JWT) Request Example: 
curl http://localhost:3001/status \
  -H "Authorization: Bearer $DUCKLING_API_KEY"
Response: 
{
  "uptime": 86400,
  "memory": {
    "rss": 134217728,
    "heapTotal": 67108864,
    "heapUsed": 45088768,
    "external": 2097152,
    "arrayBuffers": 1048576
  },
  "architecture": "sequential-appender",
  "config": {
    "syncInterval": 15,
    "batchSize": 10000,
    "incrementalSync": true
  },
  "databases": [
    {
      "databaseId": "lms",
      "name": "LMS Database",
      "tables": {
        "mysql": 181,
        "duckdb": 181
      }
    },
    {
      "databaseId": "analytics",
      "name": "Analytics Database",
      "tables": {
        "mysql": 45,
        "duckdb": 45
      }
    }
  ]
}
​
uptime
number
Server uptime in seconds
​
memory
object
Node.js process memory usage statistics (in bytes)
​
memory.rss
number
Resident Set Size - total memory allocated for the process
​
memory.heapTotal
number
Total heap memory allocated
​
memory.heapUsed
number
Heap memory currently in use
​
config
object
Current synchronization configuration
​
config.syncInterval
number
Automatic sync frequency in minutes
​
config.batchSize
number
Number of records processed per batch during sync
​
config.incrementalSync
boolean
Whether incremental sync is enabled
​
databases
array
Table counts for each configured database
​
databases[].tables.mysql
number
Number of tables in MySQL source database
​
databases[].tables.duckdb
number
Number of tables replicated in DuckDB
Status Codes:
  • 200 - Status retrieved successfully
  • 500 - Failed to retrieve status

​
Use Cases

​
Container Health Checks

Use the /health endpoint in Docker health checks: 
# docker-compose.yml
services:
  duckdb-server:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

​
Kubernetes Probes

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: duckling
    livenessProbe:
      httpGet:
        path: /health
        port: 3001
        httpHeaders:
        - name: Authorization
          value: Bearer ${DUCKLING_API_KEY}
      initialDelaySeconds: 30
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /health
        port: 3001
        httpHeaders:
        - name: Authorization
          value: Bearer ${DUCKLING_API_KEY}
      initialDelaySeconds: 10
      periodSeconds: 5

​
Monitoring & Alerting

#!/bin/bash
# health-monitor.sh

RESPONSE=$(curl -s -H "Authorization: Bearer $DUCKLING_API_KEY" \
  http://localhost:3001/health)

STATUS=$(echo $RESPONSE | jq -r '.status')

if [ "$STATUS" != "healthy" ]; then
  echo "ALERT: Duckling service is unhealthy"
  echo $RESPONSE | jq .
  # Send alert to monitoring system
  curl -X POST https://your-monitoring-service/alerts \
    -d "service=duckling&status=unhealthy"
fi

​
Load Balancer Integration

Configure load balancers to use /health for backend health checks: AWS Application Load Balancer: 
{
  "HealthCheckProtocol": "HTTP",
  "HealthCheckPath": "/health",
  "HealthCheckIntervalSeconds": 30,
  "HealthCheckTimeoutSeconds": 5,
  "HealthyThresholdCount": 2,
  "UnhealthyThresholdCount": 3
}
The /health endpoint returns HTTP 503 if any database is unhealthy, making it ideal for automated health checks and load balancer configurations.

Build docs developers (and LLMs) love

Get started for freeTalk to us