---
phase: 03-clickhouse-schema-migration
plan: 01
subsystem: database
tags: [clickhouse, schema, migration, rename-column]

requires:
  - phase: 02-test-hygiene
    provides: "Clean check-full baseline before schema changes"
provides:
  - "schema.sql with _us column naming throughout including v14.x migration section"
  - "Idempotent migration script for bigblack column rename (dry-run default)"
  - "_ensure_schema() DDL strings aligned with _us column names"
affects: [04-python-sql-rename, 05-rust-rename, 06-deploy-gap-repair]

tech-stack:
  added: []
  patterns: ["Dry-run-by-default migration scripts with --apply flag"]

key-files:
  created:
    - scripts/migrate_column_rename_us.py
  modified:
    - python/opendeviationbar/clickhouse/schema.sql
    - python/opendeviationbar/clickhouse/cache.py

key-decisions:
  - "Migration script checks both old and new column names for idempotency"
  - "RENAME COLUMN is metadata-only -- no data rewrite needed for 42M+ rows"

patterns-established:
  - "Migration script pattern: dry-run default, --apply flag, pre/post row count verification"

requirements-completed: [RENAME-01]

duration: 3min
completed: 2026-03-25
---

# Phase 03 Plan 01: ClickHouse Schema Migration Summary

**ClickHouse schema DDL and migration script updated from \_ms to \_us column naming with idempotent dry-run-default migration for bigblack**

## Performance

- **Duration:** 3 min
- **Started:** 2026-03-25T02:00:08Z
- **Completed:** 2026-03-25T02:03:17Z
- **Tasks:** 2
- **Files modified:** 3

## Accomplishments

- schema.sql has v14.x migration section documenting the \_ms to_us column rename with safety notes
- Migration script `scripts/migrate_column_rename_us.py` handles 3 tables/columns with idempotency detection
- All DDL strings in `_ensure_schema()` and `_migrate_auxiliary_tables()` now reference \_us column names

## Task Commits

Each task was committed atomically:

1. **Task 1: Update schema.sql migration comments and create migration script** - `9496c38` (feat)
2. **Task 2: Update \_ensure_schema() DDL strings from \_ms to \_us** - `a93e79b` (feat)

## Files Created/Modified

- `python/opendeviationbar/clickhouse/schema.sql` - Added v14.x migration section, updated Issue #164 and #158 comments to \_us
- `scripts/migrate_column_rename_us.py` - New migration script: dry-run default, --apply flag, idempotent, row count verification
- `python/opendeviationbar/clickhouse/cache.py` - \_ensure_schema() skip index, projection, legacy add column, data_freshness DDL all use_us

## Decisions Made

- Migration script detects already-renamed columns and exits cleanly (idempotent)
- ALTER TABLE RENAME COLUMN is metadata-only in ClickHouse, safe for 42M+ rows without downtime
- Query-path \_ms references in cache.py left untouched (Phase 4 scope: RENAME-02/04)

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None

## User Setup Required

None - no external service configuration required.

## Known Stubs

None - all code is fully wired.

## Next Phase Readiness

- RENAME-01 migration infrastructure complete
- Migration script ready for bigblack deploy (stop sidecar, run --apply, restart)
- Phase 04 (Python/SQL rename) can proceed independently

---

_Phase: 03-clickhouse-schema-migration_
_Completed: 2026-03-25_
