Docker MariaDB 생성 및 기존 데이터 dump 이관

기존 서버에 있는 MariaDB 데이터를 로컬 Docker 환경으로 옮겨야 하는 상황이 있었다.

원본 서버의 MariaDB 버전은 10.5.27-MariaDB 였고, Docker에서도 최대한 동일한 환경으로 맞추기 위해 MariaDB10.5 이미지를 사용했다.

 

이번 작업에서 흐름은 아래와 같다.

 

1. 기존 서버 DB를 dump 뜨는 방법

2. Docker Compose(yaml) 방식으로 MariaDB 생성

3. dump 파일을 Docker 컨테이너로 옮기고 적용하는 방법

 

추가로 아래 설정도 함께 고려했다.

• lower_case_tables_names
• character-set
• collation
• 컨테이너가 내려가도 데이터가 유지되도록 volume 사용

---

1. 기존 서버의 DB를 dump 뜨는 방법

기존 서버의 MariaDB 데이터를 옮기기 위해 먼저 dump 파일을 생성했다.

dump 명령어

mysqldump -u root -p \
  --single-transaction \
  --routines \
  --triggers \
  --events \
  --default-character-set=utf8mb4 \
  biz > biz_dump.sql

 

옵션 설명

• --single-transaction
  innoDB 기준으로 비교적 안전하게 dump를 뜨기 위한 옵션

--single-transaction은 특히 InnoDB 위주 DB를 운영 중일 때는 거의 기본처럼 넣는 경우가 많아진다.

 

왜 많이 넣냐

--single-transaction은 dump 시작 시점에 일관된 스냅샷 기준으로 읽게 해줘서,

서비스가 돌아가는 중에도 테이블 락을 오래 잡지 않고 덤프를 뜰 수 있게 해준다.

 

즉 장점은:

• 서비스 영향이 상대적으로 적음
• LOCK TABLES 방식보다 안전하고 부담이 적음
• 운영 DB dump 시 자주 사용

특히 잘 맞는 경우

• 테이블 엔진이 InnoDB
• 운영중인 DB에서 백업 떠야 함
• 테이블 락을 최소화 하고 싶음

• --routines
  프로시저, 함수 포함
• --triggers
  트리거 포함
• --events
  이벤트 포함
• --default-character-set=utf8mb4
  문자셋 문제를 줄이기 위해 utf8mb4로 지정
• biz
  dump 대상 DB명
• biz_dump.sql
  생성된 dump 파일명

dump 파일 확인

ls -lh biz_dump.sql
head -n 20 biz_dump.sql

---

2. lowercase, character, collation 설정에 대해

MariaDB 이관 시 단순히 dump/import만 하면 끝나는게 아니라,

기존 환경의 문자셋과 대소문자 처리 방식도 같이 맞추는게 중요하다.

2-1. character-set / collation

이번 환경에서는 다음 기준으로 맞췄다.

• character-set-server=utf8mb4
• collation-server=utf8mb4_general_ci

의미는 다음과 같다.

• utf8mb4
  한글, 이모지 등 다양한 문자를 처리할 수 있는 문자셋
• utf8mb4_general_ci
  대소문자를 구분하지 않는(case insentive) collation
  즉, 문자열 비교 시 ABC와 abc를 동일하게 볼 수 있다.

2-2. lower_case_table_names

collation은 데이터 값 비교에 대한 설정이고,

lower_case_table_names는 테이블명/DB명 대소문자 처리 방식에 대한 설정이다.

 

예를 들어 아래 처럼 테이블명이 있을 때:

• USER_INFO
• user_info
• User_Info

이 이름들을 대소문자 구분 없이 처리하고 싶다면 lower_case_table_names=1 설정을 사용한다.

 

lower_case_table_names 주요 값

• 0 : 대소문자 구분
• 1 : 테이블명을 소문자로 저장하고, 조회 시 대소문가 구분 없이 처리

이번 Docker MariaDB 생성 시에는 아래 설정을 적용했다.

--lower_case_table_names=1

주의할 점은 lower_case_table_names는 DB 데이터 디렉토리가 처음 생성될 때 같이 결정되는 성격이 강하므로,

이미 만들어진 데이터 볼륨이 있다면 나중에 바꿨을 때 정상 반영되지 않을 수 있다.

 

즉, 이 값을 적용하려면 가능한 한 처음 컨테이너를 올릴 때부터 같이 설정하는 것이 좋다.

---

3. Docker MariaDB 만드는 방법 (docker-compose / yaml 방식)

MariaDB를 Docker compose 방식으로 생성했다.

원본이 MariaDB 10.5 계열이므로 Docker 이미지도 mariadb:10.5 를 사용했다.

 

