chmonitorPostgres
Monitor a Postgres database alongside your ClickHouse clusters — read-only query insights, running queries, and AI agent tools. Beta, free on every plan.
chmonitor can monitor a Postgres database the same way it monitors ClickHouse: read-only, no agent to install, from the same dashboard. This is a beta feature — off by default, free on every plan (including self-hosted) while it stabilizes.
Beta
Postgres support is new. Expect rough edges, and treat the feature flag as "on for evaluation," not "on for every production cluster" just yet.
Prop
Type
What it does
Postgres is a source engine, alongside ClickHouse and ClickHouse Cloud. Once CHM_FEATURE_POSTGRES_SOURCE is on, chmonitor can connect to a Postgres database and adds two pages:
- Query Insights (
/postgres/queries) — the slowest normalized query patterns frompg_stat_statements, ranked by total execution time, with a detail flyout per pattern. Refreshes every 30 seconds. - Running Queries (
/postgres/activity) — live backends frompg_stat_activity: state, wait event, query, duration. Refreshes every 5 seconds.
Switching to a Postgres host swaps the sidebar to these two pages automatically — the same engine-aware menu that shows ClickHouse-only pages for ClickHouse hosts.
Pages
| Page | Route | Source | Refresh |
|---|---|---|---|
| Query Insights | /postgres/queries | pg_stat_statements | 30s |
| Running Queries | /postgres/activity | pg_stat_activity | 5s |
Using it
Turn on the feature flag
CHM_FEATURE_POSTGRES_SOURCE=trueNothing changes anywhere else until this is set — the flag is fail-closed by design.
Add a Postgres connection
Two ways to connect, same as ClickHouse:
Environment variables (comma-separated lists, mirroring CLICKHOUSE_HOST etc.):
POSTGRES_HOST=db.example.com
POSTGRES_PORT=5432
POSTGRES_USER=chmonitor_ro
POSTGRES_PASSWORD=my-password
POSTGRES_DATABASE=postgres
POSTGRES_SSLMODE=require
POSTGRES_NAME=Production PostgresPer-user connection (dashboard UI, when per-user connections are enabled): open the connection form and pick the Postgres tab. Fields are host, port, database, user, password, and SSL mode.
Use a dedicated read-only Postgres role for the connection user — chmonitor pins default_transaction_read_only=on on every query as the authoritative guard, but a read-only role is good defense in depth and makes the intent explicit at the database level.
Enable pg_stat_statements (recommended)
Query Insights needs the pg_stat_statements extension. Without it, the page shows an empty state with the exact steps instead of an error:
-- postgresql.conf, then restart Postgres
shared_preload_libraries = 'pg_stat_statements'CREATE EXTENSION pg_stat_statements;Running Queries works without the extension — it only needs pg_stat_activity, which is always available.
Open the Postgres pages
Switch to the Postgres host (?pg=<connectionId> in the URL, or the host switcher). The sidebar shows Query Insights and Running Queries in place of the ClickHouse pages.
Security
Read-only, always
Every Postgres query goes through one path: queryPostgres(). It connects per request, pins default_transaction_read_only=on, and only allows a single SELECT/WITH/SHOW/EXPLAIN/TABLE/VALUES statement. There is no second Postgres access path anywhere in chmonitor.
- SSRF guard:
validatePostgresHost()rejects private, loopback, link-local and other internal address ranges (both the literal host and its resolved IPs) before connecting. SetCHM_ALLOW_PRIVATE_HOSTS=trueto allowlocalhostfor local development — this override has no effect in Cloud mode. - Credential encryption: per-user Postgres connection credentials are encrypted at rest, same as ClickHouse connections.
AI agent tools
Three tools, gated off with the feature flag (they simply don't appear when it's disabled):
Prop
Type
Agent tools currently see env-configured hosts only
The agent tools resolve Postgres hosts from POSTGRES_HOST (and siblings) — the same limitation ClickHouse agent tools have today with per-user connections. Per-user Postgres connections added through the dashboard UI are not yet visible to the agent.
Cross-source correlation (e.g. "compare this Postgres table to its ClickHouse mirror") works by giving the agent both tool sets in one conversation — there is no dedicated join primitive.
Configuration
Prop
Type
Notes & limitations (beta)
- Free on every plan, including self-hosted, while the feature is in beta — no billing gate yet.
- Postgres connections have their own id space (
?pg=<connectionId>) separate from ClickHousehostId; the two are never mixed. - Agent tools only see env-configured Postgres hosts, not per-user connections (see above).
- No live TLS certificate verification against a remote Postgres yet.
- Migrating data from Postgres into ClickHouse via CDC? See the agent's migration-planning skill, which recommends PeerDB as the CDC path.