feat(docker): add ClickHouse service for local development

[koxudaxi]

Add ClickHouse for Analytics

TL;DR

Add ClickHouse database for analytics with tables for spans and annotations.

What changed?

• Added ClickHouse service to Docker Compose configuration
• Created SQL schema for spans_analytics table with optimized structure for OLAP queries
• Created SQL schema for annotations_analytics table to track span annotations
• Added npm scripts for managing the ClickHouse service

The spans table includes:

• Core span identifiers and relationships
• Multi-tenant support columns
• Timing information
• LLM-specific fields (tokens, costs, etc.)
• Compressed attribute storage
• Optimized indexes for common query patterns

How to test?

1. Start the ClickHouse service:

   npm run clickhouse:start
   

2. Connect to ClickHouse using the web interface at http://localhost:8123 or CLI client

   • Username: default
   • Password: clickhouse
   • Database: mirascope_analytics

3. Verify tables were created:

   SHOW TABLES;
   DESCRIBE TABLE spans_analytics;
   DESCRIBE TABLE annotations_analytics;

4. Stop the service when done:

   npm run clickhouse:stop
   

Why make this change?

This adds analytical capabilities to support complex queries across span data without impacting the performance of the transactional PostgreSQL database. ClickHouse's columnar storage is optimized for OLAP workloads, enabling efficient aggregation and filtering across large volumes of trace data.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	v2-docs	145ccd6	Jan 09 2026, 03:31 AM

[koxudaxi]

• feat(docker): add ClickHouse service for local development #1807 : 2 dependent PRs (#1808 , #1819 ) 👈 (View in Graphite)
• feat(clickhouse): add clickhouse migrations and migrate tooling #1849
• v2

This stack of pull requests is managed by Graphite. Learn more about stacking.

[gitguardian]

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

---

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}

[willbakst]

Merge activity

• Jan 9, 1:29 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jan 9, 1:29 AM UTC: Graphite couldn't merge this pull request because a downstack PR feat(clickhouse): add clickhouse migrations and migrate tooling #1849 failed to merge.
• Jan 9, 1:40 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jan 9, 1:41 AM UTC: Graphite couldn't merge this pull request because a downstack PR feat(clickhouse): add clickhouse migrations and migrate tooling #1849 failed to merge.
• Jan 9, 3:23 AM UTC: @willbakst merged this pull request with Graphite.