🚨[Alembic] 명령어 및 오류 설정확인

 

💡 단순 따라하기 하다 테이블 몇번 날려먹고 깨달은점은 뭐든 한번에 실행시키지말자

 

🔗🔗 Alembic 명령어 정리 👈🏻👈🏻👈🏻👈🏻   빠르게 명령어 표로 보기!!

📌  revision -- autogenerate

alembic revision --autogenerate -m "Check metadata"

• --autogeneration 자동으로 스크립트 파일 생성해줌 
• revision 만 실행시 스크립트 셀프로 작성해야한다 
• versions 폴더 에 파일생성 my-project/migrations/versions/XXXX_Check_metadata.py
• 명령어에 입력한 텍스트가 파일이름으로 저장

✅ 출력 로그

• Generating /{Users-Path}/my--project/migrations/versions/XXXX_Check_metadata.py ... done

---

📌 upgrade 

생성된 스크립트(마이그레이션) 실행

alembic upgrade head

 

⚠️ 꼭!! 생성된 스크립트 확인합시다!! 특히(drop Table 확인)

---

📌 downgrade

마이그레이션 롤백

잘못된 마이그레이션을 되돌릴 수도 있습니다.

alembic downgrade -1  # 직전 마이그레이션 되돌리기
alembic downgrade <revision_id>  # 특정 버전으로 되돌리기

✔ 이전 상태로 돌아가고, downgrade() 함수가 실행됩니다.

---

📌 stamp head

강제적으로 현재 상태를 Alembic에 적용 (stamp head)

잘못된 마이그레이션을 되돌릴 수도 있습니다.

🚨 이 방법은 마이그레이션을 실행하지 않고 Alembic이 DB를 최신 상태로 인식하도록 설정하는 방법입니다.

즉, 현재 DB 상태를 그대로 사용하고 이후 마이그레이션을 정상적으로 생성할 수 있도록 합니다.

alembic stamp head

---

📌 downgrade base

💡 현재 DB 상태가 완전히 꼬였다고 판단될 경우 사용하는 방법

이 명령어는 데이터베이스의 모든 마이그레이션을 초기 상태로 되돌립니다.

alembic downgrade base

---

📌 upgrade

Alembic을 사용하여 특정 버전 실행

alembic upgrade <revision_id>

---

📌 alembic check 

💡 Alembic을 사용하여 현재 DB와 모델이 동기화되었는지 확인할 수도 있음

(Vercel Storage 사용 중이므로, 반드시 DATABASE_URL 환경변수가 올바른지 확인)

alembic check

✅ 출력 예시 (정상 상태)

No changes detected.

❌ 출력 예시 (DB와 모델 불일치)

Detected changes:
- Column 'products.lowest_price' is missing
- Table 'brands' has extra column 'category_id'

👉 이 경우, alembic revision --autogenerate -m "Fix sync issues" 실행 후 alembic upgrade head를 실행하여 동기화 필요

---

📌 alembic history 

현재 Alembic이 인식하는 모든 마이그레이션 기록을 확인할 수 있습니다.

alembic history

✅ 정상 상태 예시

Rev: 83064858a9b3 -> head (현재 최신 마이그레이션)
Rev: 1452d4350564 -> 83064858a9b3 (이전 마이그레이션)

❌ 문제 발생 가능성

Rev: b8f741cf4dff -> head (DB 상태와 불일치)

• DB와 Alembic의 마이그레이션 기록이 다르면, 현재 상태가 동기화되지 않은 것

---

📌 alembic current 

실행하여 DB 상태 확인

현재 DB가 Alembic이 추적하는 최신 마이그레이션 상태와 일치하는지 확인해야 합니다.

alembic current

✅ 출력 예시 (정상 상태)

Current revision for postgresql://...: 83064858a9b3 (Reinitialize migration)

❌ 문제 발생 예시 (DB와 Alembic 불일치)

b8f741cf4dff (DB가 Alembic 최신 상태와 다름)

• DB는 마이그레이션 기록을 따르지 않고, 수동으로 변경되었을 가능성이 있음
• Alembic은 변경 사항을 감지하지 못하고 있음

---

📌 alembic.ini 

🔹 프로젝트 루트 (my-project/)에 alembic.ini 유무 확인

터미널에서 확인

ls -la | grep alembic.ini

✅ 파일이 있으면 정상

❌ 없다면 아래 명령어로 생성:

alembic init migrations

---

📌 context.config가 None인지 확인

🔹 migrations/env.py 파일에서 아래 코드를 추가하여 context.config 값이 올바르게 설정되었는지 확인하세요.

from alembic import context

# Alembic 설정 파일 로드
config = context.config
if config is None:
    raise ValueError("❌ Alembic 환경 변수를 찾을 수 없습니다. `alembic` 명령어를 사용해 실행하세요.")

print(f"✅ Alembic 환경 설정 로드 완료: {config.config_file_name}")

✔ Alembic이 제대로 실행되었다면, .ini 파일 경로가 출력됩니다.

❌ config is None이면 alembic upgrade 방식으로 실행해야 합니다.

---

📌 Alembic 명령어 정리

명령어	설명
alembic revision --autogenerate -m "메시지"	모델과 DB의 차이를 자동 감지하여 마이그레이션 스크립트 생성
alembic upgrade head	최신 버전까지 모든 마이그레이션 적용
alembic check	현재 DB와 모델 간의 차이를 확인 (diff 검사)
alembic downgrade -1	직전 버전으로 한 단계 되돌리기
alembic downgrade <revision_id>	특정 리비전으로 되돌리기
alembic current	현재 적용된 마이그레이션 버전 확인
alembic history	전체 마이그레이션 히스토리 확인
alembic show <revision_id>	특정 revision의 변경사항(내용) 확인
alembic stamp head	실제로 적용하지 않고 현재 DB를 최신 상태로 간주하게 stamp 설정
alembic downgrade base	마이그레이션을 모두 되돌려 초기 상태로 되돌림 ⚠️ 주의: alembic downgrade base 명령은 모든 마이그레이션을 초기화하므로 사용 시 주의할 것!
alembic heads	현재 head가 여러 개인 경우 모든 head 리비전 표시
alembic merge <rev1> <rev2> -m "merge heads"	분기된 두 개 이상의 마이그레이션을 병합

 

---

[🚀 Dev/Python] - [FastAPI] FastAPI+ Alembic 설정 및 프로세스 정리

[FastAPI] FastAPI+ Alembic 설정 및 프로세스 정리