MySQL 8.4 'default-authentication-plugin' 에러 원인과 해결 방법
Problem
Docker Compose를 사용하여 MySQL 컨테이너를 실행하거나 기존 5.7/8.0 버전에서 8.4 버전으로 업그레이드할 때 예상치 못한 에러를 마주할 수 있습니다. 컨테이너가 정상적으로 시작되지 않고 로그에 unknown variable 'default-authentication-plugin=mysql_native_password'라는 에러 메시지가 출력되는 현상입니다. 이로 인해 데이터베이스 초기화가 중단되고, 연결된 애플리케이션(예: Laravel, Spring Boot, Node.js 등)이 DB에 접속하지 못하는 장애가 발생하게 됩니다.
Background
과거 MySQL 5.7까지는 기본 인증 플러그인으로 mysql_native_password를 사용했습니다. 하지만 보안 강화를 위해 MySQL 8.0부터는 caching_sha2_password가 기본값으로 변경되었습니다. 기존 레거시 애플리케이션과의 호환성을 유지하기 위해 많은 개발자들이 default-authentication-plugin=mysql_native_password 옵션을 명시적으로 설정하여 사용해 왔습니다. 그러나 MySQL 8.4 LTS 버전부터는 이 default-authentication-plugin 파라미터 자체가 완전히 제거되었습니다. 따라서 이전 버전에서 잘 작동하던 설정 파일(my.cnf)이나 실행 커맨드를 그대로 MySQL 8.4에 적용하면, 존재하지 않는 변수를 참조했다는 에러가 발생하게 됩니다.
Solution
이 문제를 해결하려면 MySQL 8.4의 새로운 파라미터 규칙에 맞게 설정을 변경해야 합니다. default-authentication-plugin 파라미터 대신 --mysql-native-password=ON 옵션을 사용하여 플러그인을 명시적으로 활성화해야 합니다.
1. docker-compose.yml 수정
command 항목에서 기존 파라미터를 새로운 파라미터로 교체합니다.
# 수정 전 (MySQL 8.0 이하 호환)
db:
image: mysql:8.4
command: ["mysqld", "--default-authentication-plugin=mysql_native_password"]
# 수정 후 (MySQL 8.4 이상)
db:
image: mysql:8.4
# mysql_native_password 플러그인을 활성화하는 새로운 옵션 사용
command: ["mysqld", "--mysql-native-password=ON"]
restart: unless-stopped
ports:
- "3306:3306"
# ... 나머지 환경 변수 및 볼륨 설정 유지
2. my.cnf (설정 파일) 수정
볼륨으로 연결된 커스텀 my.cnf 파일을 사용 중이라면, 해당 파일 내부의 설정도 변경해야 합니다.
[mysqld]
# mysql_native_password 플러그인 명시적 활성화
mysql_native_password=ON
# 아래 줄은 MySQL 8.4에서 에러를 유발하므로 삭제하거나 주석 처리합니다.
# default-authentication-plugin=mysql_native_password
general_log = 0
general_log_file = /var/lib/mysql/general.log
default_time_zone='+00:00'
설정을 모두 변경한 후, 터미널에서 docker compose down으로 기존 컨테이너를 완전히 내린 뒤, docker compose up -d를 통해 컨테이너를 재시작하면 정상적으로 MySQL 8.4가 실행됩니다.
Deep Dive
MySQL 8.4에서 --mysql-native-password=ON을 사용하여 임시로 문제를 해결할 수 있지만, 장기적인 관점에서는 주의가 필요합니다. Oracle은 mysql_native_password 플러그인을 Deprecated(사용 중단) 처리했으며 향후 릴리즈에서 완전히 제거할 예정입니다. 따라서 프로덕션 환경에서는 애플리케이션의 데이터베이스 드라이버(예: PHP PDO, Node.js mysql2, Java Connector/J 등)를 최신 버전으로 업데이트하는 것이 좋습니다. 드라이버를 업데이트하면 MySQL의 기본 인증 방식인 caching_sha2_password를 기본적으로 지원하므로, 레거시 인증 플러그인에 의존할 필요가 없어집니다.
Conclusion
MySQL 8.4로 업그레이드 시 발생하는 default-authentication-plugin 에러는 해당 파라미터가 시스템에서 제거되었기 때문에 발생합니다. docker-compose.yml과 my.cnf에서 해당 옵션을 삭제하고 --mysql-native-password=ON으로 변경하여 즉시 문제를 해결할 수 있습니다. 하지만 향후 호환성과 보안을 위해 애플리케이션 단에서 caching_sha2_password를 지원하도록 업데이트하는 것을 최종 목표로 삼아야 합니다.