# Phase 3: ClickHouse Schema Migration - Context

**Gathered:** 2026-03-25
**Status:** Ready for planning
**Mode:** Auto-generated (infrastructure phase)

<domain>
## Phase Boundary

Rename ClickHouse columns `close_time_ms` → `close_time_us` and `open_time_ms` → `open_time_us` in the `open_deviation_bars` table. Since `close_time_ms` is part of the ORDER BY key, this requires table recreation (CREATE new → INSERT INTO → RENAME). Zero data loss mandatory.

</domain>

<decisions>
## Implementation Decisions

### Claude's Discretion

Key constraints:

- `close_time_ms` is referenced in ORDER BY — `ALTER TABLE RENAME COLUMN` alone won't work, need table recreation
- Follow the Partition Migration Checklist from odb-ship lessons (stop services → create new → copy → verify counts → atomic rename → OPTIMIZE FINAL → verify parts → restart)
- Schema.sql must be updated to use `_us` naming
- The skip index `idx_close_time` references `close_time_ms` — must be recreated
- All services MUST be stopped during migration (sidecar, kintsugi)
- This runs on bigblack via SSH — not a local operation

### CRITICAL: This phase produces a migration SCRIPT, not executes it

Since this requires SSH to bigblack and stopping production services, this phase should:

1. Update `schema.sql` with `_us` column names
2. Create a migration script that can be run manually on bigblack
3. Document the exact sequence of operations

The actual migration execution happens during the next `/odb-ship deploy`.

</decisions>

<canonical_refs>

## Canonical References

- `python/opendeviationbar/clickhouse/schema.sql` — current table DDL
- `CLAUDE.md` §"Partition Migration Checklist" — exact ordering for table recreation
- `.claude/skills/odb-ship/SKILL.md` §"4.1b" — mutation kill procedure
- `.claude/skills/ch-clean-slate/SKILL.md` — clean slate rebuild reference
  </canonical_refs>

<code_context>

## Existing Code Insights

- Current ORDER BY: `(symbol, threshold_decimal_bps, ouroboros_mode, first_agg_trade_id)`
- `close_time_ms` is NOT in ORDER BY (it was changed to `first_agg_trade_id` in a prior migration)
- Skip index: `INDEX idx_close_time close_time_ms TYPE minmax GRANULARITY 8192`
- PARTITION BY: `(symbol, threshold_decimal_bps)`
- Since close_time_ms is NOT in ORDER BY, `ALTER TABLE RENAME COLUMN` MAY work directly
  </code_context>

<specifics>
No specific requirements.
</specifics>

<deferred>
None.
</deferred>

---

_Phase: 03-clickhouse-schema-migration_
_Context gathered: 2026-03-25_
