Hub Administration

All hub administration endpoints require SuperUser authentication.

Federation Status

curl -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/status

{
  "total_clusters": 5,
  "active_clusters": 4,
  "healthy": 3,
  "degraded": 1,
  "unreachable": 0,
  "schema_version": 12
}

Cluster Management

List Clusters

curl -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/clusters

Returns each cluster’s ID, name, endpoint, port, health status, and active flag.

Register a Cluster

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://api.syndb.xyz/v1/federation/clusters \
  -d '{
    "name": "partner-lab",
    "endpoint": "ch.partner-lab.edu",
    "port": 9440,
    "description": "Partner Lab ClickHouse node",
    "institution": "Partner University",
    "contact_email": "[email protected]"
  }'

Clusters can also self-register via POST /v1/federation/register using the federation password (no SuperUser required).

Deactivate a Cluster

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/clusters/{cluster_id}

Sets is_active = false. The cluster is excluded from future queries but its record is preserved.

Health Checks

Single Cluster

curl -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/clusters/{cluster_id}/health

Verification Tests

Three targeted tests for diagnosing cluster issues:

# Test ClickHouse connectivity and measure latency
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/clusters/{cluster_id}/test/connectivity

# Verify schema version compatibility
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/clusters/{cluster_id}/test/schema

# Run a test cross-cluster query
curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/clusters/{cluster_id}/test/query

Schema Sync

Push pending DDL migrations to all active clusters:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/schema/sync

Get the current schema version and migrations:

# All migrations
curl -H "Authorization: Bearer $TOKEN" \
  https://api.syndb.xyz/v1/federation/schema

# Migrations since version 10
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.syndb.xyz/v1/federation/schema?since_version=10"

Benchmarks

Track federation query performance:

# Submit a benchmark record
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://api.syndb.xyz/v1/federation/benchmarks \
  -d '{
    "cluster_id": "...",
    "query_type": "remote_single",
    "latency_ms": 145,
    "row_count": 50000,
    "cluster_count": 1,
    "payload_bytes": 2048000,
    "success": true
  }'

# List benchmarks with filters
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.syndb.xyz/v1/federation/benchmarks?query_type=remote_single&limit=50"

# Aggregate stats grouped by query type
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.syndb.xyz/v1/federation/benchmarks/aggregate?since=2024-01-01"

Query Types