ClickHouse

GitLab's OLAP database for analytics that don't fit Postgres.

Purpose

Run wide aggregations (millions to billions of rows) for analytics features without overwhelming the OLTP databases.

Source

Concern	Location
Library	lib/click_house/
Models	app/models/click_house/
Migrations	db/click_house/
Schema validators	scripts/lint-clickhouse-migrations.sh, scripts/validate_clickhouse_schema.rb
Stored procedures	lib/click_house/migration_support/
Settings	config/click_house.yml.example

What's stored

• Audit events (long retention).
• DORA metrics aggregations.
• Value Stream Analytics events.
• Internal events (high-volume product analytics).
• Build trace tokens for searching.
• Embeddings (via pgvector or native ClickHouse vector).

Migrations

ClickHouse has its own migration mechanism, similar to Rails migrations:

db/click_house/
├── main/
│   └── <timestamp>_create_some_table.rb
└── ...

Each migration uses ClickHouse-specific helpers. The validator scripts/validate_clickhouse_schema.rb keeps the schema dumps in sync.

Querying

ClickHouse::Client provides:

result = ClickHouse::Client.select(query, :main)

Models under app/models/click_house/ wrap commonly-used queries. They're not ActiveRecord — they're plain Ruby with a select API.

Active Context

gems/gitlab-active-context/ defines an abstraction over multiple stores (Postgres, ClickHouse, OpenSearch, dedicated vector DBs). The codebase uses it for retrieval-augmented features. See Search.

Production deployment

ClickHouse runs as a separate cluster (or managed service). The Rails monolith has read/write credentials in config/click_house.yml. Self-managed operators can disable ClickHouse — features that need it gracefully degrade.

Related

• Search.
• Internal events.
• Database.