chmonitor

Monitor PeerDB replication mirrors and peers from within chmonitor (optional, read-only).

Routes/peerdb, /peerdb/peers
Feature idpeerdb
Default accesspublic
Requires authNo (set CHM_FEATURE_PEERDB_ACCESS=authenticated to gate)
System tablesNone — proxies the PeerDB REST API, not ClickHouse system tables
ClickHouse grantsNone required

What it does

When you set PEERDB_API_URL, chmonitor adds a PeerDB section to the navigation. It proxies read-only calls to the PeerDB API so you can monitor replication without leaving the chmonitor UI.

Mirrors (/peerdb) shows all configured replication mirrors with status, throughput, and per-table sync state.

Peers (/peerdb/peers) lists source and destination peers, replication slot lag, and a mirror connectivity graph.

Mutation requests (create, delete, pause, resume) are blocked at the proxy layer and return HTTP 403. chmonitor only ever reads from PeerDB.

The PeerDB section does not appear in the navigation when PEERDB_API_URL is unset.

Pages

PageRouteWhat it showsSystem tables
Mirrors/peerdbMirror status, throughput, per-table sync— (PeerDB API)
Peers/peerdb/peersPeer list, slot lag, mirror graph— (PeerDB API)

Permissions & access

The peerdb feature id controls visibility.

Disable:

CHM_FEATURE_PEERDB_ENABLED=false

Require authentication:

CHM_FEATURE_PEERDB_ACCESS=authenticated

Config file:

[features.peerdb]
enabled = true
access = "authenticated"

Configuration

VariableDefaultDescription
PEERDB_API_URL(unset)PeerDB API base URL. Include the /api suffix for the UI API (e.g., https://peerdb.example.com/api). When unset, the PeerDB section is hidden entirely.
PEERDB_PASSWORD(unset)HTTP Basic auth password. The username is left empty.
PEERDB_CACHE_TTL_MS10000Response cache TTL in milliseconds.
PEERDB_CACHE_MAX_ENTRIES500Maximum number of cached responses.
PEERDB_FETCH_TIMEOUT_MS10000Timeout for proxied PeerDB API requests.

Example:

PEERDB_API_URL=https://peerdb.example.com/api
PEERDB_PASSWORD=my-peerdb-password
PEERDB_CACHE_TTL_MS=15000

Notes & limitations

  • This integration is read-only. Any PeerDB API call that would mutate state (create/delete/pause/resume mirrors or peers) is blocked at the chmonitor proxy layer and returns HTTP 403.
  • The PeerDB API URL must be reachable from the chmonitor server, not from the user’s browser. All PeerDB requests are server-side proxied.
  • PEERDB_API_URL that points to the bare origin (without /api) is intended for direct flow-api use; the UI mirrors/peers pages expect the /api-suffixed URL.
  • PeerDB version compatibility is not guaranteed across major PeerDB releases. If the PeerDB API shape changes, some fields may not render correctly.
  • No ClickHouse system tables are queried by this section.