Docker DB Replication Lab

이 프로젝트는 Docker Compose를 사용하여 다양한 종류의 데이터베이스에 대한 마스터-레플리카(Master-Replica) 복제 환경을 구축하고 테스트하기 위한 랩(Lab) 저장소입니다. 향후 지속적으로 더 많은 데이터베이스 환경이 추가될 예정입니다.

🚀 지원되는 데이터베이스 환경 (계속 추가됨)

현재 구성되어 있는 데이터베이스 목록 및 접속 포트는 다음과 같습니다:

• PostgreSQL 18.3
  • Master (포트: 5432)
  • Replica (포트: 5433)
• MySQL 8.4.7
  • Master (포트: 3306)
  • Replica (포트: 3307)
• MSSQL 2022 (AlwaysOn 가용성 그룹)
  • Master (포트: 1433)
  • Replica (포트: 1434)
• MongoDB 8.3.2
  • Master (포트: 27017)
  • Replica (포트: 27018)

📅 추가 예정 데이터베이스 환경

향후 다음 환경들이 순차적으로 추가될 예정입니다:

• Redis (Master-Replica / Sentinel): 인메모리 Key-Value 데이터의 비동기 복제 및 모니터링/승격 구조 환경
• MariaDB (Galera Cluster): RDBMS 기반의 강력한 동기식 다중 마스터(Multi-Master) 클러스터 환경

📋 사전 요구 사항

1. 로컬 네트워크 설정

컨테이너 간 통신을 위해 localnetwork라는 이름의 외부 네트워크가 필요합니다. (docker-compose.yml에서 external 네트워크로 지정되어 있습니다.)

docker network create localnetwork

# 확인
docker network ls

2. 환경 변수 설정 (.env)

프로젝트 루트 경로에 .env 파일을 만들고 아래와 같이 환경 변수를 설정합니다. (docker-compose.yml에서 이 값들을 참조합니다.)

# MySQL 관리자(Root) 계정 (MySQL 특성상 주로 root로 사용)
DATABASE_ROOT_USER_MYSQL=root
# PostgreSQL 관리자(Superuser) 계정
DATABASE_ROOT_USER_POSTGRES=postgres
# MSSQL 관리자(Superuser) 계정
DATABASE_ROOT_USER_MSSQL=sa

# 관리자 공통 비밀번호
DATABASE_ROOT_PASSWORD=paSsw0rd

# 복제(Replication) 권한을 가질 계정 설정
DATABASE_REPL_USER=repl
DATABASE_REPL_USER_PASSWORD=replpaSsw0rd

# 기본적으로 생성할 데이터베이스(스키마) 이름
DATABASE_DEFAULT_SCHEMA=TEST_DB

# MSSQL 에디션 설정
MSSQL_PID=Developer

🛠 실행 방법

이 프로젝트는 데이터베이스 마운트 디렉토리와 초기 복제 설정을 항상 깔끔하게 유지할 수 있도록 초기화 및 자동 실행 스크립트(run-init.sh / run-init.bat)를 기본 실행 방법으로 제공합니다.

1. 스크립트를 이용한 자동 초기화 및 실행

기존 컨테이너와 데이터 볼륨을 정리하고, 로컬 디렉토리 구조를 다시 구축하여 모든 데이터베이스 환경을 깔끔하게 처음부터 구동합니다.

• macOS / Linux:

  chmod +x run-init.sh
  ./run-init.sh

• Windows (CMD / PowerShell):

  run-init.bat

🔍 스크립트 내부 동작 방식 및 프로세스

초기화 스크립트를 실행하면 백그라운드에서 다음 단계가 순차적으로 실행됩니다:

1. 기존 리소스 정리 (Clean Up): docker compose -p db-lab down --volumes 명령을 통해 현재 실행 중이거나 중지 상태인 db-lab 프로젝트의 모든 컨테이너를 정지하고, 생성된 도커 네트워크 및 볼륨을 완전히 제거합니다.
2. 로컬 데이터 디렉토리 구조 재구성: 로컬에 잔존하는 DB 마운트 디렉토리(databases)를 통째로 안전하게 삭제하여 캐시나 데이터 오염을 예방합니다. 그 후 각 데이터베이스(PostgreSQL, MySQL, MSSQL, MongoDB)의 Master 및 Replica 마운트 경로를 새롭게 구조화하여 재생성합니다.
3. 신규 컨테이너 강제 재구동 및 설정: docker compose -p db-lab up -d --force-recreate 명령을 통해 컨테이너를 백그라운드에서 강제로 재생성하며 구동합니다.
   • 각 데이터베이스의 Replica 컨테이너들은 docker-compose.yml 내 depends_on (service_healthy) 조건에 의해 Master 서버의 헬스체크(Healthcheck)가 완료된 후 가동됩니다.
   • 컨테이너가 처음으로 활성화되면 _init 디렉토리 하위의 초기화 스크립트가 실행되어 복제(Replication)에 필요한 사용자 계정과 권한이 자동으로 설정됩니다.

