Spring Boot DB + Docker + TimeZone

TMT

MySQL의 타임존 설정은 여러 레이어에서 동시에 적용되며, 각각의 설정은 서로 다른 역할을 합니다. 아래에서 Docker Compose에서의 MySQL 설정과 Spring Boot의 JDBC URL 설정이 어떻게 작동하는지, 그리고 어느 부분이 필수이고 어느 부분은 선택적인지 정리해 보겠습니다.

1. Docker Compose 내 MySQL 설정

a. MySQL 커맨드 옵션

command:
  - --default-time-zone="+09:00"
  - --skip-character-set-client-handshake
  - --character-set-server=utf8mb4
  - --collation-server=utf8mb4_unicode_ci
  - --default-authentication-plugin=mysql_native_password
  - --lower_case_table_names=0
  • --default-time-zone="+09:00"
    MySQL 서버의 내부 타임존을 +09:00 (Asia/Seoul과 동일)으로 설정합니다.
    → 이 설정은 MySQL이 내부적으로 사용하는 시간(예: NOW(), CURRENT_TIMESTAMP 등)에 직접 영향을 줍니다.

b. 환경 변수

environment:
  MYSQL_ROOT_USER: ${MYSQL_ROOT_USER}
  MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
  MYSQL_DATABASE: ${MYSQL_DATABASE}
  TZ: Asia/Seoul
  • TZ: Asia/Seoul
    컨테이너의 OS 수준에서 사용하는 기본 시간대를 설정합니다.
    → MySQL 서버는 기본적으로 명령행 옵션(--default-time-zone)을 우선적으로 사용하므로, 내부 DB 타임존 계산에는 직접적인 영향을 주지 않습니다.
    → 다만, 컨테이너 내 로그 기록이나 OS 기반의 시간 표시에는 영향을 줄 수 있으므로 운영상의 일관성을 위해 설정하는 것이 좋습니다.

2. Spring Boot의 JDBC URL 설정

url=jdbc:mysql://mysql:3306/mydev?serverTimezone=Asia/Seoul&useSSL=false&allowPublicKeyRetrieval=true
  • serverTimezone=Asia/Seoul
    MySQL JDBC 드라이버에 서버의 타임존 정보를 명시적으로 알려줍니다.
    → 이 옵션은 드라이버가 MySQL로부터 전달받은 날짜/시간 데이터를 올바르게 해석하고 변환하도록 돕습니다.
    → 때로는 MySQL 서버가 올바른 타임존 정보를 제공하더라도, 드라이버가 이를 자동으로 감지하지 못해 타임존 관련 오류가 발생할 수 있으므로 명시적으로 지정하는 것이 좋습니다.

3. 정리: 어느 부분이 필수이고, 어느 부분은 선택적인가?

  • 필수 사항:

    • --default-time-zone="+09:00" (Docker Compose의 MySQL 커맨드 옵션):
      → MySQL 서버 내부의 타임존을 올바르게 설정하기 위해 반드시 필요합니다.
    • serverTimezone=Asia/Seoul (JDBC URL 옵션):
      → MySQL 드라이버가 올바른 타임존으로 날짜/시간 데이터를 처리하도록 보장하기 위해 권장됩니다.
      → 드라이버에 따라 자동 감지가 어려운 경우가 많으므로 명시하는 것이 안전합니다.

  • 선택 사항:

    • TZ: Asia/Seoul (환경 변수):
      → OS 레벨, 즉 컨테이너의 시스템 시간대를 설정합니다.
      → MySQL 내부 시간 계산에는 --default-time-zone 옵션이 우선 적용되므로 필수는 아니지만, 로그 기록 등에서 일관된 타임존을 유지하려면 설정하는 것이 좋습니다.

결론

  • MySQL 내부 타임존:
    → --default-time-zone="+09:00" 옵션으로 설정합니다.

  • 컨테이너 OS 타임존:
    → TZ: Asia/Seoul 환경 변수를 사용합니다 (운영 일관성을 위해 설정 추천).

  • JDBC 드라이버 타임존:
    → serverTimezone=Asia/Seoul 옵션을 JDBC URL에 포함하여, 드라이버가 올바르게 시간 데이터를 처리하도록 합니다.

따라서, 위 설정들을 함께 사용하면 MySQL 서버, 컨테이너, 그리고 Spring Boot 애플리케이션 간에 시간대 관련 불일치 없이 일관된 시간 처리가 가능해집니다. 만약 MySQL 서버의 타임존이 이미 정확하게 설정되어 있다 하더라도, JDBC 드라이버의 안정적인 동작을 위해 serverTimezone 옵션은 유지하는 것이 좋습니다.

Edit this page
Index

On this Page