또한 컨테이너가 종료되거나 재시작되더라도 데이터가 유지되도록 volume을 연결했다.

 

docker-compose.yml

version: "3.8"

services:
  mariadb:
    image: mariadb:10.5
    container_name: mariadb105
    environment:
      TZ: Asia/Seoul
      MARIADB_ROOT_PASSWORD: 
      MARIADB_DATABASE: 
      MARIADB_USER: 
      MARIADB_PASSWORD: 
    ports:
      - "3306:3306"
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_general_ci
      - --lower_case_table_names=1
    volumes:
      - mariadb_data:/var/lib/mysql

volumes:
  mariadb_data:

 

설정 설명

image

image: mariadb:10.5

원본 DB와 최대한 비슷한 버전으로 맞추기 위해 10.5 사용

 

environment

MARIADB_ROOT_PASSWORD: 
MARIADB_DATABASE: 
MARIADB_USER: 
MARIADB_PASSWORD:

초기 root 비밀번호, 생성할 DB, 일반 사용자 계정 정보 설정

 

command

- --character-set-server=utf8mb4
- --collation-server=utf8mb4_general_ci
- --lower_case_table_names=1

문자셋, 정렬규칙, 테이블명 대소문자 처리 방식 설정

 

volumes

- mariadb_data:/var/lib/mysql

MariaDB 실제 데이터 경로를 Docker volume에 저장

즉, 컨테이너가 내려가도 데이터는 유지된다.

---

실행 명령어

docker compose up -d

 

실행 상태 확인

docker ps
docker compose logs -f

---

4. dump 파일을 Docker로 옮기고 적용하는 방법

내 로컬 터미널에 biz_dump.sql 파일이 있고,

Docker 컨테이너 안의 MariaDB에 이 dump를 적용해야 했다.

 

내 Mac에는 mariadb 명령어가 설치되어 있지 않았기 때문에,

호스트에서 바로 Import 하는 방식 대신, dump 파일을 컨테이너 안으로 복사해서 컨테이너 내부에서 Import 했다.

---

4-1. dump 파일이 현재 경로에 있는지 확인

ls -lh biz_dump.sql

---

4-2. dump 파일을 컨테이너 안으로 복사

docker cp biz_dump.sql mariadb105:/tmp/biz_dump.sql

설명:

• 로컬의 biz_dump.sql
• 컨테이너 mariadb105 내부 /tmp/biz_dump.sql 경로로 복사

---

4-3. Docker 컨테이너 안으로 접속

docker exec -it mariadb105 bash

---

4-4. 컨테이너 내부에서 dump 적용

mariadb -uroot -p biz < /tmp/biz_dump.sql

 

 

만약 mariadb 명령어가 안 되면 아래처럼 mysql 로도 시도 가능하다.

mysql -uroot -p biz < /tmp/biz_dump.sql

---

5. 적용 후 확인 방법

컨테이너 안에서 MariaDB 접속:

mariadb -uroot -p

 

그 다음 확인:

SHOW DATABASES;
USE biz;
SHOW TABLES;

 

특정 테이블 데이터 확인:

SELECT COUNT(*) FROM 테이블명;

---

6. 설정값 확인 방법

lower_case_table_names 확인

SHOW VARIABLES LIKE 'lower_case_table_names';

 

character-set 확인

SHOW VARIABLES LIKE 'character_set_server';

 

collation 확인

SHOW VARIABLES LIKE 'collation_server';

 

DB 생성 옵션 확인

SHOW CREATE DATABASE biz;

---

7. 주의할 점

7-1. lower_case_table_names는 처음부터 맞춰야 한다

이 설정은 DB 데이터 경로가 처음 만들어질 때 영향을 크게 받는다.

이미 생성된 volume이 있으면 나중에 값을 바꿔도 원하는 대로 적용되지 않을 수 있다.

 

따라서 lower_case_table_names=1 은 가능하면 처음 컨테이너 생성 시점부터 넣는 것이 좋다.

---

7-2. volume 삭제 시 데이터도 같이 삭제된다.

아래 명령어는 volume까지 같이 삭제하므로 주의해야 한다.

docker compose down -v

 

단순히 컨테이너만 내리고 싶으면

docker compose down

이 경우 volume은 남기 때문에 데이터는 유지된다.

---

7-3. 원본 DB와 버전 차이가 크면 문제가 될 수 있다.

이번에는 원본이 10.5.27-MariaDB 였기 때문에 Docker도 10.5로 맞췄다.

버전 차이가 크면 프로시저, 함수, 정렬규칙, 인증 방식 등에서 차이가 날 수 있으므로 가능하면 같은 메이저 버전으로 맞추는 것이 안전하다.