---

2. 수동 실행 및 종료 방법

스크립트를 사용하지 않고 터미널에서 개별적인 도커 컴포즈 명령을 활용해 수동으로 컨테이너를 시작하거나 종료하는 방법입니다.

컨테이너 수동 시작

# 프로젝트 이름을 'db-lab'으로 지정하여 컨테이너 강제 재생성 및 실행
docker compose -p db-lab up -d --force-recreate

💡 Tip: --force-recreate 옵션은 설정의 변경 여부와 관계없이 기존 컨테이너를 지우고 새로 만듭니다. 개발 및 테스트 랩(Lab) 환경에서 기존 꼬인 상태를 정리하고 확실히 새롭게 배포할 때 유용합니다.

컨테이너 수동 종료 (리소스 반환)

네트워크 볼륨 및 축적된 복제 데이터 볼륨까지 안전하게 삭제하고 컨테이너를 모두 종료하려면 다음 명령을 실행합니다. 프로젝트명(db-lab)을 동일하게 맞춰주어야 정상 처리됩니다.

docker compose -p db-lab down -v

🔍 접속 및 확인 방법

실행 중인 각 데이터베이스 컨테이너에 접속하는 방법입니다.

💻 로컬 DB 클라이언트 (GUI) 접속

DBeaver, DataGrip, MySQL Workbench 등 호스트(로컬 PC)에 설치된 DB 클라이언트 프로그램을 사용할 경우, 아래 정보를 이용해 접속하시면 됩니다.

• Host (IP): localhost 또는 127.0.0.1
• Port:
  • PostgreSQL Master: 5432 / Replica: 5433
  • MySQL Master: 3306 / Replica: 3307
  • MSSQL Master: 1433 / Replica: 1434
  • MongoDB Master: 27017 / Replica: 27018
• 계정 및 비밀번호: .env 파일에 설정해 둔 관리자 계정 정보를 사용합니다.

🐳 컨테이너 내부 터미널(CLI) 접속

터미널에서 직접 각 데이터베이스 컨테이너 내부 셸로 들어가 접속하는 방법입니다.

PostgreSQL

• Master 접속:

  docker exec -it postgres-master bash -c "psql -U \${DATABASE_ROOT_USER_POSTGRES} -d \${DATABASE_DEFAULT_SCHEMA}"

• Replica 접속:

  docker exec -it postgres-repl bash -c "psql -U \${DATABASE_ROOT_USER_POSTGRES} -d \${DATABASE_DEFAULT_SCHEMA}"

MySQL

• Master 접속:

  docker exec -it mysql8-master bash -c "mysql -u root -p\${DATABASE_ROOT_PASSWORD}"

• Replica 접속:

  docker exec -it mysql8-repl bash -c "mysql -u root -p\${DATABASE_ROOT_PASSWORD}"

MSSQL

• Master 접속:

  docker exec -it mssql-master /opt/mssql-tools18/bin/sqlcmd -S localhost -U SA -P "\${DATABASE_ROOT_PASSWORD}" -C -d "\${DATABASE_DEFAULT_SCHEMA}"

• Replica 접속:

  docker exec -it mssql-repl /opt/mssql-tools18/bin/sqlcmd -S localhost -U SA -P "\${DATABASE_ROOT_PASSWORD}" -C -d "\${DATABASE_DEFAULT_SCHEMA}"

MongoDB

• Master 접속:

  docker exec -it mongo-master mongosh -u \${DATABASE_ROOT_USER_MYSQL} -p \${DATABASE_ROOT_PASSWORD} --authenticationDatabase admin \${DATABASE_DEFAULT_SCHEMA} --eval "db.runCommand({ replSetGetStatus: 1 })"

• Replica 접속:

  docker exec -it mongo-repl mongosh -u \${DATABASE_ROOT_USER_MYSQL} -p \${DATABASE_ROOT_PASSWORD} --authenticationDatabase admin \${DATABASE_DEFAULT_SCHEMA} --eval "db.runCommand({ replSetGetStatus: 1 })"

---

기타: 아키텍처 및 OS 확인용 명령어

# 이미지 빌드 예제 (Dockerfile 사용 시)
docker build -t my-custom-db-image:1.0 .

# 임의의 컨테이너 접속 예제
docker exec -it my-custom-container bash

# aarch64 / x86_64 기반 OS 쉘 실행 및 아키텍처 확인 (Ubuntu 예제)
docker run -it --platform linux/aarch64 ubuntu:22.04 /bin/bash
docker run -it --platform linux/amd64 ubuntu:22.04 /bin/bash
uname -m