기본 Skill 4 - postgres-migration

PostgreSQL의 테이블, 컬럼, 제약조건, 인덱스, 데이터 보정 작업을 항상 같은 검토 절차로 수행하게 한다.

 

경로 : .agents/skills/postgres-migration/SKILL.md

 

---
name: postgres-migration
description: 저장소에서 현재 사용하고 있는 마이그레이션 도구를 이용하여 PostgreSQL 스키마 및 데이터 마이그레이션을 계획하고, 생성하거나 검토한다. 테이블, 컬럼, 제약조건, 인덱스, ENUM, 시퀀스 또는 기존 데이터 보정 작업에 사용한다. 애플리케이션 코드만 변경하는 작업이나 스키마 변경이 필요하지 않은 일반적인 SELECT 쿼리 튜닝에는 사용하지 않는다.
---

# 목적

저장소의 기존 규칙을 따르면서 PostgreSQL 마이그레이션 작업을 안전하고, 점진적이며, 일관되게 수행한다.

# 기본 행동

- 사용자가 분석이나 검토를 요청한 경우에는 파일을 수정하지 않는다.

- 사용자가 구현을 명시적으로 요청한 경우에도 파일을 수정하기 전에 현재 상태를 확인하고 작업 계획을 작성한다.

- Flyway 또는 Liquibase를 사용한다고 임의로 가정하지 않는다. 저장소에서 이미 사용하고 있는 마이그레이션 도구를 확인하여 그대로 사용한다.

- 저장소에 마이그레이션 도구가 없다면 해당 사실을 보고하고, 새로운 도구를 도입하기 전에 작업을 중단한다.

- 운영 데이터베이스에 접근하거나 운영 데이터베이스를 수정하지 않는다.

# 필수 확인 자료

변경사항을 만들기 전에 다음 내용을 확인한다.

1. 프로젝트 루트의 `AGENTS.md`를 읽는다.

2. 가장 가까운 백엔드 또는 데이터베이스 관련 `AGENTS.md`를 읽는다.

3. 저장소의 데이터베이스 및 마이그레이션 문서를 읽는다.

4. Build 설정을 확인한다.

5. 마이그레이션 설정과 최근 마이그레이션 파일을 확인한다.

6. 요청한 변경사항의 영향을 받는 Entity, Repository, Query 및 테스트를 확인한다.

# 작업 절차

## 1. 현재 상태 확인

다음 내용을 확인한다.

- 프로젝트에서 사용하는 PostgreSQL 버전
- 마이그레이션 도구와 마이그레이션 파일 경로
- 마이그레이션 파일 명명 규칙
- 현재 테이블 및 컬럼 정의
- 이미 존재하는 제약조건과 인덱스
- 영향을 받는 데이터를 읽거나 저장하는 애플리케이션 코드
- 새로운 스키마 조건을 위반할 가능성이 있는 기존 데이터
- 저장소 문서에 정의된 배포 관련 전제조건

ORM Entity 정의만 보고 현재 데이터베이스 상태를 판단하지 않는다.

스키마가 어떻게 변경되어 왔는지를 판단하는 기준 정보는 마이그레이션 이력이다.

## 2. 변경 유형 분류

요청한 작업을 다음 유형 중 하나 이상으로 분류한다.

- 새로운 구조를 추가하는 스키마 변경
- 제약조건 변경
- 인덱스 변경
- 기존 데이터 보정
- 이름 변경
- 데이터 타입 변환
- 데이터를 삭제하거나 기존 구조를 제거하는 파괴적 스키마 변경
- 호환성 또는 배포 순서와 관련된 변경

파일을 수정하기 전에 변경 유형을 먼저 보고한다.

## 3. 위험 평가

다음 위험이 있는지 확인한다.

- 데이터가 손실될 가능성
- 기존 `NULL` 값
- 기존 중복 값
- 유효하지 않은 외래키 값
- 테이블 잠금
- 오랜 시간이 걸릴 수 있는 데이터 변경 작업
- 배포 중 애플리케이션 호환성
- 롤백 또는 복구의 어려움
- 기존 Query와 인덱스에 미치는 영향

파괴적인 변경, 데이터 타입의 허용 범위를 줄이는 변경, 이름 변경 또는 컬럼 삭제의 경우에는 마이그레이션 전략이 명확해질 때까지 파일을 수정하지 않는다.

즉시 파괴적인 변경을 적용하면 호환성이 깨질 수 있는 경우에는 `확장-마이그레이션-축소` 방식의 접근을 우선한다.

1. 새로운 구조를 추가한다.

2. 기존 데이터를 변경하거나 새로운 구조에 맞게 보정한다.

3. 기존 구조와 새로운 구조를 모두 처리할 수 있는 호환 가능한 애플리케이션 코드를 배포한다.

4. 새로운 구조가 실제로 사용되고 있는지 확인한다.

5. 이후 별도의 마이그레이션에서 기존 구조를 제거한다.

## 4. 작업 계획 보고

파일을 수정하기 전에 다음 내용을 보고한다.

- 새로 추가하거나 수정할 파일
- 마이그레이션 유형
- 기존 데이터 보정 방법
- 애플리케이션 호환성에 미치는 영향
- 실행할 검증 명령
- 아직 해결되지 않은 위험

제안하는 변경사항을 사용자가 요청한 범위로 제한한다.

## 5. 마이그레이션 생성

다음 규칙을 따른다.

- 새로운 버전의 마이그레이션 파일을 생성한다.

