컨테이너로 실행된 Spring Boot가 MySQL에 연결되지 않는 이유

Docker로 Spring Boot와 MySQL을 함께 실행할 때,
**“DB 연결이 되지 않는다”**는 오류를 한 번쯤 경험해보셨을 겁니다.
이번 포스팅에서는 그 원인과 해결 방법을 간단하게 정리해보겠습니다 ⚙️

 

컨테이너에서 실행 시 연결이 안 되는 이유

Spring Boot 애플리케이션을 컨테이너로 실행하면,
호스트 환경의 localhost와는 완전히 분리된 네트워크 공간에서 동작하게 됩니다.

즉,

• 호스트 컴퓨터의 localhost:3306은
  Spring Boot 컨테이너 입장에서는 존재하지 않는 주소입니다.
• 각 컨테이너는 자신만의 IP 주소와 네트워크를 가짐으로써,
  서로 직접 접근할 수 없습니다.

결국 아래 구조처럼
Spring Boot → MySQL로의 연결이 localhost를 기준으로는 불가능한 것이죠.

 

잘못된 DB 설정 예시

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: root
    password: pwd1234
    driver-class-name: com.mysql.cj.jdbc.Driver

위 설정은 호스트 기준의 주소를 사용하고 있기 때문에,
컨테이너 내부의 Spring Boot 애플리케이션이
자신 내부에서 localhost:3306을 찾으려다 실패하게 됩니다.

 

그럼 어떻게 해결할까?

 

정답은 바로 —
Compose에서 정의한 service 이름을 사용하면 된다!

Docker Compose에서는 컨테이너 간 통신 시
서비스 이름이 곧 컨테이너의 “호스트 이름(hostname)” 역할을 합니다.

 

 

올바른 DB 설정으로 수정하기

spring:
  datasource:
    url: jdbc:mysql://my-db:3306/mydb
    username: root
    password: pwd1234
    driver-class-name: com.mysql.cj.jdbc.Driver

여기서 my-db는 compose.yml에 정의된 MySQL 서비스 이름입니다.

 

 

compose.yml 예시

services:
  my-server:
    build: .
    ports:
      - 8080:8080
    depends_on:
      my-db:
        condition: service_healthy

  my-db:
    image: mysql
    environment:
      MYSQL_ROOT_PASSWORD: pwd1234
      MYSQL_DATABASE: mydb
    volumes:
      - ./mysql_data:/var/lib/mysql
    ports:
      - 3306:3306
    healthcheck:
      test: ["CMD", "mysqladmin", "ping"]
      interval: 5s
      retries: 10

포인트

• my-server가 실행되기 전,
  my-db가 정상적으로 실행(healthy)되었는지를 확인
• my-db → service 이름이며, 컨테이너 간 통신 시 호스트명 역할

 

정리하면

 

Docker Compose의 네트워크 구조를 이해하면
컨테이너 간 통신 문제는 훨씬 쉽게 해결됩니다.
Spring Boot와 MySQL을 함께 띄울 때는
“localhost” 대신 서비스 이름으로 접근한다는 점만 기억하세요! 🐳