ClickHouse

ClickHouse is an open-source column-oriented DBMS for online analytical processing (OLAP) that allows users to generate analytical reports using SQL queries in real-time. It is well suited for high-volume event data where fast aggregations matter.

Connect via Cloud Mode

In Cloud mode, DataBridge connects directly to your ClickHouse instance over the network.

1. Go to Data Stores and click Connect New
2. Select ClickHouse
3. Keep the connection mode set to Cloud (default)
4. Fill in the connection details:
   • Name - a display label (e.g., "ClickHouse Production")
   • Hosts - comma-separated list of host:port entries (e.g., ch-node1.example.com:9440)
   • Username and Password
   • Cluster - cluster name if running in cluster mode; leave empty for single-node
   • Database - target database name (e.g., default)
5. Click Test Connection to verify connectivity
6. Click Save

Connect via DataBridge Agent

In Agent mode, the DataBridge Agent running in your infrastructure handles the connection. No credentials are sent to the cloud.

1. Go to Data Stores and click Connect New
2. Select ClickHouse
3. Switch the connection mode to Agent
4. Fill in:
   • Name - a display label
   • Connection Alias - must match an alias defined in the agent's config.yaml
5. Click Save

The agent resolves the alias to the full connection configuration locally and can access ClickHouse from within your network.

Configuration Reference

Name	Required	Description	Default
Protocol	Yes	Connection protocol: http, https, clickhouse, clickhouse-secure	http
Hosts	Yes	List of ClickHouse servers as host:port (comma-separated). If port is omitted, the protocol default is used.	localhost:8123
Username	Yes	Username for authentication
Password	Yes	Password for authentication
Cluster	No	Cluster name. Leave empty for single-node deployments.
Database	Yes	Target database name	default
Parameters	No	Additional key-value driver parameters (see ClickHouse Go driver docs)

Protocol and Default Ports

Protocol	Default Port	Description
http	8123	HTTP interface (unencrypted)
https	8443	HTTP interface with TLS
clickhouse	9000	Native TCP protocol (unencrypted)
clickhouse-secure	9440	Native TCP protocol with TLS

warning

Use https or clickhouse-secure for production deployments to encrypt data in transit.

Schema-Driven Column Types

When a JSON Schema is registered for an event, DataBridge maps each top-level property to a native ClickHouse column type:

JSON Schema Type	ClickHouse Column Type
string	String
string with format: "date-time"	DateTime64(3)
integer	Int64
number	Float64
boolean	Bool
object	String (JSON-encoded)
array	String (JSON-encoded)

Every table also includes two metadata columns: ref_url_id String and event_id String.

Optional properties (not listed in required) are wrapped with Nullable(). Tables use the MergeTree() engine ordered by event_id.

If no schema is registered, the table falls back to the simplified three-column layout (ref_url_id, event_id, payload).

Testing the Connection

In Cloud mode, click Test Connection in the connection dialog before saving. DataBridge sends a ping to your ClickHouse instance and reports success or failure.

In Agent mode, test connectivity from the machine running the agent:

# HTTP protocol
curl http://your-clickhouse-host:8123/ping

# Native protocol - verify port is open
nc -zv your-clickhouse-host 9000

Required Permissions

The ClickHouse user needs the following privileges on the target database:

GRANT CREATE TABLE, INSERT, ALTER TABLE ON my_database.* TO 'databridge_user';

Troubleshooting

Connection timed out

• Verify the host and port are correct for the selected protocol
• Check that firewall rules or security groups allow inbound traffic on the port
• For Cloud mode, ensure your ClickHouse instance is reachable from the internet (or whitelist DataBridge IPs)

Authentication failed

• Confirm the username and password are correct
• Check that the user has access to the specified database

Table creation errors

• Ensure the user has CREATE TABLE privileges on the target database
• If using a cluster, verify the cluster name matches your ClickHouse configuration

Cluster vs. single-node

• Leave the Cluster field empty when running a single ClickHouse server
• When running a cluster, provide the cluster name so DataBridge creates distributed tables correctly

Tips

• For high-throughput workloads, use the native clickhouse-secure protocol - it is more efficient than HTTP for bulk inserts
• When connecting to ClickHouse Cloud, use https protocol with port 8443
• Use the Parameters field to pass driver-specific options such as max_execution_time, compress, or connection_open_strategy