ClickHouse Deploy Integration
Overview
Deploy applications that connect to ClickHouse Cloud from serverless and
container platforms with proper connection management and secrets handling. The
same platform-agnostic connection module drives all three targets — Vercel,
Fly.io, and Cloud Run — so only the secrets mechanism and runtime model change
per platform.
Prerequisites
- ClickHouse Cloud instance (or self-hosted with public endpoint)
- Platform CLI installed (vercel, fly, or gcloud)
- Application tested locally against ClickHouse
Instructions
Step 1: ClickHouse Connection Module (Platform-Agnostic)
Write a singleton client so a serverless cold start reuses one connection
instead of opening a new pool per invocation. Keep max_open_connections low
for serverless and enable compression to cut egress.
import { createClient, ClickHouseClient } from '@clickhouse/client';
let client: ClickHouseClient | null = null;
export function getClickHouse(): ClickHouseClient {
if (!client) {
client = createClient({
url: process.env.CLICKHOUSE_HOST!,
username: process.env.CLICKHOUSE_USER!,
password: process.env.CLICKHOUSE_PASSWORD!,
database: process.env.CLICKHOUSE_DATABASE ?? 'default',
request_timeout: 30_000,
max_open_connections: 5,
compression: {
request: true,
response: true,
},
});
}
return client;
}
Step 2: Pick a platform and deploy
Choose the target that matches your runtime model, then set secrets and deploy.
All three import the getClickHouse() module above unchanged.
- Vercel (serverless functions) —
vercel env add per secret; best for API
endpoints. Keep max_open_connections at 1-3.
- Fly.io (containers) —
fly secrets set + a fly.toml health check; best
for long-running apps with persistent connections.
- Cloud Run (containers) — secrets via Secret Manager (
--set-secrets);
best for event-driven workloads. Set --min-instances=1 to avoid cold-start
connection churn.
Full per-platform commands, the Next.js App Router query example, fly.toml,
the Cloud Run deploy script, and a platform comparison table:
Platform deployment walkthrough.
Step 3: Add health check and graceful shutdown
Expose a /health endpoint that pings ClickHouse (drives Fly.io / Cloud Run
readiness probes) and close the client on SIGTERM/SIGINT so pending inserts
flush before the container is recycled. Full code:
Production patterns.
Output
Running this skill produces a deployable ClickHouse-connected application:
src/db.ts — a singleton ClickHouse client, serverless-safe and compressed.- Platform config with secrets set: Vercel env vars,
fly.toml + fly secrets,
or a Cloud Run service wired to Secret Manager.
- A
/health endpoint reporting { status, clickhouse: { connected, latencyMs } }.
- Graceful-shutdown handlers that flush pending inserts on
SIGTERM/SIGINT.
- A live deployment reachable over HTTPS on the chosen platform.
Error Handling
| Issue | Cause | Solution |
|---|
ECONNRESET on Vercel | Function timeout | Reduce query scope, increase timeout |
TLS handshake failed | Wrong port | Use port 8443 for Cloud |
| Secret not found | Env var not set | Check platform secret config |
| Cold start latency | New connection per invocation | Use min-instances=1 on Cloud Run |
Examples
Deploy an analytics API to Vercel: set the four CLICKHOUSE_* secrets with
vercel env add, drop the getClickHouse() module in src/db.ts, and add a
route that runs a parameterized SELECT ... GROUP BY event_type. See the full
Next.js App Router handler under the Vercel section of the
Platform deployment walkthrough.
Deploy a long-running container to Fly.io: add a [[http_service.checks]]
block pointing at /health, fly secrets set the ClickHouse credentials, then
fly deploy — see the complete fly.toml in the
Platform deployment walkthrough.
Deploy an event-driven service to Cloud Run: store host + password in Secret
Manager, wire them with --set-secrets, and set --min-instances=1. Full
deploy script in the
Platform deployment walkthrough.
Resources
Next Steps
For data ingestion patterns, see clickhouse-webhooks-events.
