Upgrading ClickHouse

Check your current version

curl -s "https://your-ch-host:8443?query=SELECT+version()" \
  -u monitoring:password

Or from the dashboard: open the AI agent and ask "What ClickHouse version is this cluster running?"

Check the support matrix

chmonitor supports ClickHouse 22.x and later. Some features degrade gracefully on older versions — they show a "table not available" notice instead of an error. The minimum recommended version for full dashboard coverage is 23.8 LTS.

Back up critical tables before upgrading

Backups that matter for the dashboard:

-- Save current merge-tree settings for comparison after upgrade
SELECT * FROM system.merge_tree_settings INTO OUTFILE 'merge_tree_settings_before.csv' FORMAT CSV;
-- Save current settings
SELECT * FROM system.settings INTO OUTFILE 'settings_before.csv' FORMAT CSV;

Verify no stuck mutations or active merges

The dashboard's Merges and Mutations pages show this at a glance. From SQL:

-- Any stuck mutations?
SELECT database, table, command, parts_to_do, is_done
FROM system.mutations
WHERE is_done = 0
ORDER BY create_time DESC;

-- Long-running merges?
SELECT database, table, round(progress * 100, 2) AS pct, elapsed
FROM system.merges
ORDER BY elapsed DESC;

Wait for mutations to complete or cancel them before upgrading a replica.

Check replication health

SELECT database, table, replica_name,
       is_leader, is_readonly, future_parts,
       queue_size, last_queue_update_exception
FROM system.replicas
WHERE is_readonly = 1 OR queue_size > 10;

All replicas should be healthy with no read-only instances before the upgrade.

Check the dashboard loads correctly

Open /overview — if the page shows data, the basic connection and system-table grants are working.

Check for new system tables

The dashboard automatically picks up new tables if they become available. Look for pages that were previously showing "Table not available" notices:

• Merges → Merge Performance — needs system.part_log
• Queries → Profiler — needs system.processors_profile_log
• Security → Login Attempts — needs system.session_log

Validate from the AI agent

Ask the agent:

"Compare the system tables available now with what the dashboard expects. Are any optional tables still missing?"

The agent uses list_tables against system to enumerate available tables and the system-tables-reference skill to cross-check against the expected set.

Re-check grants if you upgraded users

ClickHouse sometimes changes system-table visibility across major versions. Confirm the monitoring user can still SELECT from the tables it uses:

-- Quick sanity check
SELECT count() FROM system.query_log LIMIT 1;
SELECT count() FROM system.processes LIMIT 1;
SELECT count() FROM system.replicas LIMIT 1;

If any return a permission error, re-apply the grants from ClickHouse User & Grants.

Check deprecated settings

After a major upgrade, system.settings may contain settings marked deprecated. The Settings page flags these. Review and update your server config file accordingly.

Upgrade one replica at a time

Upgrade a single node before touching the next.

Confirm the node rejoins replication

After each node upgrades, confirm it rejoins replication (is_readonly = 0, queue_size draining).

Watch the Replication page

The dashboard's Replication page shows per-table replica health across the cluster.

Wait before the next node

Do not upgrade the next node until the previous one is fully caught up.