playuniare.sori.studio/docs/migrations.md

데이터 마이그레이션 운영 원칙

현재 상태

현재 Play Uniare에는 데이터베이스와 영구 서버 데이터가 없다. 따라서 지금은 마이그레이션 명령을 실행할 필요가 없다.

마이그레이션이 필요한 시점

다음 기능 중 하나가 추가되면 마이그레이션 체계를 도입한다.

• 사용자 계정
• 저장된 덱
• 게임 기록
• 장기 유지되는 방 상태
• Redis 외의 영구 데이터베이스
• 기존 저장 데이터의 구조 변경

기본 원칙

1. 모든 마이그레이션 코드는 Git으로 관리한다.
2. 파일명에 실행 순서와 목적이 드러나야 한다.
3. 같은 마이그레이션을 두 번 실행해도 데이터가 망가지지 않아야 한다.
4. 운영 실행 전에 데이터베이스를 백업한다.
5. 로컬 또는 복제 데이터로 먼저 검증한다.
6. 성공 여부를 기록하는 마이그레이션 테이블을 사용한다.
7. NAS에서 즉석 SQL을 직접 입력하는 것은 긴급 복구 외에는 금지한다.
8. 긴급 명령을 사용했다면 같은 내용을 정식 마이그레이션 코드로 남긴다.

예정 디렉터리

데이터베이스 기술이 결정되면 다음과 같은 구조를 사용한다.

server/
└── migrations/
    ├── 0001_create_rooms.js
    └── 0002_add_room_expiration.js

실제 도구가 Prisma, Drizzle 또는 다른 마이그레이션 시스템으로 결정되면 해당 도구의 표준 디렉터리를 우선한다.

배포 순서

일반적인 운영 배포 순서:

1. 데이터베이스 백업
2. 새 코드 가져오기
3. 마이그레이션 실행
4. 애플리케이션 컨테이너 재빌드
5. 상태와 로그 확인
6. 주요 데이터 조회 검증

마이그레이션과 애플리케이션 코드의 선후 관계가 다르면 해당 릴리스의 docs/update.md에 정확한 순서를 기록한다.

파괴적 변경

열 삭제, 데이터 타입 축소, 대량 데이터 재작성은 한 번에 수행하지 않는다.

1. 새 필드 추가
2. 기존 데이터를 새 필드로 복사
3. 애플리케이션을 새 필드로 전환
4. 충분한 확인 기간 후 이전 필드 제거

복구 불가능한 변경은 사용자 승인과 백업 확인 없이 실행하지 않는다.