Trench: ClickHouse and Kafka Behind a Segment-Compatible Event API

The gap Trench fills between an event SDK and a data warehouse

Most teams that want product analytics face the same fork. They can send events to a hosted service and accept the vendor's schema and pricing, or they can stand up Kafka and ClickHouse themselves and spend weeks on ingest, batching, schema, and query endpoints. Trench is an attempt at the second path with the first path's interface. The README states it is compliant with the Segment API for Track, Group, and Identify calls, which means an existing Segment client library can point at a Trench URL instead of Segment's. That is the whole pitch: keep the client code, own the storage. The audience is engineers, not analysts. Nothing in the README describes a chart builder, a funnel editor, or a session replay view. It describes an endpoint that accepts JSON events, a store, and a SQL query interface. The demo video shows building a basic Google Analytics equivalent with Trench and Grafana, which tells you where the visualization layer is expected to come from.

Kafka in front, ClickHouse behind, Node.js at the edge

The architecture named in the repository description is ClickHouse, Kafka, and Node.js, and the README confirms the shape: an event tracking system built on top of Apache Kafka and ClickHouse. A POST to /events lands on the Node.js server, which publishes to a Kafka topic. A consumer reads from Kafka and writes into ClickHouse. Reads go the other way. The GET /events endpoint and the POST /queries endpoint both query ClickHouse and return JSON. Kafka is doing the buffering and decoupling work, so a slow or briefly unavailable ClickHouse does not immediately reject writes, and ClickHouse is doing the aggregation work that makes real-time queries feasible on large volumes. The split matters for operations: Kafka and ClickHouse are separate processes with separate failure modes, and the docker-compose.dev.yml file in the quickstart starts local instances of both. Whether you can run the Node.js layer against an external Kafka cluster and an external ClickHouse is implied by the Kafka authentication variables, which exist precisely because the brokers may live outside the compose file, but the README does not document an equivalent external-ClickHouse configuration.

Getting a local instance running from the quickstart

The README gives one prerequisite: Docker and Docker Compose. It recommends at least 4GB of RAM and 4 CPU cores for a production environment, which is a useful floor to note because ClickHouse and Kafka in one compose stack will consume most of it. The commands are four lines. Clone the repository, change into apps/trench, copy .env.example to .env, then run docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --build --force-recreate --renew-anon-volumes. The two-file compose invocation is the part worth reading twice: the base file defines the services and the dev file overrides them, so a production deployment would drop the second -f flag and supply its own overrides. The stack comes up on http://localhost:4000 and serves the text Trench server is running. Events go in with a bearer token taken from the public API key in .env, and the README's sample payload is a Segment-style track call with userId, type, event, and a properties object. Reads use the private key against GET /events?event=ConnectedAccount, and the response wraps rows in a results array alongside limit, offset, and total fields. Arbitrary SQL goes to POST /queries as an array of query strings, and the README's example is a COUNT(*) against the events table filtered by userId.

The queries endpoint is a SQL surface, and that shapes who can call it

POST /queries accepts raw SQL strings and runs them against ClickHouse. That is the most interesting and most dangerous part of the API. It is what makes Trench useful as infrastructure rather than as a fixed analytics product: you can write any aggregation ClickHouse supports without waiting for the project to add a feature. It also means the endpoint's authorization model is the only thing standing between a caller and the events table. The README's own example sends that request with the public API key, the same key type used to write events from a browser or client application. If that is the intended deployment, then any client holding the public key can run arbitrary SQL against the store. The README does not describe query restrictions, row-level filtering, or a separate read-only credential. Treat this as the first thing to resolve before exposing Trench beyond a trusted network, and check the API reference for whether the public and private key distinction is enforced differently than the examples suggest.

Where Trench is the wrong tool

Three cases stand out. First, if you need a dashboard today. The README offers no built-in visualization, and the path it demonstrates runs through Grafana. That is a reasonable choice for teams that already run Grafana, and a real cost for teams that do not. Second, if your data is not event-shaped. Trench is built around Track, Group, and Identify calls. Identity resolution, user profile merging, and cohort definitions are not described anywhere in the material, so a team expecting Segment's full identity graph should assume it is not there. Third, if you cannot operate Kafka. The single-image claim is about packaging, not about eliminating the operational surface. Kafka has partitions, retention, consumer group offsets, and rebalancing behavior, and the README's Kafka authentication section exists because real deployments connect to brokers with SASL and TLS rather than the local compose instance. A team without Kafka experience is taking on that learning curve along with ClickHouse's. The README also states the project was built to scale the event pipeline at Frigade, which is a fair signal about its design center but also means the documented path is the one that worked for that workload.

Compared with running ClickHouse and writing your own ingest

The honest alternative is not another analytics product. It is ClickHouse plus a small ingest service you write yourself, which is what Trench effectively is, minus the API contract. The difference is the contract. Trench implements the Segment Track, Group, and Identify shapes, so client libraries and existing integrations that speak Segment can target it without changes, and the event schema in ClickHouse is the project's decision rather than yours. If you write your own ingest, you control the table schema, the partitioning key, and the materialized views, and you pay for that control with the work of building and maintaining the HTTP layer, the batching, the retry behavior, and the Kafka consumer. Trench's value is that this layer already exists and is MIT licensed. Its cost is that you inherit someone else's schema and someone else's query endpoint. For a team whose analytics needs fit the Segment event model, that trade is favorable. For a team whose events are unusual, or whose queries need custom materialized views tuned to specific access patterns, the abstraction may get in the way more than it helps.

Licence, releases, and what maintenance looks like

Trench is MIT licensed, which permits commercial use, modification, and redistribution with the licence and copyright notice preserved. That is the permissive end of the spectrum and removes the licensing question that hangs over several analytics projects. The release history is thin and worth reading carefully. The listed releases are trench-js@0.0.17 and trench-js@0.0.16, both dated 2024-12-04, plus analytics-plugin-trench@0.0.9 from the same day. All three are 0.0.x versions of client-side packages, not of the server. The repository's last push is 2026-04-06, so the codebase has moved since those releases, but the published version numbers tell you the client packages are pre-1.0 and their APIs may change without a major-version signal. Anyone pinning trench-js in a production client should pin an exact version rather than a range. The server image has no version number in the material at all, which means upgrades are likely to mean rebuilding from a commit or a tag you select yourself, and you should read the diff between the commit you run and the one you move to. There is no documented migration path for the ClickHouse schema between versions, so treat schema changes as something to verify by reading the source before upgrading.

Editorial conclusion

Adopt Trench if you are an engineering team that already writes SQL against ClickHouse and wants a Segment-compatible ingest endpoint without running Segment or paying for a managed pipeline. Do not adopt it if you need a product analytics UI out of the box: the README points to Grafana and a demo video for that, not to a built-in dashboard. Before committing, verify two things on your own hardware: that the single-node throughput claim holds for your event shape, and that the queries endpoint is acceptable as a public interface, since the README shows it accepting a public API key. Check the .env.example in apps/trench for the full configuration surface, because the README documents only the Kafka authentication variables.

Official sources

1. FrigadeHQ/trench on GitHub
2. License: MIT
3. Project website
4. README
5. Releases