How-to-use-alembic.md

오늘은 python의 데이터베이스 마이그레이션 툴 alembic 사용법을 정리해보려합니다.

최근 개발하고 있는 졸업작품에서 FastAPI를 이용한 서버개발을 맡게 되었는데 Django를 쓸 때 기본적으로 manage.py에서 제공하는 migration 기능이 유용해서 다른 라이브러리가 없을까 찾던 중 alembic이라는 툴을 찾게되어 사용하게 되었습니다.

마이그레이션(migration)?

alembic에 대해 알아보기 전 마이그레이션이란 무엇인지 알아봅시다. 직역하면

migration : 이주, 이전

정보기술 분야에서는 운영환경을 옮기는 것을 말합니다.

최근 클라우드 서비스를 많이 사용되면서 기존 온프레미스 방식의 IDC환경에서 클라우드 환경으로 마이그레이션하는 것을 자주 볼 수 있습니다. 이에 따라 마이그레이션을 쉽게 할 수 있는 툴들이 많이 등장하고 있습니다.

ex. AWS Storage Gateway, AWS DataSync, AWS Snowcone 등

근데 이런 것들은 인프라 자체를 이전할때 쓰는 것 같은데, alembic은 그럼 뭘까요?

alembic은 ORM으로 스키마를 사용하여 데이터베이스를 관리할때 사용하는 도구입니다.

alembic 스크립트에는 upgrade()와 downgrade() 함수들을 사용하여 변경 사항을 제어하고 변경 히스토리를 저장하여 데이터베이스를 재구성할 수 있습니다.

설치

alembic은 pip 로 설치할 수 있다.

pip install alembic

사용법

초기화

alembic init 폴더명

위의 명령어를 실행하면 지정한 폴더명으로 아래와 같은 마이그레이션 관리 폴더가 생성됩니다.

alembicinit

데이터베이스 연동

위의 명령어를 실행하고 만들어진 env.py의 run_migrations_offline() 함수의 url 변수에 연결할 데이터베이스 URI를 입력합니다.

해당 URI는 alembic.ini 파일에 작성되어있는데 해당 파일에서

sqlalchemy.url = drivier://user:[e-mail]

위의 변수의 값을 연결할 데이터베이스 URI로 바꾸어 사용하면 됩니다.

• 기본으로 제공하는 alembic.ini가 아니어도 dotenv 같은 모듈을 사용하여 env.py에 따로 입력하여 사용해도 됩니다😃

마이그레이션

이제 실제 마이그레이션 작업을 해봅시다.

alembic에서는 revision명령어를 사용하여 migration script를 작성하고 마이그레이션을 진행할 수 있습니다.

$ alembic revision -m "[Migration Script]"
Generating /path/to/my_folder/practice/versions/f09152543072_example.py ...  done

revision을 생성하면 versions폴더 밑에 {revisioncode}_{migrationscript}.py로 파일이 생성됩니다.

해당 파일에는 upgrade(), downgrade()

두 함수가 있는데, 해당 revision을 실제 데이터베이스에 적용할 때 수행될 작업이 upgrade()에 명시됩니다. downgrade()에는 변경사항이 있을 때 있기전 상태가 명시됩니다.

• 첫번째 revision에는 만들어진대로 비워두거나 table drop을 적어주면 됩니다.

이제 정말 실제 데이터베이스에 revision을 적용시켜 봅시다.

$ alembic upgrade head

명령어를 사용하면 가장 최근의 revision을 데이터베이스에 적용합니다.

이외 기능들

alembic은 아래 명령어를 사용하여 migration history를 확인할 수 있습니다.

$ alembic history

• downgrade 하는 방법 downgrade를 수행할 때는 특정 revision번호를 지정하거나 -1, -2 같이 현재상태에서 상대적인 위치의 downgrade를 할 수 있습니다.

$ alembic downgrade <down_revision 번호>

$ alembic downgrade -1 #가장 최신 버전의 전 단계로 downgrade 수행

마무리

프로젝트를 하면서 유용하게 사용했던 alembic에 대해서 정리했습니다. python프로젝트가 아니더라도 nodejs, go 등 다양한 언어로 서버를 개발하고, alembic으로 마이그레이션을 수행할 수 있으니 유용하게 사용할 수 있었으면 좋겠습니다. 더 자세한 내용은 참고한 블로그 링크를 공유해둘테니 참고하시면 될 것 같습니다:D

참고 링크

• sqlalchemy와 함께 alembic 사용하기

• alembic을 이용해 DB 마이그레이션 하기

• Alembic documentation