How Conversion works with ClickHouse
Conversion connects to ClickHouse Cloud or self-hosted ClickHouse over HTTPS and runs the SQL queries you write on a schedule you choose. Each row lands as a contact, a custom object related to a contact, or an event that can trigger a workflow. Conversion signs in as a dedicated read-only user, so it can run SELECT queries but can't write to your databases.
What you can do
Cloud or self-hosted
Connect a ClickHouse Cloud service on port 8443 or your own server on its HTTPS port. Idle Cloud services take a few seconds to wake, so the first sync after a quiet period can run slower.
Read-only at the user level
Conversion's user is created with readonly = 2, which allows SELECT queries and per-query settings but blocks writes. Grants can cover a whole database or single tables.
Types that survive the trip
Named tuples, Map, and JSON columns arrive as JSON objects and arrays as JSON arrays, while large integers and decimals come through as strings so no precision is lost.
Incremental on your schedule
Run each sync every 15 minutes, hourly, every 6 hours, or daily. Compare your DateTime column with toDateTime() on last_sync_time so a run reads only new and changed rows.
What syncs
| Data | Direction | Details |
|---|---|---|
| Contacts | Into Conversion | Created or updated from each row, identified by userId or email, with columns mapped to field keys by exact name. |
| Custom objects | Into Conversion | Any custom object type you define, related to contacts through relationshipFields built as a named tuple. |
| Events | Into Conversion | Rows become timestamped events on contacts, and an eventId stops a repeated row from being recorded twice. |
How to connect ClickHouse
- 1 In the ClickHouse Cloud SQL console or clickhouse-client, create a role with SELECT and SHOW on the database you want to sync.
- 2 Create a dedicated user with a strong password and readonly = 2, and grant it the role.
- 3 Add Conversion's IP addresses to the service's IP Access List in ClickHouse Cloud, or allow them through your firewall on the HTTPS port if you self-host.
- 4 Under Settings > CRM & Syncing > Connections, add a ClickHouse connection with the host, HTTPS port, database, username, and password, then create your syncs.
