--- name: bijection-clickhouse description: "Evaluate and integrate the Clickhouse component with Bijection." --- # Clickhouse Buffered analytical event export - Package: @bijectionhq/clickhouse - Category: Analytics - Status: Preview - License: MIT - Bijection source (repository access required): https://github.com/bijectionhq/clickhouse/tree/24cf4910fe82aed34d05e7154fe9d3075a9650e4 - Upstream: https://github.com/robertalv/clickhouse/tree/df2e88357ca0e0f4529229e56d02db7f1a16843e - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/clickhouse ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/clickhouse.git cd clickhouse git checkout 24cf4910fe82aed34d05e7154fe9d3075a9650e4 ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes @devwithbobby/clickhouse. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. # ClickHouse ## Instructions Use ClickHouse to buffer analytics events in convex and batch-flush them to clickhouse cloud via http api, with configurable batch size, retries, and cron-based scheduling. This Convex component integrates directly with your backend. ### Installation ```bash npm install @devwithbobby/clickhouse ``` ### Capabilities - Decouple event ingestion from ClickHouse writes by buffering rows in Convex before flushing in configurable batches - Run read-only ClickHouse queries directly from Convex actions without managing a separate HTTP client - Control flush frequency and retry behavior through scheduler or cron integration without additional infrastructure - Keep ClickHouse credentials scoped to your Convex environment variables instead of exposing them client-side ## Examples ### how to send analytics events from Convex to ClickHouse 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. ### batch insert into ClickHouse from 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. ### query ClickHouse from a Convex action 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. ### how to test Convex components that use ClickHouse 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. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by ClickHouse is not needed ## Troubleshooting **How do I install and mount the ClickHouse Convex component?** 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. **Where should I store ClickHouse credentials when using this component?** 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. **Why does flushing happen in a Convex action instead of a mutation?** 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. **What table name formats does the ClickHouse component accept?** 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. **Does the component support retries when ClickHouse inserts fail?** 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. ## Resources - [npm package](https://www.npmjs.com/package/%40devwithbobby%2Fclickhouse) - [GitHub repository](https://github.com/robertalv/clickhouse) - [Live demo](https://robertalv.github.io/clickhouse/) - [Convex Components Directory](https://www.convex.dev/components/devwithbobby/clickhouse) - [Convex documentation](https://docs.convex.dev)