MySQL Docker 연결 오류는 최근 Docker Desktop 4.x와 MySQL 8.x 환경에서 특히 자주 검색돼요. 가장 먼저 docker ps로 실제 공개 포트를 확인하고, docker logs와 docker inspect로 포트 미노출·권한 문제·인증 플러그인 호환 문제·볼륨 초기화 문제 중 어디에 해당하는지 분류하면 해결이 빨라져요.

MySQL Docker 연결 오류는 무엇인지

Docker와 MySQL이 연결되는 모습을 한눈에 보여주는 이미지AI로 생성된 이미지입니다
Docker와 MySQL이 연결되는 모습을 한눈에 보여주는 이미지

MySQL Docker 연결 오류는 컨테이너가 떠 있어도 호스트나 다른 컨테이너에서 MySQL 8.0 또는 8.4 LTS에 접속하지 못하는 상태를 말해요. 최근 Docker Desktop 4.x와 MySQL 8.x 조합에서 Can't connect to MySQL server on 127.0.0.1, Access denied, MySQL server has gone away 같은 메시지가 자주 검색되는데, 원인은 대개 포트 매핑, 계정 권한, 인증 플러그인, 초기화된 볼륨 중 하나예요.

여기서 중요한 점은 ready for connections 로그가 보여도 네트워크 접속이 보장되는 것은 아니라는 사실이에요. 이 문구는 MySQL 프로세스가 부팅됐다는 뜻일 뿐이고, 3306 포트 공개 여부나 브리지 네트워크, 호스트 방화벽, WSL2 포트 바인딩 상태는 별도로 확인해야 해요.

MySQL Docker 연결 오류를 확인하는 방법

포트 매핑이나 호스트명 문제처럼 연결 경로가 끊기는 상황AI로 생성된 이미지입니다
포트 매핑이나 호스트명 문제처럼 연결 경로가 끊기는 상황

가장 실용적인 점검 방법은 포트 확인부터 로그·네트워크·계정 순서로 좁혀가는 것이에요. 아래 5단계는 MySQL 공식 이미지 사용 시점의 기본 흐름이고, Docker Compose와 단일 docker run 환경 모두에 적용할 수 있어요.

  1. docker ps를 실행해서 PORTS 항목을 확인해요. 0.0.0.0:3307->3306/tcp처럼 보이면 호스트에서는 127.0.0.1:3307로 접속해야 해요. 3306으로 접속하면 실패해요.

  2. docker logs <컨테이너명>으로 MySQL 부팅 로그를 확인해요. ready for connections가 보이면 DB 프로세스는 올라온 것이고, 그다음은 네트워크나 계정 쪽을 봐야 해요.

  3. docker inspect <컨테이너명>에서 NetworkSettings를 확인해요. 포트 공개가 없거나 기대한 브리지 네트워크에 붙지 않았으면 외부 또는 앱 컨테이너 접속이 안 돼요.

  4. 앱이 다른 컨테이너에서 접속한다면 localhost 대신 Compose 서비스 이름을 써요. 예를 들어 서비스 이름이 mysql이면 호스트명을 mysql로 맞춰야 하고, 같은 Compose 네트워크에서 127.0.0.1은 자기 자신을 가리켜요.

  5. 비밀번호와 사용자 설정이 최근에 바뀌었다면 볼륨 초기화 여부를 확인해요. MySQL 공식 이미지는 첫 기동 시에만 MYSQL_ROOT_PASSWORD, MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD를 적용하므로 기존 볼륨이 남아 있으면 변경값이 반영되지 않아요.

bash
docker ps

docker logs mysql8

docker inspect mysql8 --format '{{json .NetworkSettings.Ports}}'

# Compose 네트워크에서 앱 컨테이너 안 테스트
mysql -h mysql -P 3306 -u appuser -p

# 호스트에서 포트가 3307로 바인딩된 경우
mysql -h 127.0.0.1 -P 3307 -u root -p

Windows에서 Docker Desktop이 WSL2 백엔드를 쓰는 경우에는 3306 포트 충돌도 자주 봐야 해요. 예를 들어 Windows 쪽에서 이미 3306을 점유한 프로세스가 있거나 보안 솔루션이 바인딩을 막으면, 컨테이너는 실행 중이어도 호스트 접속은 실패할 수 있어요. 이때는 3307 같은 다른 포트로 바꿔서 테스트하는 것이 현실적이에요.

원인별 해결책과 대안은 무엇인지

인증 플러그인, 볼륨 초기화, 설정 점검 같은 해결책을 떠올리기 쉬운 그림AI로 생성된 이미지입니다
인증 플러그인, 볼륨 초기화, 설정 점검 같은 해결책을 떠올리기 쉬운 그림

원인별 해결책은 포트, 호스트명, 인증, 계정 권한, 볼륨 상태로 나눠 보면 정리가 쉬워요. 특히 MySQL 8.0의 기본 인증 플러그인 caching_sha2_password는 오래된 클라이언트나 드라이버와 충돌할 수 있으니, 먼저 클라이언트 업그레이드를 검토하는 편이 안전해요.

