Antigravity Agent
124 lines
4.4 KiB
Markdown
124 lines
4.4 KiB
Markdown
---
|
|
id: db-migration-safety
|
|
title: DB Migration Safety — Zero-downtime 전환 패턴
|
|
category: Coding
|
|
status: draft
|
|
source_trust_level: B
|
|
verification_status: conceptual
|
|
created_at: 2026-05-09
|
|
updated_at: 2026-05-09
|
|
tags: [database, migration, zero-downtime, postgres, vibe-coding]
|
|
tech_stack: { language: "SQL / Postgres / MySQL", applicable_to: ["Backend"] }
|
|
applied_in: []
|
|
aliases: [expand-contract, blue-green schema, online migration, lock-free]
|
|
---
|
|
|
|
# DB Migration Safety
|
|
|
|
> **Expand → Migrate → Contract** 3단계가 정답. 한 번에 schema + 코드 둘 다 못 바꾼다 — 둘이 동시에 deploy 안 되니까. NOT NULL 추가 / column rename / type change 가 가장 위험.
|
|
|
|
## 📖 핵심 개념
|
|
- **Expand**: 새 schema 추가. 옛 코드는 옛 schema 만 사용. 양립 가능.
|
|
- **Migrate**: 코드를 새 schema 로 이전. dual-write 또는 backfill.
|
|
- **Contract**: 옛 schema 제거.
|
|
- 각 단계는 별도 deploy. 사이에 모니터링 시간.
|
|
|
|
## 💻 코드 패턴
|
|
|
|
### Column rename `old_name → new_name`
|
|
|
|
#### Expand
|
|
```sql
|
|
ALTER TABLE users ADD COLUMN new_name TEXT;
|
|
-- Trigger: old_name 변경 시 new_name 동기화
|
|
CREATE OR REPLACE FUNCTION sync_name() RETURNS trigger AS $$
|
|
BEGIN NEW.new_name := COALESCE(NEW.new_name, NEW.old_name); RETURN NEW; END;
|
|
$$ LANGUAGE plpgsql;
|
|
CREATE TRIGGER trg_sync_name BEFORE INSERT OR UPDATE ON users
|
|
FOR EACH ROW EXECUTE PROCEDURE sync_name();
|
|
|
|
-- Backfill (낮 시간대 batch)
|
|
UPDATE users SET new_name = old_name WHERE new_name IS NULL;
|
|
```
|
|
|
|
#### Migrate (코드 deploy)
|
|
- 코드: 읽기는 `COALESCE(new_name, old_name)`, 쓰기는 둘 다.
|
|
|
|
#### Contract
|
|
```sql
|
|
DROP TRIGGER trg_sync_name ON users;
|
|
DROP FUNCTION sync_name();
|
|
ALTER TABLE users DROP COLUMN old_name;
|
|
```
|
|
|
|
### NOT NULL 추가 — 큰 테이블
|
|
|
|
```sql
|
|
-- ❌ 직접 NOT NULL — 대형 테이블 long lock
|
|
ALTER TABLE orders ALTER COLUMN status SET NOT NULL;
|
|
|
|
-- ✅ 단계별
|
|
-- 1) DEFAULT + NOT VALID CHECK
|
|
ALTER TABLE orders ADD CONSTRAINT orders_status_chk CHECK (status IS NOT NULL) NOT VALID;
|
|
-- 2) 기존 행 backfill
|
|
UPDATE orders SET status = 'pending' WHERE status IS NULL;
|
|
-- 3) constraint validate (read lock 만)
|
|
ALTER TABLE orders VALIDATE CONSTRAINT orders_status_chk;
|
|
-- 4) 진짜 NOT NULL (Postgres 12+ — fast path)
|
|
ALTER TABLE orders ALTER COLUMN status SET NOT NULL;
|
|
ALTER TABLE orders DROP CONSTRAINT orders_status_chk;
|
|
```
|
|
|
|
### Index 추가 — CONCURRENTLY (Postgres)
|
|
```sql
|
|
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
|
|
-- write block 안 함. 단 transaction 안에서는 못 씀.
|
|
```
|
|
|
|
### 큰 테이블 backfill — batch
|
|
```sql
|
|
-- 한 번에 1000행씩
|
|
DO $$
|
|
DECLARE batch INT := 1000;
|
|
BEGIN
|
|
LOOP
|
|
WITH ids AS (
|
|
SELECT id FROM orders WHERE new_field IS NULL LIMIT batch FOR UPDATE SKIP LOCKED
|
|
)
|
|
UPDATE orders SET new_field = compute(id) WHERE id IN (SELECT id FROM ids);
|
|
EXIT WHEN NOT FOUND;
|
|
PERFORM pg_sleep(0.1);
|
|
END LOOP;
|
|
END$$;
|
|
```
|
|
|
|
## 🤔 의사결정 기준
|
|
| 변경 | 안전 |
|
|
|---|---|
|
|
| Column 추가 (nullable) | ✅ 즉시 |
|
|
| Column 추가 + DEFAULT (Postgres 11+) | ✅ — fast path |
|
|
| NOT NULL 추가 | expand-contract |
|
|
| Column rename | expand-contract |
|
|
| Type change (varchar → text) | 보통 안전 — but 큰 테이블이면 점검 |
|
|
| Type change (int → bigint) | expand-contract |
|
|
| Drop column | expand-contract — 코드 먼저 안 쓰게 |
|
|
| Index 추가 | CONCURRENTLY |
|
|
| FK 추가 | NOT VALID + VALIDATE |
|
|
|
|
## ❌ 안티패턴
|
|
- **schema 변경과 코드 변경 한 deploy**: 둘이 정확히 동시 시작 못 함. 한 쪽만 적용된 짧은 시간 = 사고.
|
|
- **online migration 없는 큰 테이블 ALTER**: 수십 분 lock → 다운타임.
|
|
- **rollback 계획 없음**: 새 코드 + 새 schema deploy 후 문제 → 옛 코드 + 새 schema 인스턴스 발생 → 사고. expand-contract 면 자연 롤백.
|
|
- **production 에 직접 SQL**: history / review 없음. migration tool (Flyway / Prisma migrate / golang-migrate / dbmate) 사용.
|
|
- **migration 안에 비즈니스 로직**: 한 트랜잭션에 무거운 변환. 별도 backfill batch.
|
|
- **trigger 가 영구 남음**: contract 단계에서 trigger 제거 잊음.
|
|
- **dev 에서만 테스트**: 데이터 양이 다름. staging with prod-size dataset 검증.
|
|
|
|
## 🤖 LLM 활용 힌트
|
|
- "schema 변경 = expand-migrate-contract 3 deploy" 강제.
|
|
- 큰 테이블 ALTER 는 항상 단계별 + CONCURRENTLY 권장.
|
|
|
|
## 🔗 관련 문서
|
|
- [[DB_Connection_Pool]]
|
|
- [[Optimistic_Concurrency_Control]]
|