database-migration

database-migration 스킬 개요

database-migration 스킬로 할 수 있는 일

database-migration 스킬은 일반적인 ORM 및 SQL 워크플로 전반에서 데이터베이스 스키마 변경과 데이터 마이그레이션 작업을 계획하고 생성할 때 쓰는 스킬입니다. 특히 롤백 안전성과 무중단 배포를 중요하게 다룹니다. 단순히 “마이그레이션 작성해줘” 수준의 범용 프롬프트로는 부족한 상황에서 가장 유용합니다. 예를 들어, 변경이 실제 프로덕션 데이터에 영향을 주거나, 단계적 배포가 필요하거나, Sequelize나 TypeORM 같은 특정 마이그레이션 프레임워크 안에서 작업해야 할 때 이 스킬의 가치가 분명해집니다.

어떤 사용자가 이 database-migration 스킬에 잘 맞는가

이 database-migration 스킬에 가장 잘 맞는 사용자는 Database Engineering 팀, 백엔드 엔지니어, 플랫폼 엔지니어, 그리고 AI 보조 개발자입니다. 핵심은 문법만 맞는 결과물이 아니라, 실제 운영을 고려한 마이그레이션 결과물이 필요하다는 점입니다. 테이블 구조를 바꾸거나, 데이터 백필을 수행하거나, 컬럼명을 안전하게 변경하거나, ORM 패턴을 옮기는 작업이라면, 이 스킬은 빈 프롬프트보다 훨씬 더 실전적인 기본 프레임을 제공합니다.

어떤 일을 가장 잘 해결하는가

실제 해야 할 일이 “실행 가능한 마이그레이션 계획”을 만드는 것이라면 database-migration 스킬을 쓰는 편이 좋습니다. 여기에는 마이그레이션 파일, 단계별 롤아웃 절차, 롤백 경로, 데이터 변환 고려사항이 포함됩니다. 이 스킬의 핵심 가치는 단순한 코드 생성이 아닙니다. 작업 순서, 호환성 유지 기간, 실패 복구 방식처럼 마이그레이션에서 가장 헷갈리기 쉬운 부분의 추측을 줄여준다는 데 있습니다.

일반적인 코딩 프롬프트와 비교했을 때의 차별점

일반 프롬프트와 비교하면, 이 database-migration 스킬은 다음과 같은 관점을 분명하게 갖고 있습니다.

• ORM을 인지한 마이그레이션 예시
• 명시적인 up / down 패턴
• 무중단 배포를 전제로 한 사고방식
• 스키마 변경과 데이터 변경을 함께 다루는 워크플로
• 롤백 절차를 부가 요소가 아니라 핵심 요구사항으로 취급

그래서 단순한 “SQL 생성해줘” 요청보다, 프로덕션 변경 작업에 훨씬 더 잘 맞습니다.

어디까지가 범위이고, 어디부터는 아닌가

현재 이 스킬 콘텐츠는 마이그레이션 패턴과 예시 구조에 강점이 있으며, 특히 Sequelize와 TypeORM 쪽이 두드러집니다. 반면 리포지토리별 자동화, 검증 스크립트, 세부 의사결정 규칙은 상대적으로 약한 편인데, 스킬 폴더에 노출된 내용이 SKILL.md 하나뿐이기 때문입니다. 즉, 마이그레이션 작업을 안내하고 초안을 만드는 데는 충분히 유용하지만, 신뢰할 수 있는 결과를 얻으려면 여러분의 스택 세부사항, 운영 제약, 배포 모델을 함께 제공해야 합니다.

database-migration 스킬 사용 방법

database-migration 스킬 설치 맥락

이 리포지토리의 Skills 시스템을 사용한다면, 먼저 리포지토리에서 해당 스킬을 설치한 뒤, 코드베이스와 스키마 맥락에 이미 접근 가능한 에이전트 세션에서 호출하면 됩니다. 일반적인 설치 예시는 다음과 같습니다.

npx skills add https://github.com/wshobson/agents --skill database-migration

