Connect ClickHouse

To connect ClickHouse to CoIsland, you add a connector with the service’s HTTPS address, a database user and its password, then pick what to watch. You do it alone: any user that can sign in and read works.

CoIsland talks to ClickHouse’s HTTP interface straight from your Mac; the password stays in your login Keychain and goes only in the X-ClickHouse-Key header. Every query is sent with readonly=1, so the server refuses anything but a read.

Get an address, a user and a password

• ClickHouse Cloud: open the service, click Connect, choose HTTPS: it shows the address (https://abc123.eu-west-1.aws.clickhouse.cloud:8443), the default user and a way to reset its password.

• A user that only reads is safest. In the SQL console:

  CREATE USER coisland IDENTIFIED BY 'a long password' SETTINGS readonly = 1;
  GRANT SELECT ON shop.* TO coisland;
  -- For the health monitors, only the tables they read:
  GRANT SELECT ON system.query_log, SELECT ON system.processes, SELECT ON system.mutations,
        SELECT ON system.parts, SELECT ON system.replicas, SELECT ON system.disks TO coisland;

• Your own server: its HTTPS port (8443 by default) must be open. Plain HTTP (8123) works only for a server on your Mac, like http://localhost.

Connect ClickHouse in CoIsland

1. Open Settings › Connectors, click +, choose ClickHouse.
2. Server: the HTTPS address, pasted as the console shows it. Port: only when it is not 8443 (or 8123 for http://localhost).
3. Database (optional): where table names without a database are read. User and Password.
4. Click Test connector, then Add Connector. Test says who you are, the version, and which system tables the health monitors cannot read.

Watch ClickHouse

Custom SQL and Validation work as for PostgreSQL: one SELECT, WITH or SHOW; under Advanced, Database picks another database. A SETTINGS or FORMAT clause is refused by the server’s read-only mode: CoIsland asks for its own format.

The health kinds need no SQL: pick a threshold, and CoIsland writes the SELECT on the system table.

Kind	Reads	Alerts when
Failed queries	system.query_log	a query failed within the lookback (1 hour)
Long-running queries	system.processes	a query has run longer than 5 minutes
Stuck mutations	system.mutations	a mutation is not done after 30 minutes
Too many parts	system.parts	a partition has more than 300 active parts
Replication lag	system.replicas	a replica is more than 5 minutes behind
Low disk space	system.disks	a disk has less than 15% free

On ClickHouse Cloud a service runs several replicas, and each keeps its own query log and process list: add Cluster default to Failed queries and Long-running queries to read every replica.

-- name: Queries running over 10 minutes
-- kind: clickhouse.long-queries
-- connector: events
-- every: 5m

over:10m cluster:default

Troubleshooting ClickHouse connector errors

Message	What to do
ClickHouse refused the user or the password	Check both; in Cloud, reset the password under Connect
Signed in, but not allowed: … SELECT ON system.query_log	Grant SELECT on that system table, or use a user that has it
Monitors only read (readonly=1)	The SQL writes; monitors never do
Monitors run read-only (readonly=1), which cannot change a setting	Remove the SETTINGS clause
No ClickHouse HTTP interface answered at this address	Use the HTTPS address and port, not 9000 or 9440
ClickHouse is not answering yet	The service is starting or waking; the next check tries again

Frequently asked questions

Does a check wake an idle ClickHouse Cloud service?

Yes. Any query wakes it, and it stays on until it idles again. Check less often, or keep the monitors on a service that does not idle.

Does it read ClickHouse Cloud’s backups or service state?

Not yet. Those come from the Cloud API, whose keys only an organization Admin can create, so CoIsland watches what the database itself says.