ClickHouse Quick Setup Guide
This guide will walk you through creating your first ClickHouse monitoring check in UptimeDock. By the end of this tutorial, you'll have a fully configured check that monitors your ClickHouse database for performance, availability, and resource usage.
Prerequisites
Before you begin, make sure you have:
- An active UptimeDock account
- ClickHouse version 22.8 or higher
- Access to your ClickHouse database credentials
- Network connectivity from UptimeDock to your ClickHouse instance (see Network Access & IP Whitelisting)
UptimeDock requires ClickHouse 22.8.0 or later. Earlier versions are not supported due to differences in system tables and metrics availability. You can check your version by running: SELECT version()
For security best practices, we recommend creating a dedicated read-only user for monitoring. UptimeDock only needs SELECT permissions on specific system tables. See Database Configuration & Permissions for detailed setup instructions.
Step 1: Select Check Type
Navigate to the Create New Check page and select ClickHouse as your check type from the available options.
Step 2: Enter Connection Details
Fill in the following connection details for your ClickHouse database:
| Field | Description | Example |
|---|---|---|
| Check Tag | A friendly name to identify this check | Production Analytics DB |
| Database Host | Hostname or IP address of your ClickHouse server | clickhouse.example.com |
| Database Port | Native protocol port (see port reference below) | 9000 or 9440 |
| Database Name | Name of the database to connect to | default |
| Username | ClickHouse user with read access | monitoring_user |
| Password | Password for the specified user | •••••••• |
| TLS/SSL | Enable secure connection (required for ClickHouse Cloud) | Enabled / Disabled |
Connection Ports Reference
Choosing the correct port is essential for a successful connection. Here's a quick reference:
If you're using ClickHouse Cloud, use port 9440 and make sure to enable TLS/SSL. ClickHouse Cloud requires encrypted connections.
For self-hosted ClickHouse with default configuration, use port 9000. TLS can remain disabled unless you've configured SSL on your server. We recommend testing the connection to verify your settings.
| Environment | Port | TLS Required |
|---|---|---|
| ClickHouse Cloud | 9440 | ✅ Yes |
| Self-Hosted (Default) | 9000 | ❌ No (unless configured) |
| Self-Hosted with TLS | 9440 | ✅ Yes |
Step 3: Test Connection
After filling in all connection details, the Test Connection button will become active. Click it to verify that UptimeDock can successfully connect to your ClickHouse database.
A successful test will show a confirmation message. If the test fails, double-check your:
- Host address and port number
- Username and password
- TLS settings (especially for ClickHouse Cloud)
- Firewall rules allowing connections from UptimeDock (see IP Whitelisting)
If you're having trouble connecting, make sure UptimeDock's IP address is whitelisted. See our Network Access & IP Whitelisting guide for details.
Step 4: Schedule Settings
Configure when and how often UptimeDock should check your ClickHouse database:
- Hours: Select specific hours during which monitoring should run
- Days: Choose which days of the week to monitor
For production databases, we recommend 24/7 monitoring. For development or staging environments, you might want to limit monitoring to business hours.
Step 5: Maintenance Windows
If you have scheduled maintenance periods (e.g., database upgrades, backups), you can configure maintenance windows to pause monitoring during these times.
During maintenance windows:
- No checks will be performed
- No alerts will be triggered
- Your uptime statistics won't be affected
Step 6: Create Your Check
Once you've configured all settings, click the Create button to create your ClickHouse monitoring check.
Alert thresholds cannot be configured during check creation. After your check is created and starts collecting live data, you can set up alerts based on actual metrics from your database. Visit the check's settings page to configure alerts once monitoring data is available.
Congratulations! Your ClickHouse monitoring check is now active. UptimeDock will start collecting metrics immediately and you'll see your first data points within minutes.
What's Next?
Now that your check is running, explore these guides to get the most out of your monitoring:
- Query Performance Monitoring – Understand and optimize query performance
- Memory & Resources – Monitor memory usage and system resources
- Threshold Guide – Learn recommended alert thresholds
- Setting Up Alerts – Configure notifications for issues