Buffer analytics events in Convex and batch-flush them to ClickHouse Cloud via HTTP API, with configurable batch size, retries, and cron-based scheduling.
npm install @devwithbobby/clickhouseThis component buffers analytics events in Convex's database and flushes them in batches to ClickHouse Cloud via the ClickHouse HTTP API. It decouples high-frequency write operations from synchronous external HTTP calls by staging rows locally and draining them through a separate action, typically triggered by a cron or scheduler. Configurable batch size, retry logic, and a read-only query interface round out the integration surface.
The @devwithbobby/clickhouse component lets you call clickhouse.insert() inside a Convex mutation to buffer rows into Convex storage, then call clickhouse.flush() from a Convex action triggered by a cron or scheduler to batch-send those rows to ClickHouse Cloud over the HTTP API. This avoids making HTTP calls from mutations, which are not supported in Convex.
The @devwithbobby/clickhouse component buffers inserted rows in Convex and flushes them in configurable batches using the batchSize option, defaulting behavior you control at initialization. The flush action returns counts of flushed and failed rows along with any error messages, making it straightforward to monitor delivery.
The @devwithbobby/clickhouse component exposes a query() method callable from Convex actions that accepts a SQL string and returns typed rows. It restricts input to read-only statements starting with SELECT, WITH, SHOW, DESCRIBE, DESC, or EXPLAIN to prevent accidental writes.
The @devwithbobby/clickhouse package exports a clickhouseTest helper compatible with convex-test. You register it with your convexTest instance using clickhouseTest.register(t), which allows unit tests to run without a live ClickHouse connection.
Run npm install @devwithbobby/clickhouse, then mount the component in convex/convex.config.ts by importing clickhouse from @devwithbobby/clickhouse/convex.config.js and calling app.use(clickhouse). After mounting, create a wrapper file in your convex directory that initializes a ClickHouse instance with your credentials, batch size, and retry settings.
The @devwithbobby/clickhouse component expects credentials to be provided via a function that reads from Convex environment variables, such as process.env.CLICKHOUSE_URL, process.env.CLICKHOUSE_USER, and process.env.CLICKHOUSE_PASSWORD. This keeps credentials out of client-side code and version control.
Convex mutations cannot make outbound HTTP requests. The @devwithbobby/clickhouse component separates concerns by buffering rows during mutations and performing the actual HTTP POST to ClickHouse Cloud inside a Convex action, which supports calling external APIs. The flush action is typically scheduled via a Convex cron or scheduler.
The @devwithbobby/clickhouse component validates and quotes table names before inserting. Valid formats include simple names like events or database-qualified names like analytics.events. Names that do not match the expected pattern are rejected before any HTTP call is made.
Yes. The @devwithbobby/clickhouse component accepts a maxRetries option at initialization that controls how many times a flush will retry failed batches before giving up. The flush action returns a result object with flushed count, failed count, and an array of error strings for observability.