Alembic 마이그레이션에서 비밀번호 특수문자 에러 해결하기

데이터베이스 마이그레이션 도구인 Alembic을 사용하다 보면, 예상치 못한 에러가 발생할 수 있습니다. 특히, 데이터베이스 접속 비밀번호에 특수문자가 포함된 경우 문제가 발생할 수 있습니다. 이번 글에서는 PostgreSQL 접속 비밀번호에 포함된 특수문자 때문에 발생한 문제와 이를 해결한 방법을 공유합니다.

문제

Alembic을 사용하여 데이터베이스 마이그레이션을 수행하는 과정에서, 접속 비밀번호에 ‘@’ 문자가 포함되어 있었습니다. 이를 URL 인코딩하여 ‘%40’으로 표현했지만, Alembic이 이를 제대로 처리하지 못했습니다.

증상

Alembic을 실행할 때, 다음과 같은 InterpolationSyntaxError가 발생했습니다:

InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%40'

이 오류는 Alembic이 configparser를 사용하여 설정 파일을 읽는 과정에서 발생했습니다. configparser는 ‘%’ 뒤에 오는 문자를 보간 변수로 해석하기 때문에, ‘%40’을 올바르게 인식하지 못했습니다.

원인

문제의 원인은 Alembic이 configparser를 사용하여 설정을 읽을 때, URL 인코딩된 비밀번호의 ‘%’ 문자를 보간(interpolation) 문법으로 오인한 것입니다. 이는 Alembic의 engine_from_config 함수가 내부적으로 configparser를 사용하기 때문에 발생했습니다.

해결

이 문제를 해결하기 위해, engine_from_config 대신 create_engine을 직접 사용하여 데이터베이스 연결을 설정했습니다. 이렇게 하면 configparser의 보간 문제를 피할 수 있습니다.

실제 코드

아래는 문제를 해결하기 위해 수정한 alembic/env.py의 코드입니다:

from sqlalchemy import create_engine, pool
from my_project import settings

DATABASE_URL = settings.database_url
connectable = create_engine(DATABASE_URL, poolclass=pool.NullPool)

이 코드는 settings.database_url에서 직접 create_engine을 호출하여 데이터베이스 연결을 설정합니다. 이로써 % 문자를 포함한 URL 인코딩된 비밀번호를 안전하게 사용할 수 있습니다.

결과

위와 같이 코드를 수정한 후, Alembic 마이그레이션은 더 이상 InterpolationSyntaxError를 발생시키지 않았습니다. 데이터베이스 접속 비밀번호에 특수문자가 포함되어 있어도 문제없이 마이그레이션을 수행할 수 있었습니다.

주의사항

데이터베이스 URL에 특수문자가 포함된 경우, 항상 URL 인코딩을 사용해야 합니다.
configparser를 사용할 때는 보간(interpolation) 문법에 주의해야 합니다.
create_engine을 직접 사용하는 방법은 Alembic 설정을 보다 유연하게 관리할 수 있는 방법입니다.

FAQ

Q1: Alembic 설정 파일에서 다른 특수문자도 문제가 될 수 있나요?

A1: 네, %를 포함한 다른 특수문자도 문제가 될 수 있습니다. 항상 URL 인코딩을 사용하여 안전하게 처리하세요.

Q2: `create_engine`을 사용하면 다른 설정은 어떻게 관리하나요?

A2: create_engine을 사용할 때는 추가적인 설정을 코드에서 직접 관리해야 합니다. 이는 설정을 보다 명확하게 이해하고 관리할 수 있는 장점이 있습니다.

Q3: Alembic 외에 다른 도구에서도 비슷한 문제가 발생할 수 있나요?

A3: 네, configparser를 사용하는 다른 도구에서도 비슷한 문제가 발생할 수 있습니다. 보간 문법을 이해하고 적절히 대응하는 것이 중요합니다.

[태그:] Alembic 비밀번호 특수문자 에러