BAT-025 Design

D-1. Revision graph and parent

구현 시작 직전 uv run alembic heads 및 uv run alembic history로 유효 head를 재확인한다. 신규 revision은 그 실제 head 하나를 down_revision으로 사용하며, 문서/코드에 20260628_0027을 선결 가정으로 고정하지 않는다.

D-2. Migration idempotency

신규 revision은 inspector/information_schema 기반으로 table/column 존재를 확인한다.

portfolio_ledger가 정상적으로 존재하는 일반 경로에서는 네 컬럼을 추가한다.
runtime ensure_schema()가 이미 컬럼을 생성한 경로에서는 컬럼 재생성 없이 nullable/default를 검증·보정한다.
source는 upgrade 전에 NULL을 'broker'로 backfill하고 이후 NOT NULL DEFAULT 'broker'를 보장한다.
기존 행은 삭제·재작성하지 않으며 upgrade 전후 row count와 business field를 비교한다.
down migration은 운영 forward-only 정책과 충돌하지 않도록 구현 범위를 명시하고, 운영 runbook은 column deletion을 rollback으로 제시하지 않는다.

D-3. Runtime boundary

app/repositories/postgres.py:ensure_schema()는 bootstrap safety 경로로 유지한다. Alembic revision은 persistent schema history의 source of truth로 둔다. migration 성공만으로 version table을 임의 stamp하지 않으며, schema와 Alembic current가 함께 일치하는지 검증한다.

D-4. Test matrix

시작 상태	검증
fresh Alembic schema	upgrade, 네 컬럼 타입/nullable/default, current/head
기존 ledger rows	row count/business data 보존, source broker backfill
runtime-precreated columns	중복 DDL 부재, constraints/default 정합, current/head
broker write	기존 `/ledger/trades` 회귀 없음
manual API	source/manual metadata 및 REQ-056 핵심 regression
runbook	preflight 조건, 실패 중단, forward-only recovery 문서 정합

D-5. Operational gate

이번 batch는 local/non-production verification만 수행한다. 운영 DB backup/upgrade, service restart, 신규 API activation, deploy/push/merge는 M5 Release의 별도 결재 없이는 실행하지 않는다. runbook은 실행 가능한 명령 템플릿과 중단 조건을 제공하되 실제 운영 결과를 가장하지 않는다.

Design decisions / open findings

실제 revision ID는 구현 preflight 결과로 결정한다.
실제 DB driver availability에 따라 migration integration test harness는 repository 표준 fixture 또는 isolated PostgreSQL 경로를 사용하되, 사용하지 못한 환경은 QC evidence에 명시한다.
stamp 필요성은 schema inspection과 version table evidence 이후에만 판단하며 자동 조치하지 않는다.

2.7 KiB Raw Blame History