chmonitor
Features

PeerDB

Monitor PeerDB replication mirrors and peers from within chmonitor — read-only, proxied, no direct database access required.

Monitor PeerDB replication mirrors and peers without leaving chmonitor — an optional, read-only integration that proxies the PeerDB API server-side.

Prop

Type

What it does

PeerDB Mirrors: fleet status tiles, rows-synced trends, peer topology, pipeline phase and peer info

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, plus a fleet lag-triage strip (worst-lag mirrors) and a collapsible logs & alerts feed aggregated across every mirror.
  • Mirror detail (/peerdb/mirror?name=…) adds snapshot / initial-load progress (per-table partition completion, fetch/consolidate phase, avg time per partition), CDC batch history (rows per batch, LSN range, duration), a per-table operation mix (insert/update/delete), and an authoritative rows-synced total.
  • Peers (/peerdb/peers) lists source and destination peers, a replication slot health table (lag, active state, WAL status classified ok / warn / critical), and a mirror connectivity graph.
  • Peer detail (/peerdb/peer?name=…) shows the peer's redacted config and server version, its replication slots, slot-lag history, and active queries.

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, lag triage, fleet logs feed— (PeerDB API)
Mirror detail/peerdb/mirrorSnapshot progress, CDC batch history, operation mix, rows-synced total— (PeerDB API)
Peers/peerdb/peersPeer list, slot health, mirror graph— (PeerDB API)
Peer detail/peerdb/peerPeer info + version, slots, slot-lag history, active queries— (PeerDB API)

Using it

Point chmonitor at your PeerDB API

Set PEERDB_API_URL (include the /api suffix for the UI API). Add PEERDB_PASSWORD if the API requires auth:

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

By default the password is sent as HTTP Basic auth with an empty username (the self-hosted flow-api convention). For PeerDB Enterprise / BYOC deployments that sit behind an auth proxy, set PEERDB_AUTH_SCHEME=bearer to send PEERDB_PASSWORD as an Authorization: Bearer <token> instead:

PEERDB_AUTH_SCHEME=bearer
PEERDB_PASSWORD=my-api-token

Open the PeerDB section

Once PEERDB_API_URL is set, the PeerDB section appears in the nav. Open /peerdb for mirror status, throughput, and per-table sync state.

Inspect peers and lag

PeerDB mirror detail: throughput, replication lag, cumulative rows synced, partition sync history and per-partition QRep progress

Open /peerdb/peers to list source and destination peers, replication slot lag, and the mirror connectivity graph.

(Optional) Attach PeerDB per connection

Instead of the single deployment-wide PEERDB_API_URL, you can attach a PeerDB deployment to an individual saved connection (linking its Postgres source and ClickHouse destination). This needs user connections enabled.

When adding a connection, open the Advanced section and fill in PeerDB monitoring:

  • API URL — the PeerDB flow-api endpoint (same value you'd put in PEERDB_API_URL).
  • Auth — None, Password (empty-user HTTP Basic), or API token (Bearer, for Enterprise / BYOC behind an auth proxy).

Click Test PeerDB to verify the endpoint, then save. The URL is SSRF-validated and the secret is stored only inside the connection's encrypted payload — it is never returned by the connections API.

View that connection's mirrors at /peerdb?connection=<connectionId>. When no ?connection= is present, the pages fall back to the env-wide PEERDB_API_URL.

Permissions & access

The peerdb feature id controls visibility.

CHM_FEATURE_PEERDB_ACCESS=authenticated
CHM_FEATURE_PEERDB_ENABLED=false
[features.peerdb]
enabled = true
access = "authenticated"

Configuration

Prop

Type

Notes & limitations

Read-only by design

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.

Feature permissions

Gate or disable features per section.

PeerDB documentation

Upstream reference for PeerDB mirrors and peers.

Inbound Events

Ingest Alertmanager, Datadog, and generic webhook events into chmonitor — normalized, de-duplicated, retained ~30 days, and optionally re-emitted to your outbound alert routes.

Browser Connections

Add personal ClickHouse connections in the browser with AES-256-GCM encrypted credentials and server-side proxy — no config changes needed.

On this page

What it doesPagesUsing itPoint chmonitor at your PeerDB APIOpen the PeerDB sectionInspect peers and lag(Optional) Attach PeerDB per connectionPermissions & accessConfigurationNotes & limitationsRelated