- 이미 적용되었을 가능성이 있는 기존 마이그레이션 파일은 절대로 수정하지 않는다.

- 저장소의 기존 파일 명명 규칙과 SQL 작성 형식을 따른다.

- 제약조건과 인덱스에 명시적인 이름을 지정한다.

- 실제 데이터 규칙을 나타내는 경우에는 데이터베이스 제약조건을 추가한다.

- 어떤 Query를 지원하기 위한 것인지 확인하지 않고 인덱스를 추가하지 않는다.

- 기존 데이터에 `NULL` 값이 있을 가능성을 처리하지 않은 상태에서 `NOT NULL` 제약조건을 추가하지 않는다.

- 기존 중복 데이터를 확인하지 않은 상태에서 `UNIQUE` 제약조건을 추가하지 않는다.

- 기존 데이터를 사용자에게 알리지 않고 삭제하거나 변경하지 않는다.

- 하나의 마이그레이션에 서로 관련 없는 스키마 변경사항을 함께 넣지 않는다.

- 사용자의 명시적인 승인 없이 새로운 마이그레이션 라이브러리를 추가하지 않는다.

- 저장소의 트랜잭션 전략과 충돌하는 PostgreSQL 전용 기능을 사용할 때는 그 이유를 문서화한다.

## 6. 관련 코드 변경

승인된 작업 범위에서 반드시 필요한 경우에만 다음 항목을 변경한다.

- 영속성 매핑
- 요청 DTO 및 응답 DTO
- 입력값 검증
- Repository 및 Query
- 테스트 Fixture
- 초기 데이터 또는 Seed 데이터
- 데이터베이스 문서

요청과 관련 없는 리팩터링은 수행하지 않는다.

## 7. 검증

`AGENTS.md`에 정의된 명령을 사용한다.

해당되는 경우 최소한 다음 내용을 검증한다.

1. 비어 있는 테스트 데이터베이스에 전체 마이그레이션이 정상적으로 적용된다.

2. 저장소에 업그레이드 경로 테스트가 있다면, 이전 스키마 상태에서 새로운 마이그레이션이 정상적으로 적용된다.

3. 제약조건이 유효하지 않은 데이터를 정상적으로 거부한다.

4. 기존의 유효한 데이터를 계속 정상적으로 읽을 수 있다.

5. 보정된 데이터가 예상한 값을 가지고 있다.

6. 영향을 받는 Repository 테스트와 통합 테스트가 통과한다.

7. 백엔드 Build가 통과한다.

8. 인덱스가 의도한 Query 유형을 지원한다.

9. 기존 마이그레이션 파일이 수정되지 않았다.

검증을 수행할 수 없다면 해당 항목을 실행하지 않았다고 보고한다.

SQL 내용을 눈으로 확인한 것만으로 성공했다고 보고하지 않는다.

# 검토 모드

기존 마이그레이션을 검토할 때는 다음 절차를 따른다.

1. 파일을 수정하지 않는다.

2. 마이그레이션 파일과 관련 애플리케이션 코드를 확인한다.

3. 데이터 손실 위험과 호환성 위험을 확인한다.

4. `NULL`, 중복 데이터 및 외래키 관련 가정을 확인한다.

5. 트랜잭션과 테이블 잠금에 미치는 영향을 확인한다.

6. 테스트가 유효한 데이터와 유효하지 않은 데이터를 모두 검증하는지 확인한다.

7. 발견한 문제를 심각도에 따라 구분하여 보고한다.

# 필수 최종 보고서

## 마이그레이션 요약

어떤 스키마 또는 데이터 변경을 수행했는지 설명한다.

## 변경된 파일

변경한 모든 파일과 각 파일을 변경한 이유를 작성한다.

## 호환성

애플리케이션 및 배포 호환성에 미치는 영향을 설명한다.

## 데이터 처리

기존 데이터 검증, 데이터 보정 및 기존 데이터 보존 방법을 설명한다.

## 검증

실행한 각 명령과 결과를 작성하고, 성공·실패·실행하지 않음 중 어떤 상태인지 명시한다.

## 남아 있는 위험

아직 해결되지 않은 위험과 운영 시 고려사항을 작성한다.

# 금지 사항

- 운영 데이터베이스에 연결하지 않는다.

- 어떤 데이터베이스인지 명확하지 않은 상태에서 파괴적인 SQL을 실행하지 않는다.

- 이미 적용된 마이그레이션 파일을 수정하지 않는다.

- 마이그레이션 실패 또는 테스트 실패를 숨기지 않는다.

- 테스트를 통과시키기 위한 목적으로 데이터베이스 제약조건을 약화하지 않는다.

- 복구 방법을 실제로 검증하지 않았다면 해당 마이그레이션을 되돌릴 수 있다고 주장하지 않는다.

 

사용 예시

 

분석

$postgres-migration

user_account 테이블에 status 컬럼을 추가하려고 한다.

아직 파일을 수정하지 말고 다음만 보고해라.

1. 현재 Migration 방식
2. 영향을 받는 코드
3. 기존 데이터 위험
4. Migration 계획
5. 필요한 테스트

 

구현

$postgres-migration

승인된 계획에 따라 user_account.status 컬럼 추가를 구현해라.

조건:
- 기존 사용자는 ACTIVE로 보정한다.
- 적용된 Migration은 수정하지 않는다.
- 기존 Migration 명명 규칙을 따른다.
- PostgreSQL 통합 테스트를 실행한다.
- 최종 diff와 검증 결과를 보고한다.