Prisma을 찾는 분이 가장 먼저 구분해야 할 기준부터 실제 순서까지 정리했습니다. Prisma 스키마 변경은 모델 파일만 수정하고 끝나는 작업이 아닙니다. 생성된 migration SQL, migration 이력, 개발·스테이징·운영 데이터베이스 분리, 배포 명령, 적용 상태, 복구 계획을 같은 흐름으로 확인해야 데이터 손실과 배포 실패를 줄일 수 있습니다.
읽는 시간 약 7분 · 가이드: 판단 기준 · 실행 순서 · 구매와 보관
Prisma 문제 정의: 먼저 기준을 세워야 하는 이유
Prisma 스키마 변경은 모델 파일만 수정하고 끝나는 작업이 아닙니다. 생성된 migration SQL, migration 이력, 개발·스테이징·운영 데이터베이스 분리, 배포 명령, 적용 상태, 복구 계획을 같은 흐름으로 확인해야 데이터 손실과 배포 실패를 줄일 수 있습니다.
개발용 migrate 명령을 운영에 그대로 쓰거나 생성된 SQL을 검토하지 않으면 의도하지 않은 삭제·잠금·장시간 변경을 놓칠 수 있습니다. 환경별 명령과 권한을 분리하고 migration 하나를 한 변경 단위로 검증해야 합니다.
| 첫 확인 | 이력 일치 |
|---|
현실 차이: 겉으로 비슷해도 결과가 달라지는 지점
스키마 선언과 실제 SQL의 차이
Prisma schema는 원하는 모델을 선언하지만 실제 데이터베이스 변경은 생성된 SQL과 현재 상태의 영향을 받습니다.
Prisma의 스키마 선언과 실제 SQL의 차이 단계에서는 migration SQL을 검토하고 테스트 데이터에서 실행하세요. 이때 다른 조건은 유지해야 스키마 선언과 실제 SQL의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 SQL readback입니다. 스키마 선언과 실제 SQL의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
스키마 선언과 실제 SQL의 차이 확인은 migration SQL을 검토하고 테스트 데이터에서 실행하세요. 이후 SQL readback 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 스키마 선언과 실제 SQL의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | SQL readback |
|---|
개발과 운영 명령의 차이
migrate dev는 개발용이며 운영·스테이징에는 pending migration을 적용하는 deploy 흐름을 사용합니다.
이 항목의 개발과 운영 명령의 차이 단계에서는 CI 환경에서 운영용 명령을 분리하세요. 이때 다른 조건은 유지해야 개발과 운영 명령의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 환경 분리입니다. 개발과 운영 명령의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
개발과 운영 명령의 차이 확인은 CI 환경에서 운영용 명령을 분리하세요. 이후 환경 분리 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 개발과 운영 명령의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | 환경 분리 |
|---|
적용 성공과 데이터 정상의 차이
명령이 성공해도 데이터 변환과 애플리케이션 쿼리가 기대대로 동작하는지 확인해야 합니다.
이 항목의 적용 성공과 데이터 정상의 차이 단계에서는 핵심 읽기·쓰기 경로를 배포 뒤 다시 실행하세요. 이때 다른 조건은 유지해야 적용 성공과 데이터 정상의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 앱 경로 검증입니다. 적용 성공과 데이터 정상의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
적용 성공과 데이터 정상의 차이 확인은 핵심 읽기·쓰기 경로를 배포 뒤 다시 실행하세요. 이후 앱 경로 검증 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 적용 성공과 데이터 정상의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | 앱 경로 검증 |
|---|
Prisma 판단 기준 3가지
migration 이력
저장소의 migration 파일과 데이터베이스의 적용 이력이 일치해야 합니다.
Prisma의 migration 이력 단계에서는 상태 명령과 migration 테이블을 확인하세요. 이때 다른 조건은 유지해야 migration 이력에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 이력 일치입니다. migration 이력의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
migration 이력 확인은 상태 명령과 migration 테이블을 확인하세요. 이후 이력 일치 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 migration 이력 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 이력 일치 |
|---|
SQL 위험도
필수 컬럼 추가, 데이터형 변경, 삭제, 인덱스 생성은 데이터와 잠금에 영향을 줄 수 있습니다.
이 항목의 SQL 위험도 단계에서는 생성 SQL과 예상 행 수를 검토하세요. 이때 다른 조건은 유지해야 SQL 위험도에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 위험 SQL 표시입니다. SQL 위험도의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
SQL 위험도 확인은 생성 SQL과 예상 행 수를 검토하세요. 이후 위험 SQL 표시 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 SQL 위험도 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 위험 SQL 표시 |
|---|
환경 권한
개발자 로컬 계정이 운영 연결 문자열과 변경 권한을 직접 쓰면 사고 범위가 커집니다.
이 항목의 환경 권한 단계에서는 CI 비밀 저장소와 최소 권한 계정을 사용하세요. 이때 다른 조건은 유지해야 환경 권한에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 권한 최소화입니다. 환경 권한의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
환경 권한 확인은 CI 비밀 저장소와 최소 권한 계정을 사용하세요. 이후 권한 최소화 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 환경 권한 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 권한 최소화 |
|---|
복구 가능성
적용 전에 백업·되돌림·호환 배포 순서를 정하지 않으면 실패 시 대응이 늦어집니다.
이 항목의 복구 가능성 단계에서는 복구 담당자와 검증 쿼리를 미리 기록하세요. 이때 다른 조건은 유지해야 복구 가능성에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 복구 계획입니다. 복구 가능성의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
복구 가능성 확인은 복구 담당자와 검증 쿼리를 미리 기록하세요. 이후 복구 계획 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 복구 가능성 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 복구 계획 |
|---|
| 확인 항목 | 권장 신호 | 피할 신호 |
|---|---|---|
| migration 이력 | 이력 일치 | 저장소의 migration 파일과 데이터베이스의 적용 이력이 일치해야 합니다. |
| SQL 위험도 | 위험 SQL 표시 | 필수 컬럼 추가, 데이터형 변경, 삭제, 인덱스 생성은 데이터와 잠금에 영향을 줄 수 있습니다. |
| 환경 권한 | 권한 최소화 | 개발자 로컬 계정이 운영 연결 문자열과 변경 권한을 직접 쓰면 사고 범위가 커집니다. |
| 복구 가능성 | 복구 계획 | 적용 전에 백업·되돌림·호환 배포 순서를 정하지 않으면 실패 시 대응이 늦어집니다. |
Prisma 실행법 3단계
1단계 · 변경 범위 고정
Prisma schema의 한 변경과 예상 데이터 영향을 기록합니다.
Prisma의 1단계 · 변경 범위 고정 단계에서는 관련 모델과 쿼리만 변경 목록에 넣으세요. 이때 다른 조건은 유지해야 1단계 · 변경 범위 고정에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 단일 변경입니다. 1단계 · 변경 범위 고정의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
1단계 · 변경 범위 고정 확인은 관련 모델과 쿼리만 변경 목록에 넣으세요. 이후 단일 변경 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 1단계 · 변경 범위 고정 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 단일 변경 |
|---|
2단계 · 개발 migration 생성
개발 데이터베이스에서 migration을 생성하고 SQL을 읽습니다.
이 항목의 2단계 · 개발 migration 생성 단계에서는 삭제·변환·기본값·인덱스 항목을 표시하세요. 이때 다른 조건은 유지해야 2단계 · 개발 migration 생성에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 SQL 검토입니다. 2단계 · 개발 migration 생성의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
2단계 · 개발 migration 생성 확인은 삭제·변환·기본값·인덱스 항목을 표시하세요. 이후 SQL 검토 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 2단계 · 개발 migration 생성 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | SQL 검토 |
|---|
3단계 · 스테이징 적용
운영과 유사한 데이터량에서 pending migration과 앱 읽기·쓰기를 검증합니다.
이 항목의 3단계 · 스테이징 적용 단계에서는 소요 시간과 오류 로그를 저장하세요. 이때 다른 조건은 유지해야 3단계 · 스테이징 적용에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 스테이징 증거입니다. 3단계 · 스테이징 적용의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
3단계 · 스테이징 적용 확인은 소요 시간과 오류 로그를 저장하세요. 이후 스테이징 증거 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 3단계 · 스테이징 적용 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 스테이징 증거 |
|---|
4단계 · 운영 배포 readback
CI에서 운영용 deploy 명령을 실행하고 상태와 핵심 쿼리를 확인합니다.
이 항목의 4단계 · 운영 배포 readback 단계에서는 문제가 있으면 정한 복구 절차를 실행하고 원본 로그를 보존하세요. 이때 다른 조건은 유지해야 4단계 · 운영 배포 readback에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 운영 재확인입니다. 4단계 · 운영 배포 readback의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
4단계 · 운영 배포 readback 확인은 문제가 있으면 정한 복구 절차를 실행하고 원본 로그를 보존하세요. 이후 운영 재확인 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 4단계 · 운영 배포 readback 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 운영 재확인 |
|---|
주의점: 잘못 적용하기 쉬운 부분
Prisma 적용 전 확인과 실행 중 확인을 분리해서 보세요. 아래 항목이 맞지 않으면 범위나 재시도 횟수를 늘리지 마세요.
- 개발용 명령을 운영에서 실행개발 흐름은 shadow database와 대화형 동작을 전제로 할 수 있어 운영 자동화와 맞지 않습니다.
- 생성 SQL 무검토모델 변경 의도와 실제 데이터 변경 위험이 다를 수 있습니다.
- migration 파일 수정 후 공유이미 적용된 이력을 바꾸면 환경 간 상태가 갈라질 수 있습니다.
- 로컬 운영 연결 문자열 사용실수로 다른 환경을 변경하거나 비밀 값이 노출될 위험이 있습니다.
- 배포와 앱 변경 동시 비호환이전 앱과 새 스키마가 잠시 함께 동작할 수 있도록 호환 순서를 설계해야 합니다.
상황별 적용: 같은 기준을 다르게 쓰는 법
필수 컬럼을 추가하는 경우
기존 행의 값 채우기와 기본값, 앱 배포 순서를 먼저 설계합니다.
Prisma의 필수 컬럼을 추가하는 경우 단계에서는 호환 가능한 단계로 나눠 적용하세요. 이때 다른 조건은 유지해야 필수 컬럼을 추가하는 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 단계적 변경입니다. 필수 컬럼을 추가하는 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
필수 컬럼을 추가하는 경우 확인은 호환 가능한 단계로 나눠 적용하세요. 이후 단계적 변경 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 필수 컬럼을 추가하는 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | 단계적 변경 |
|---|
migration 이력이 어긋난 경우
파일과 데이터베이스 상태를 비교하고 임의 삭제보다 공식 해결 절차를 따릅니다.
이 항목의 migration 이력이 어긋난 경우 단계에서는 원본 이력과 상태 출력을 보존하세요. 이때 다른 조건은 유지해야 migration 이력이 어긋난 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 이력 복구입니다. migration 이력이 어긋난 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
migration 이력이 어긋난 경우 확인은 원본 이력과 상태 출력을 보존하세요. 이후 이력 복구 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 migration 이력이 어긋난 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | 이력 복구 |
|---|
운영 적용 후 쿼리 오류
migration 성공 로그와 앱 오류를 함께 보고 스키마·클라이언트 생성물·배포 커밋을 대조합니다.
이 항목의 운영 적용 후 쿼리 오류 단계에서는 복구 뒤 같은 쿼리를 다시 실행하세요. 이때 다른 조건은 유지해야 운영 적용 후 쿼리 오류에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 쿼리 readback입니다. 운영 적용 후 쿼리 오류의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
운영 적용 후 쿼리 오류 확인은 복구 뒤 같은 쿼리를 다시 실행하세요. 이후 쿼리 readback 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 운영 적용 후 쿼리 오류 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | 쿼리 readback |
|---|
근거를 읽는 방법과 확인 순서
Prisma 공식 문서는 Prisma Migrate가 migration SQL 이력을 생성하며 개발과 운영 양쪽에서 역할을 한다고 설명합니다. migrate deploy는 스테이징·운영의 pending migration을 적용하며 drift 탐지나 reset을 수행하지 않습니다. 공식 배포 지침은 운영 변경을 CI/CD 자동 배포 흐름에서 실행하도록 권장합니다.
Prisma 근거는 수치 하나를 떼어 보기보다 측정 조건, 비교 대상, 적용 범위를 함께 읽어야 합니다. 짧은 소개 문구보다 공식 문서와 실제 실행 로그를 우선하면 판단 오류를 줄일 수 있습니다.
- Prisma Migrate 개요 – 선언형 schema와 사용자 수정 가능한 SQL 이력 확인
- Prisma migrate deploy – 스테이징·운영 적용 명령의 특성 확인
- Prisma migration 배포 지침 – 로컬 운영 적용 위험과 CI/CD 권장 확인
Prisma migrate dev를 운영에서 써도 되나요?
공식 문서는 migrate dev를 개발 환경용으로 설명하고 운영·스테이징에는 migrate deploy를 사용하도록 구분합니다.
migrate deploy가 drift도 찾아주나요?
공식 문서에 따르면 pending migration을 적용하지만 drift를 찾거나 reset·artifact 생성을 수행하지 않습니다.
생성된 migration SQL은 수정할 수 있나요?
Prisma Migrate는 생성된 SQL을 사용자 정의할 수 있지만 적용 전 검토·테스트와 이력 보존이 필요합니다.
db push와 migration은 같은가요?
프로토타입에서는 db push가 유용할 수 있지만 migration 이력을 통한 반복 가능한 운영 배포와 목적이 다릅니다.
운영 migration 실패 시 무엇을 먼저 보나요?
적용 로그, migration 상태, 데이터베이스 오류, 앱 쿼리를 같은 시각 기준으로 모으고 정한 복구 절차를 따르세요.
마무리: 오늘 바로 적용할 순서
Prisma 운영 변경은 schema 수정, SQL 검토, 스테이징 적용, CI deploy, 상태 확인, 앱 쿼리 readback과 복구 계획까지 완료해야 끝납니다. 오늘은 다음 migration 한 개의 SQL과 영향 행, 복구 담당자를 같은 문서에 고정하세요.
Prisma은 한 문장으로 단정하기보다 확인할 항목을 순서대로 나누는 것이 핵심입니다. 첫 기록을 남기고 다음번 결과와 비교하면 구매, 사용, 보관에서 같은 실수를 반복할 가능성이 낮아집니다.