이 스킬은 사실상 하나의 SKILL.md 중심으로 제공되므로, 실제 가치는 요청을 어떻게 구성하느냐와 스키마 맥락을 얼마나 구체적으로 제공하느냐에 크게 좌우됩니다.

사용 전에 먼저 읽어야 할 파일

다음 파일부터 확인하세요.

• plugins/framework-migration/skills/database-migration/SKILL.md

이 스킬에는 눈에 보이는 rules/, resources/, 스크립트가 따로 없기 때문에, 리포지토리를 길게 읽어야 하는 단계는 필요하지 않습니다. 실무적으로는 SKILL.md를 먼저 확인하고, 바로 여러분의 스키마 파일, ORM 설정, 기존 마이그레이션 이력으로 넘어가는 흐름이 가장 효율적입니다.

스킬이 잘 작동하려면 어떤 입력이 필요한가

database-migration 스킬은 다음 정보를 함께 줄 때 훨씬 더 잘 작동합니다.

• 현재 사용하는 ORM 또는 마이그레이션 도구: Sequelize, TypeORM, Prisma, raw SQL 등
• 현재 스키마 또는 모델 정의
• 목표 스키마 변경 사항
• 데이터 백필 필요 여부
• 테이블 크기 또는 트래픽 민감도
• 허용 가능한 다운타임 수준
• 롤백 기대치
• 대상 데이터베이스 엔진: PostgreSQL, MySQL 등
• 배포 방식: one-shot, phased, blue/green, canary

이 정보가 없으면, 겉보기엔 그럴듯하지만 실제 프로덕션에서는 위험한 마이그레이션을 반환할 수 있습니다.

대략적인 목표를 강한 database-migration 프롬프트로 바꾸는 법

약한 프롬프트:

Create a migration to rename a column.

더 강한 프롬프트:

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

두 번째 버전은 이 스킬이 더 안전한 expand-migrate-contract 접근을 선택하는 데 필요한 정보를 제공합니다. 반대로 첫 번째처럼 짧게 쓰면, 위험한 직접 rename 방식으로 흘러갈 가능성이 큽니다.

실제 마이그레이션 작업에서 가장 좋은 워크플로

실무적인 database-migration usage 흐름은 다음과 같습니다.

1. 먼저 마이그레이션 전략부터 요청합니다.
2. 그다음 위험 요소, 락 동작, 롤백 가정을 검토합니다.
3. 이후 현재 프레임워크에 맞는 실제 마이그레이션 파일 생성을 요청합니다.
4. 단계적 롤아웃이라면 애플리케이션 계층의 호환성 변경도 요청합니다.
5. 검증 쿼리와 롤백 절차를 추가로 요청합니다.
6. 결과물을 신뢰하기 전에, 프로덕션과 유사한 데이터 형태의 staging에서 실행해 봅니다.

이 순서는 중요합니다. 너무 이른 단계에서 생성된 마이그레이션 코드는 잘못된 롤아웃 모델을 그대로 굳혀버리는 경우가 많습니다.

이 스킬이 특히 강한 ORM 패턴

리포지토리에서 확인되는 명시적 예시는 다음과 같습니다.

• Sequelize migrations
• TypeORM migrations

설명 자체는 더 넓은 ORM/플랫폼 마이그레이션까지 포함하지만, 눈에 보이는 예시는 이 두 생태계에 가장 강합니다. 다른 스택을 쓴다면, 모델이 해당 의도를 여러분의 툴체인으로 번역하도록 요청하는 편이 좋습니다. 기본적으로 깊게 지원할 것이라고 가정하지는 마세요.

무중단 가이드를 언제 명시적으로 요청해야 하는가

모델이 항상 온라인 마이그레이션 안전성을 최우선으로 최적화해 줄 것이라고 기대하면 안 됩니다. 다음 중 하나라도 해당하면 무중단 요구사항을 직접 명시하세요.

• 큰 테이블
• 높은 쓰기 트래픽
• 앱 배포와 DB 배포가 독립적일 때
• 컬럼 이름 변경 또는 타입 변경
• 핫패스에서의 백필
• 프로덕션 트래픽 중 제약조건 변경

