ClickHouse

Unkey generates a lot of usage data, such as API requests, system metrics, verification/ratelimit outcomes and more. Most of it we serve back to the user through our dashboard or API, but we also use this data internally to drive our billing and alerts.

ClickHouse is a perfect fit for us, for it's very high ingest capabilities and easy of querying through SQL.

We're using ClickHouse Cloud offering and run our staging and production clusters in AWS us-east-1

Working with ClickHouse

For development, we run ClickHouse inside our docker-compose setup and it will be autostarted and migrated for you.

The /internal/clickhouse package contains both the schema as well as a typescript client for inserting and querying. All queries/inserts must be defined in this package.

For migrations, we're using goose. This is only really relevant when migrating the staging and production clusters, as it is taken care of automatically during the docker compose setup.

While ClickHouse can ingest millions of rows per second, it can only achieve this with relatively large insert batches of tens of thousands of rows per request. This presents a challenge in our serverless setup, as most of our API invocations would only insert a single row per table. That's why we're using a ClickHouse Proxy for our inserts.

Databases

You can insert or query every database, but for logical separation, we're using the following:

verifications

Raw verifications are ingested here and we run hourly, daily and monthly aggregations for user facing analytics.

ratelimits

Raw ratelimits are ingested here and we run hourly, daily and monthly aggregations for user facing analytics.

billing

Aggregates data from other databases for creating invoices.

business

Aggregates data from other databases for creating internal dashboards.

metrics

Various system metrics, like API requests, latencies etc. Powering our Grafana dashboards and alerts.

IaC

Our ClickHouse clusters are fully managed in unkeyed/infra.