Send events to ClickHouse
High-throughput row-shaped event delivery into a customer's ClickHouse cluster, one row per event.
What is ClickHouse?
ClickHouse is an open-source columnar OLAP database known for sub-second analytics over billions of rows. As a destination, it gives data teams a place to run high-cardinality, real-time analytics over your product events without paying warehouse-style compute costs. Pushrail's ClickHouse adapter inserts one row per event using the native protocol with column-level type mapping.
Why deliver events to ClickHouse
- Sub-second queries over billions of events without warehouse-scale compute bills.
- Realtime dashboards, events are queryable seconds after ingestion.
- Self-hosted or ClickHouse Cloud, works against either.
- Compresses well, historical event archives stay cheap.
How Pushrail delivers events to ClickHouse
The ClickHouse adapter uses the native binary protocol with batched INSERTs into a table whose shape matches the canonical envelope: `event_id` (UUID), `event_type` (LowCardinality(String)), `occurred_at` (DateTime64(3)), `customer_external_id` (String), `source` (LowCardinality(String)), `payload` (JSON or String), `metadata` (JSON or String), `received_at` (DateTime64(3)). Batches are tuned per the ClickHouse server's recommended insert size to keep merges efficient.
Auth and credentials
Pushrail connects with username/password over TLS (default) or with a TLS client certificate (recommended for cloud deployments). Credentials are stored encrypted at rest. The customer creates a dedicated `pushrail_writer` user with `INSERT` on the destination database and grants no other privileges; rotations happen by adding a new user in ClickHouse and swapping the credential in Pushrail.
Batching, retries, and replay
Default batches are 10,000 events or 5 MB with a 5-second flush, tuned for ClickHouse's preference for larger batches. Transient errors (network, timeouts, 503) retry with exponential backoff. Permanent errors (auth, schema mismatch) land in the DLQ. Replay re-runs the INSERTs; the table includes the `event_id` as a primary key component, so customers using ReplacingMergeTree get natural deduplication on re-runs.
Example payload
Pushrail accepts the canonical event shape on POST /v1/events. Below is the ingestion request your service makes.
{
"eventType": "order.completed",
"occurredAt": "2026-05-26T14:21:08.493Z",
"source": "billing-service",
"customerExternalId": "acct_8K2zRq",
"idempotencyKey": "order_38a91f-completed",
"correlationId": "req_4f30b2",
"payload": {
"orderId": "ord_38a91f",
"amount": 12900,
"currency": "USD",
"items": [
{ "sku": "PR-PRO-MONTHLY", "qty": 1, "price": 12900 }
]
},
"metadata": {
"tier": "pro",
"region": "us-east-1"
}
}Example configuration
The fields your customer fills in to point Pushrail at their ClickHouse setup.
{
"type": "CLICKHOUSE",
"name": "Customer ClickHouse",
"host": "acme-prod.clickhouse.cloud",
"port": 9440,
"tls": true,
"database": "pushrail_events",
"tableEngine": "ReplacingMergeTree",
"auth": {
"mode": "PASSWORD",
"username": "pushrail_writer",
"password": "••••••••"
},
"batchSize": 10000,
"flushIntervalSec": 5
}Common use cases
- Power customer-built analytics dashboards over high-cardinality event data.
- Feed an in-product analytics view that queries millions of events without warehouse latency.
- Provide cheap long-term event storage with fast ad-hoc query.
- Backbone for customer ML feature engineering over event history.
Related destinations
Stream events directly into a customer's BigQuery dataset, table per event type or single wide table.
Continuous ingest into a customer-owned Snowflake table via Snowpipe-style staging.
Native Kafka producer with SASL/TLS, deliver events into a customer's topic with configurable partitioning.
Frequently asked questions
How does Pushrail write to ClickHouse?
The adapter uses the native binary protocol with batched INSERTs into a table whose columns match the canonical envelope (event_id, event_type, occurred_at, customer_external_id, source, payload, metadata, received_at). You send one canonical event to Pushrail and it handles batching and type mapping.
Does this work with both self-hosted and ClickHouse Cloud?
Yes. The adapter connects to either a self-hosted cluster or ClickHouse Cloud. It uses username/password over TLS by default, or a TLS client certificate, which is recommended for cloud deployments.
Whose credentials are used?
The customer's. They create a dedicated pushrail_writer user with INSERT on the destination database and no other privileges; credentials are stored encrypted at rest. Rotations happen by adding a new user in ClickHouse and swapping the credential in Pushrail.
What happens on a failed insert, and are replays safe?
Transient errors (network, timeouts, 503) retry with exponential backoff; permanent errors (auth, schema mismatch) land in the dead-letter queue. Every attempt is recorded in the delivery logs. Because event_id is part of the primary key, customers using ReplacingMergeTree get natural deduplication on replayed re-runs.