장고 MySQL 연동 NameError: name '_mysql' is not defined 해결하기

플러터 app_plugin_loader Gradle plugin 문제로 어찌저찌하다 openjdk17 새로 설치했었다.

이 과정에서 python3.13을 설치하게 되었는데 기존의 파이썬과 충돌했었는지, 장고 테스트 서버 실행 시 NameError: name '_mysql' is not defined 오류 발생했다.

여러가지 방법들을 시도한 결과, python과 mysql이 연결되지 않아 발생한 오류라는 걸 알게 되었다.

하지만 환경에 따라 해결 방법이 다 달라 어쩔 수 없이 문제가 해결될 때까지 여러 방법들을 일일이 시도해봐야 한다.

Homebrew로 MySQL 설치 확인

Mac에서는 Homebrew로 패키지를 관리하는 것이 일반적이기 때문에, 먼저 MySQL이 제대로 설치되어 있는지 확인했다.

brew list

만약 mysql이 없다면 다시 설치한다.

brew install mysql

만약 이미 설치된 경우 Homebrew는 이를 알려주며, 필요한 경우 brew upgrade mysql 명령어로 최신 버전으로 업그레이드할 수 있다. 오래된 버전이 문제를 일으킬 수 있기 때문에 최신 상태로 관리해야 한다.

MySQL이 제대로 설치되어 있어야 mysqlclient가 정상적으로 작동할 수 있다.

참고로 mysqlclient는 C 기반의 패키지다.

Mac에서는 C/C++로 빌드가 필요할 때 Xcode Command Line Tools가 필수다. Python 패키지를 컴파일하는 데 필요한 컴파일러와 유틸리티를 제공하기 때문이다. 이 도구가 있어야 mysqlclient와 같은 C 기반 패키지의 빌드 오류를 방지할 수 있다.

그래서 다음 명령어로 설치를 확인했다.

xcode-select --install

이 명령어는 Xcode Command Line Tools가 설치되어 있는지 확인하고, 없는 경우 설치를 진행한다.

mysqlclient 재설치

때로는 mysqlclient 패키지가 제대로 설치되지 않아 빌드가 실패하는 경우가 있다. 이를 해결하려면 기존 설치를 제거하고 다시 설치하면 된다.

pip uninstall mysqlclient
pip install mysqlclient

pip uninstall mysqlclient는 기존 mysqlclient 설치를 제거하고, pip install mysqlclient는 새로 설치한다.

가상환경을 사용 중이라면 해당 환경에서 명령어를 실행하여 의존성 충돌을 피해야 한다. 설치 과정에서 필요한 파일이 빌드되므로 종종 빌드 과정에서 문제를 해결할 수 있다.

환경변수 설정

MacOS에서는 MySQL의 동적 라이브러리 경로가 정확하게 설정되어 있어야 _mysql 모듈이 올바르게 로드될 수 있다.

환경 변수를 설정하여 이 경로를 명시적으로 지정할 수 있다.

export PATH="/usr/local/mysql/bin:$PATH"
export DYLD_LIBRARY_PATH="/usr/local/mysql/lib:$DYLD_LIBRARY_PATH"

export PATH="/usr/local/mysql/bin:$PATH"는 터미널에서 MySQL 실행 파일들이 위치한 디렉터리를 PATH 환경 변수에 추가한다.

export DYLD_LIBRARY_PATH="/usr/local/mysql/lib:$DYLD_LIBRARY_PATH"는 Mac에서 동적 라이브러리 경로를 설정하여 _mysql 모듈이 MySQL 클라이언트를 올바르게 참조하도록 한다. 경로는 MySQL이 설치된 위치에 따라 다를 수 있으니 주의해야 한다.

mysqlclient 빌드 문제 해결

일부 경우 mysqlclient가 제대로 빌드되지 않아 _mysql 모듈이 로드되지 않는 문제가 발생할 수 있다. wheel 패키지를 업그레이드하고, 강제로 재설치를 시도하여 해결할 수 있다.

pip install --upgrade wheel
pip install --force-reinstall --no-cache-dir mysqlclient

pip install --upgrade wheel은 wheel 패키지를 최신 버전으로 업그레이드하여 Python 패키지를 빌드할 때 최신 표준을 사용할 수 있게 한다.

pip install --force-reinstall --no-cache-dir mysqlclient는 mysqlclient를 강제로 재설치하면서, 캐시된 파일을 사용하지 않고 새로 다운로드 및 빌드하도록 강제한다. 이는 기존의 손상된 설치를 새로 설치하는 데 유용하다.

pymysql 사용 (대안)

만약 mysqlclient를 사용하는 데 지속적인 문제가 있다면, Python용 MySQL 드라이버 중 하나인 pymysql을 대안으로 사용할 수 있다. pymysql은 설치가 비교적 간단하며, 종종 Mac 환경에서 호환성 문제를 피할 수 있다.

# pymysql 설치
pip install pymysql

pymysql은 Python용 MySQL 클라이언트 드라이버로, 기존의 mysqlclient를 대체할 수 있다. 설치 과정은 간단하며, mysqlclient보다 덜 복잡한 경우도 많다.

프로젝트의 **init**.py 파일에 다음 코드를 추가하여 Django가 pymysql을 MySQLdb 대체로 사용하도록 설정한다.

import pymysql
pymysql.install_as_MySQLdb()

이 코드는 pymysql을 MySQLdb의 대체로 사용하는 설정이다. Django는 기본적으로 MySQLdb API를 사용하므로, pymysql을 명시적으로 MySQLdb로 등록해 주어야 한다. 이를 통해 Django와 MySQL이 원활히 통신할 수 있다.

정리하자면, NameError가 발생 시 환경 변수 설정을 확인하거나 라이브러리를 재설치하면 문제가 해결된다. 그리고 pymysql은 대안이 될 수 있다.