portfolio-hub/docs/runbooks/bat-025-req057-portfolio-ledger-manual-metadata-runbook.md

운영 적용 런북: REQ-057 — portfolio_ledger 수동 장부 메타데이터 migration

• Batch: BAT-025
• Discovery: dcy-012
• Date: 2026-07-15
• 결재 게이트: REQ-057 완료 승인 및 release 결재 필수
• 작업 예상 시간: 약 20~40분

---

전제 조건

• DB 백업 완료
• PORTFOLIOHUB_DB_ENABLED=true 및 DB 접속 환경변수 설정
• 대상 DB는 alembic current로 20260628_0027 상태(또는 그 이전 배포 라인)에서 진행
• 새 코드 배포는 alembic upgrade 20260715_0028 완료 + 검증 성공 및 M5 Release 결재 후에만 수행

주의: 운영 DB는 본 배치에서 실제 upgrade/runbook 실행 대상을 만들지 않는다. 아래는 실운영 적용 체크리스트이다.

---

0) 사전 점검

export TIMESCALEDB_HOST=<DB_HOST>
export TIMESCALEDB_PORT=<DB_PORT>
export TIMESCALEDB_NAME=<DB_NAME>
export TIMESCALEDB_USER=<DB_USER>
export TIMESCALEDB_PASSWORD=<DB_PASS>
export PORTFOLIOHUB_DB_ENABLED=true

alembic heads
alembic current

• alembic heads에는 구현 시점 head 20260715_0028가 확인되어야 한다.
• alembic current 값이 20260715_0028이면 이미 마이그레이션 적용 완료 상태다.

1) 프리체크

1-1. 대기 중인 락/액티브 커넥션

SELECT pid, usename, application_name, state, wait_event_type, wait_event, query
FROM pg_stat_activity
WHERE query ILIKE '%portfolio_ledger%'
  AND state != 'idle';

• 결과는 반드시 비어 있거나 승인된 윈도우에서만 허용.

1-2. 대상 스키마 및 데이터 건수

-- 현재 컬럼 상태
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'portfolio_ledger'
  AND column_name IN ('source', 'target_ledger_entry_id', 'confirmation_evidence', 'actor_user_id')
ORDER BY column_name;

-- 기존 행 수(증적)
SELECT COUNT(*) AS rows FROM portfolio_ledger;

• source가 이미 없거나 NULL 허용 상태여도 업그레이드 실행 전/후로 수렴 가능.

---

2) 마이그레이션 실행

alembic upgrade 20260715_0028

수신 메시지 예시

• 정상: Running upgrade ... 형태로 revision 로그 출력
• 실패: 즉시 종료되며 partial 변경 여부는 로그로 확인

---

3) 사후 검증

SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'portfolio_ledger'
  AND column_name IN ('source', 'target_ledger_entry_id', 'confirmation_evidence', 'actor_user_id')
ORDER BY column_name;

-- source backfill 결과(0이어야 함)
SELECT COUNT(*) AS null_source_rows
FROM portfolio_ledger
WHERE source IS NULL;

SELECT COUNT(*) AS rows_after FROM portfolio_ledger;
SELECT column_name, is_nullable
FROM information_schema.columns
WHERE table_name = 'portfolio_ledger' AND column_name = 'source';
SELECT column_default
FROM information_schema.columns
WHERE table_name = 'portfolio_ledger'
  AND column_name = 'source';

• 기대치: source가 NOT NULL, DEFAULT 'broker', null_source_rows = 0
• rows_after 값은 프리체크 시점과 일치해야 한다.
• alembic current가 20260715_0028로 일치해야 한다.

alembic current

---

4) 실패 대응 (Forward-only)

• 업그레이드 실패 시 바로 이전 코드로 rollback은 허용하되, 본 migration에서 추가된 4개 컬럼은 운영에서 자동 삭제하지 않는다.
• 필요한 경우 운영 담당과 협의하여 수동 복구 계획을 수립한다.
• 필수 검토 항목: 대상 DB 백업 상태, 실행 로그, 에러 스택, 락/동시 접속 상태

---

5) 운영 활성화 조건

• 위 사후 검증(alembic current/schema/row count/source null 없음) 완료
• API smoke(REQ-056 manual ledger) 통과
• release 결재 완료
• 위 조건 충족 시 신규 코드 재시작 및 API 활성화 수행