Database Engineering 팀이 database-migration 스킬을 사용할 때, 이 한 줄이 장난감 수준 답변과 실제 배포 가능한 답변을 가르는 경우가 많습니다.

스킬에 어떤 출력물을 요청해야 하는가

신뢰도 높은 활용을 원한다면, database-migration 스킬에 파일 하나만 달라고 하지 말고 묶음 형태의 결과를 요청하세요.

• 마이그레이션 코드
• 롤아웃 순서
• 롤백 순서
• 데이터 백필 로직
• 가정과 위험 요소
• 검증 체크리스트
• 마이그레이션 후 정리 단계

이렇게 해야 운영상 필요한 숨은 작업이 빠지는 것을 막을 수 있습니다.

직접적인 파괴적 변경에 대한 실전 경고

이 스킬은 다음과 같은 위험한 단일 단계 변경을 피하는 용도로 가장 잘 활용됩니다.

• 기존 컬럼을 즉시 삭제하는 것
• 호환성 계층 없이 핫 컬럼을 제자리에서 rename하는 것
• 변환 전략 없이 타입을 변경하는 것
• 백필 전에 non-null 제약을 추가하는 것
• 락 영향을 계획하지 않고 대형 테이블을 다시 쓰는 것

첫 번째 결과물이 이런 방향이라면, 프로덕션 경로에 쓰기 전에 단계적 대안을 요청하세요.

database-migration 스킬 FAQ

이 database-migration 스킬은 ORM 마이그레이션 전용인가

아닙니다. 이 스킬은 ORM과 플랫폼 전반의 데이터베이스 스키마 및 데이터 마이그레이션을 다루도록 설계되어 있습니다. 다만 실제로 보이는 예시는 ORM 중심이며, 특히 Sequelize와 TypeORM 쪽 비중이 큽니다. 따라서 최상의 결과를 얻으려면 현재 스택을 정확히 밝히고, 필요하다면 SQL 또는 해당 프레임워크 형태로 변환해 달라고 요청하는 것이 좋습니다.

database-migration 스킬은 초보자에게도 괜찮은가

네, 다만 한계는 있습니다. 예시가 구체적이라 접근성은 좋지만, 해당 마이그레이션이 운영상 안전한지 판단할 수 있다는 전제를 어느 정도 깔고 있습니다. 초보자도 이 스킬로 마이그레이션 파일과 롤아웃 계획 초안을 만들 수는 있지만, 첫 답변을 검토 없이 바로 프로덕션 준비 완료로 받아들여서는 안 됩니다.

언제 database-migration을 쓰지 말아야 하는가

작업이 순수하게 개념적 논의에 머물고, 실제 스키마/데이터 변경 실행과 무관하다면 이 스킬은 굳이 적합하지 않습니다. 또한 리포지토리만 보고 환경별 검증까지 완전히 제공되길 기대한다면 잘 맞지 않습니다. 노출된 폴더에 추가 스크립트, 규칙, 테스트 하네스가 포함되어 있지 않기 때문입니다.

AI에게 SQL만 작성해 달라고 하는 것보다 왜 더 나은가

database-migration guide의 가치는 문법이 아니라 마이그레이션 라이프사이클 중심으로 작업을 프레이밍한다는 데 있습니다. 단순 SQL 프롬프트는 롤백, 호환성 유지 기간, 단계적 백필, ORM 마이그레이션 관례를 자주 놓칩니다. 코드 정확성만큼 배포 안전성이 중요한 상황이라면 이 스킬이 더 낫습니다.

무중단 배포도 지원하는가

네, 분명한 주요 사용 사례 중 하나입니다. 다만 여러분 환경에서 무중단이 정확히 무엇을 의미하는지는 직접 밝혀야 합니다. 이 표현만으로는 범위가 너무 넓습니다. 모델이 적절히 판단하려면 배포 순서, 읽기/쓰기 트래픽 형태, 호환성 제약을 알아야 합니다.

database-migration 스킬을 더 잘 활용하는 방법