증상확인 포인트해결 방법
127.0.0.1:3306 접속 실패docker ps의 PORTS가 3307->3306인지 확인호스트 접속 포트를 3307로 변경하거나 컨테이너 매핑을 3306으로 다시 설정해요.
앱 컨테이너에서 localhost 접속 실패Docker Compose 서비스 이름 사용 여부 확인같은 네트워크 안에서는 localhost 대신 mysql 같은 서비스 이름으로 접속해요.
Access denied 발생사용자 호스트 권한과 비밀번호 확인필요하면 root@% 또는 전용 앱 계정을 만들고 권한을 다시 부여해요. 기존 볼륨이 있으면 초기 환경변수만 바꿔도 해결되지 않아요.
클라이언트는 있는데 인증 실패MySQL 8.0의 caching_sha2_password 지원 여부 확인오래된 드라이버를 업그레이드해요. 임시 우회가 필요하면 호환 가능한 인증 설정을 별도로 검토해요.
환경변수 바꿨는데 비밀번호가 그대로기존 데이터 볼륨 존재 여부 확인컨테이너를 지우는 것만으로는 부족할 수 있어요. 볼륨을 재생성하거나 기존 사용자 비밀번호를 SQL로 직접 변경해요.

권한 문제는 root 계정에서 특히 자주 발생해요. MySQL 8.0 환경에서는 root가 외부 접속용으로 바로 열려 있지 않거나 % 대신 localhost 범위만 허용된 초기 상태가 있을 수 있어요. 다만 이 부분은 이미지 초기화 방식과 기존 볼륨 상태에 따라 달라지므로, 항상 그렇다고 가정하기보다 실제 계정 호스트 범위를 확인하는 접근이 맞아요.

MySQL Docker 연결 오류에서 흔한 실수는 무엇인지

가장 흔한 실수는 컨테이너가 실행 중이라는 이유만으로 접속 정보도 맞다고 생각하는 것이에요. 예를 들어 docker logs에 ready for connections가 보여도 2024년 이후 많이 쓰는 Docker Desktop 4.x 환경에서는 포트 바인딩 실패, WSL2 충돌, 보안 소프트웨어 간섭 때문에 실제 접속은 막힐 수 있어요.

두 번째 실수는 환경변수를 바꾸면 비밀번호가 즉시 바뀐다고 믿는 것이에요. MySQL 공식 이미지는 첫 기동 시에만 초기값을 적용하므로, 이미 생성된 볼륨이 있으면 MYSQL_ROOT_PASSWORD=test1234로 바꿔도 이전 비밀번호가 그대로 남아요. 이 경우 2024년 현재 검색되는 Access denied 사례 상당수가 사실은 볼륨 재사용 문제예요.

세 번째 실수는 접속 위치를 구분하지 않는 것이에요. 호스트 PC에서 접속할 때는 127.0.0.1과 공개 포트를 써야 하지만, 앱 컨테이너에서 접속할 때는 Compose 서비스 이름을 써야 해요. 같은 localhost라도 1개는 호스트, 다른 1개는 컨테이너 자기 자신을 뜻하므로 2024년 실무에서도 혼동이 계속 나와요.

빠르게 해결하려면 무엇을 기억해야 하는지

빠른 해결의 핵심은 오류를 네 가지로만 분류하는 것이에요. docker inspect와 docker logs를 같이 보면 접속 실패는 대개 포트 미노출, 계정 권한 문제, 인증 플러그인 호환 문제, 볼륨 초기화 문제로 좁혀져요. 이 순서대로 보면 불필요하게 Compose 파일 전체를 다시 작성할 가능성이 줄어요.

드라이버나 GUI 클라이언트가 오래된 경우에는 MySQL 8.0 또는 8.4 LTS의 인증·TLS 협상에서 실패할 수 있으니, 설정을 뒤집기 전에 먼저 클라이언트 버전을 확인해요. 최근 실무에서는 서버를 낮추기보다 클라이언트를 올리는 쪽이 일반적이에요. 특히 새 팀 환경을 복제할 때는 서버 이미지 태그와 클라이언트 버전을 같이 기록해 두는 것이 좋아요.

마지막으로 재현 가능한 점검 메모를 남기는 것이 좋아요. 예를 들어 docker ps 출력, 실제 접속 호스트 127.0.0.1 또는 mysql, 공개 포트 3306 또는 3307, 이미지 태그 mysql:8.0 또는 mysql:8.4, 볼륨 삭제 여부를 같이 적어두면 다음 장애 때 같은 실수를 줄일 수 있어요.

FAQ

Docker에서 MySQL 로그에 ready for connections가 나오는데 왜 접속이 안 되나요?

그 로그는 MySQL 프로세스가 부팅됐다는 뜻이에요. 3306 포트 공개, docker ps의 바인딩 결과, 방화벽, 브리지 네트워크, WSL2 포트 충돌은 별도로 확인해야 해요.

호스트에서는 localhost를 쓰고, Compose에서는 서비스 이름을 써야 하나요?

맞아요. 호스트 PC에서 접속할 때는 127.0.0.1:공개포트를 쓰고, 앱 컨테이너가 MySQL 컨테이너에 붙을 때는 보통 localhost가 아니라 Compose 서비스 이름을 써야 해요.

MYSQL_ROOT_PASSWORD를 바꿨는데 왜 이전 비밀번호만 되나요?

MySQL 공식 이미지는 첫 기동 시에만 초기 환경변수를 적용해요. 기존 볼륨이 남아 있으면 새 비밀번호가 반영되지 않으므로, 볼륨을 재생성하거나 SQL로 비밀번호를 직접 바꿔야 해요.

MySQL 8.0에서 Access denied가 나는 이유는 무엇인가요?

비밀번호 오입력도 있지만, root 계정의 허용 호스트가 localhost로 제한돼 있거나 외부 접속용 계정이 없는 경우가 많아요. 사용자와 호스트 범위를 같이 확인해야 해요.

인증 플러그인 문제는 어떻게 구분하나요?

비밀번호가 맞는데도 오래된 클라이언트나 드라이버에서만 실패하면 caching_sha2_password 호환 문제를 의심해요. 이때는 서버보다 클라이언트 업그레이드를 먼저 검토하는 편이 좋아요.