CLAUDE.md

1# ClickHouse Package
2 
3`@internal/clickhouse` - ClickHouse client for analytics and observability data.
4 
5## Migrations
6 
7Goose-format SQL migrations live in `schema/`. Two rules below are load-bearing — both can block a deploy.
8 
9### Rule 1: number to `max + 1`, never slot in
10 
11Goose runs in strict mode in the deploy pipeline. If a migration file numbered *below* the version currently recorded in `goose_db_version` ever shows up, goose refuses to apply it and the deploy fails:
12 
13```
14goose run: error: found 1 missing migrations before current version 30:
15  version 29: 029_add_task_kind_to_task_runs_v2.sql
16```
17 
18When adding a migration:
19 
201. Look at `schema/` and take the largest existing number, call it `N`.
212. Name your file `0(N+1)_descriptive_name.sql`.
223. If you've been on a branch while main added migrations, **rebase and renumber** before opening the PR — a file numbered below the new max will block the next deploy after your PR merges.
23 
24### Rule 2: DDL must be idempotent
25 
26Migrations can be applied out of order in some environments (`goose up --allow-missing` for local recovery, manual fixups, etc.) and may be retried. Always use idempotent forms so a re-apply is a no-op:
27 
28```sql
29-- +goose Up
30ALTER TABLE trigger_dev.your_table
31  ADD COLUMN IF NOT EXISTS new_column String DEFAULT '';
32 
33-- +goose Down
34ALTER TABLE trigger_dev.your_table
35  DROP COLUMN IF EXISTS new_column;
36```
37 
38Equivalent forms for other DDL:
39 
40- `CREATE TABLE IF NOT EXISTS …`
41- `DROP TABLE IF EXISTS …`
42- `ADD INDEX IF NOT EXISTS …` / `DROP INDEX IF EXISTS …`
43- `CREATE MATERIALIZED VIEW IF NOT EXISTS …` / `DROP VIEW IF EXISTS …`
44 
45ClickHouse supports `IF [NOT] EXISTS` on all of the above. Older migrations in this directory predate the rule and are not idempotent — leave them as-is unless you're explicitly hardening one.
46 
47## Naming Conventions
48 
49- `raw_` prefix for input tables (where data lands first)
50- `_v1`, `_v2` suffixes for table versioning
51- `_mv_v1` suffix for materialized views
52- `_per_day`, `_per_month` for aggregation tables
53 
54See `README.md` in this directory for full naming convention documentation.
55 
56## Purpose
57 
58Stores time-series data for task run analytics, event streams, and performance metrics. Separate from PostgreSQL to handle high-volume writes from task execution.
59