스키마 diff와 운영 제약을 함께 제공하라

database-migration 출력 품질을 가장 빠르게 높이는 방법은 스키마 변경 내용과 런타임 제약을 같이 주는 것입니다. 예를 들면 다음과 같습니다.

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

이렇게 주면 단순한 alter 문 하나로 끝내는 대신, 단계적 마이그레이션 설계 쪽으로 유도할 수 있습니다.

안전성이 중요하면 expand-migrate-contract를 직접 요청하라

첫 초안이 너무 파괴적으로 보인다면, expand-migrate-contract 계획을 명시적으로 요청하세요. 특히 다음 같은 작업에서 결과가 눈에 띄게 좋아지는 경우가 많습니다.

• rename
• 타입 변환
• non-null 도입
• 테이블 분리
• 비정규화 또는 정규화 변경

이 방법은 database-migration usage 품질을 안정적으로 끌어올리는 가장 확실한 방법 중 하나입니다.

첫 응답부터 검증과 롤백을 요구하라

흔한 실패 패턴 중 하나는 up 마이그레이션은 맞는데 down이 약하거나 비현실적인 경우입니다. 이를 줄이려면 처음부터 다음 항목을 요구하세요.

• 롤백 조건
• 데이터 손실 경고
• 검증 쿼리
• 각 단계 이후의 성공 기준

이렇게 하면 모델이 초반부터 되돌릴 수 있는지까지 함께 생각하게 됩니다.

리포지토리의 기존 마이그레이션 스타일을 제공하라

프로젝트에 이미 마이그레이션 관례가 있다면, 대표적인 파일 한두 개를 붙여 넣고 그 스타일에 맞춰 달라고 요청하세요. 이렇게 하면 네이밍, 트랜잭션 처리, 타임스탬프 스타일, 프레임워크 관용구가 실제 팀 규약에 더 잘 맞게 나옵니다. 특히 Sequelize와 TypeORM에서는 프레임워크 기본값 외에 팀별 로컬 패턴이 있는 경우가 많아 더 유용합니다.

코드 정합성만 보지 말고 락 위험까지 반복 점검하라

첫 결과물 이후에는 다음과 같은 후속 질문을 해보세요.

• 어떤 단계가 테이블 락을 유발할 수 있는가?
• 어떤 단계는 쓰기를 계속 받는 상태로 실행 가능한가?
• 어떤 부분을 별도 배포로 쪼개야 하는가?
• 백필 이후에는 어떤 부분이 되돌릴 수 없는가?
• 롤아웃 중 어떤 모니터링을 봐야 하는가?

바로 이런 대화가 있어야 database-migration 스킬이 단순한 보일러플레이트 생성기가 아니라, 실제 Database Engineering 작업에 의미 있는 도구가 됩니다.

이런 흔한 실패 패턴을 주의하라

생성된 마이그레이션이 다음과 같다면 주의가 필요합니다.

• 테이블이 매우 작다고 가정함
• 롤백이 빠져 있음
• 기존 필드를 너무 일찍 삭제함
• 스키마 변경과 대규모 백필을 하나의 위험한 단계로 합침
• 전환 기간 동안 앱 호환성을 무시함
• 사용 중인 버전과 맞지 않는 프레임워크 문법을 사용함

이런 경우는 스킬이 쓸모없다는 뜻이 아니라, 프롬프트를 더 정교하게 다듬어야 한다는 신호로 보는 것이 맞습니다.

첫 초안 이후 결과를 개선하는 가장 좋은 방법

첫 답변은 최종 산출물이 아니라 마이그레이션 제안서로 취급하세요. 그런 다음 다음 정보를 바탕으로 수정을 요청하면 됩니다.

• 실제 테이블 크기
• 인덱스 현황
• 예상 배포 순서
• canary 또는 staging에서 확인된 결과
• 리뷰 과정에서 드러난 잘못된 가정

이 피드백 루프가 database-migration install 및 사용 워크플로에서 프로덕션급 가치를 끌어내는 가장 현실적인 방법입니다.