1. 왜 2019년 방식(Docker Hub microsoft/mssql-server-linux)은 더 이상 작동하지 않는가?

2019년 당시 웹 검색이나 NAS(OMV, Synology) 커뮤니티의 기술 블로그를 살펴보면 다음과 같은 명령어가 표준처럼 공유되었습니다:

# [과거 2019년 구형 튜토리얼 예시]
docker run -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=yourStrong(!)Password' \
   -p 1433:1433 --name sql1 \
   -d microsoft/mssql-server-linux:latest

OpenMediaVault(OMV 4.x)의 GUI 도커 플러그인이나 웹 터미널(Shell in a Box)을 통해 위 명령을 입력하면 손쉽게 구동되던 시절이 있었습니다. 하지만 현재 이 명령을 그대로 실행하면 최신 패치가 전혀 적용되지 않은 5년 전 구형 빌드가 다운로드되거나, 환경에 따라 다운로드 자체가 실패하게 됩니다.

1) 마이크로소프트의 MCR(Microsoft Container Registry) 이전 배경

마이크로소프트는 2019년 중반부터 전사적인 컨테이너 공급망 보안 및 배포 효율화를 위해 자사의 모든 공식 엔터프라이즈 컨테이너 이미지를 Docker Hub에서 자체 레지스트리인 MCR(Microsoft Artifact Registry / Container Registry, mcr.microsoft.com)으로 완전 이전했습니다.

[과거 아키텍처 (2019년 이전)]
Docker Client ───────► Docker Hub (microsoft/mssql-server-linux) 
                       ※ 2019년 이후 신규 CU 및 보안 패치 완전 중단 (EOL)

[현대 표준 아키텍처 (2020년 ~ 현재)]
Docker Client ───────► MCR (mcr.microsoft.com/mssql/server:<tag>)
                       ※ 최신 보안 패치, Ubuntu 22.04 LTS 베이스, 정기 CU 릴리즈

Docker Hub에 방치된 구형 이미지를 사용할 경우 다음과 같은 치명적인 문제가 발생합니다:

• 중대한 보안 취약점 방치: 수년 동안 누적된 OpenSSL 구버전 취약점 및 리눅스 커널 패치가 전혀 적용되지 않아 보안 감사에 적발됩니다.
• 신규 기능 및 버전 부재: SQL Server 2019의 최신 누적 업데이트(CU)와 최신 SQL Server 2022 이미지는 Docker Hub에 아예 배포되지 않았습니다.
• 클라이언트 드라이버 비호환: 최신 TLS 1.3 암호화 핸드셰이크가 실패하거나 최신 DB 도구와 접속이 거부됩니다.

2) OMV 전용 GUI 환경에서 범용 Docker CLI & Compose로의 전환

과거 OMV 4.x 시절에는 NAS 웹 콘솔의 그래픽 인터페이스에 종속된 튜토리얼이 많았지만, 현대 컨테이너 운영 환경은 표준 Docker CLI와 Docker Compose를 기반으로 인프라를 코드(IaC)로 정의하는 것이 정석입니다. 로컬 PC(Windows, macOS, Linux), 사내 온프레미스 서버, 클라우드 VM(AWS EC2, Azure VM, GCP) 어디서나 동일한 명세서로 재현 가능한 환경을 구축해야 합니다.

2. SQL Server 2022, 2019, 2017 버전별 특징 및 권장 태그 비교표

현업에서는 무조건 최신 버전만 사용하는 것이 아니라, 고객사의 운영 환경이나 기존 레거시 데이터베이스 엔진 버전에 맞추어 로컬 개발 환경을 동기화해야 합니다. 마이크로소프트 공식 MCR 저장소(mcr.microsoft.com/mssql/server)에서 제공하는 주요 버전별 스펙은 다음과 같습니다.

에디션 플래그 (MSSQL_PID) 설정 기준

• Developer (기본 추천): Enterprise 에디션의 모든 고급 기능(고급 파티셔닝, 인메모리 OLTP, Transparent Data Encryption 등)을 100% 동일하게 제공하며, 개발 및 테스트 목적으로 무상 제공됩니다. (단, 상용 프로덕션 배포 불가)
• Express: 소규모 상용 환경에서도 무료로 배포 가능한 에디션입니다. 단, 최대 1소켓 / 4코어 CPU 제한, 버퍼 풀 메모리 1,410MB 제한, DB당 파일 용량 10GB 제한이 하드코딩되어 있습니다.
• Standard / Enterprise: 실제 상용 라이선스 키를 보유한 경우 제품 키를 직접 입력(MSSQL_PID=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX)하여 라이선스를 활성화합니다.
• Evaluation: 180일 동안 Enterprise 에디션을 무료 평가할 수 있는 임시 라이선스입니다. (180일 경과 시 엔진 중단)

3. 버전별 docker run 단일 실행 명령어 완벽 가이드

단일 컨테이너로 빠르게 테스트하거나 CI 파이프라인에서 임시 데이터베이스를 띄울 때는 docker run 명령어를 사용합니다. 필수 파라미터의 의미를 정확히 이해하고 실행해야 예기치 않은 컨테이너 크래시를 방지할 수 있습니다.

1) SQL Server 2022 (최신 표준 권장)

docker run -d \
  --name mssql-2022 \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=YourStrong@Passw0rd2022" \
  -e "MSSQL_PID=Developer" \
  -p 1433:1433 \
  -v mssql_2022_data:/var/opt/mssql \
  --restart unless-stopped \
  mcr.microsoft.com/mssql/server:2022-latest

2) SQL Server 2019 (기업 레거시 호환)

docker run -d \
  --name mssql-2019 \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=YourStrong@Passw0rd2019" \
  -e "MSSQL_PID=Developer" \
  -p 1433:1433 \
  -v mssql_2019_data:/var/opt/mssql \
  --restart unless-stopped \
  mcr.microsoft.com/mssql/server:2019-latest

3) SQL Server 2017 (회귀 테스트용)

docker run -d \
  --name mssql-2017 \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=YourStrong@Passw0rd2017" \
  -e "MSSQL_PID=Developer" \
  -p 1433:1433 \
  -v mssql_2017_data:/var/opt/mssql \
  --restart unless-stopped \
  mcr.microsoft.com/mssql/server:2017-latest

4. 실무 표준 docker-compose.yml 완벽 구성 (데이터 영속화, 헬스체크, 리소스 제한)

실무 개발 환경에서는 여러 개발자가 동일한 설정을 공유하고, Git을 통해 인프라를 버전 관리할 수 있도록 Docker Compose를 사용하는 것이 업계 표준입니다. 특히 비밀번호 하드코딩 방지를 위한 환경 변수(.env) 분리와 컨테이너 준비 상태를 검증하는 헬스체크(Healthcheck) 설정이 반드시 포함되어야 합니다.

1) 디렉터리 구조 설계

my-mssql-project/
├── .env                  # 민감 정보 및 환경 변수 (Git 추적 제외)
├── .env.example          # 팀원 공유용 템플릿
└── docker-compose.yml    # 컨테이너 서비스 정의 명세서

2) .env 환경 변수 파일 정의

# .env
MSSQL_VERSION=2022-latest
MSSQL_SA_PASSWORD=YourStrong@Passw0rd2026!
MSSQL_PID=Developer
MSSQL_PORT=1433
MSSQL_MEMORY_LIMIT=4g
MSSQL_CPU_LIMIT=2.0

3) 프로덕션급 docker-compose.yml 완성본

version: '3.8'

services:
  mssql:
    image: mcr.microsoft.com/mssql/server:${MSSQL_VERSION:-2022-latest}
    container_name: mssql-server
    restart: unless-stopped
    ports:
      - "${MSSQL_PORT:-1433}:1433"
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD}"
      MSSQL_PID: "${MSSQL_PID:-Developer}"
      # 인메모리 버퍼 풀 메모리 한도 설정 (선택 사항)
      MSSQL_MEMORY_LIMIT_MB: "3500"
    volumes:
      # 도커 네임드 볼륨을 통한 안전한 데이터 영속화
      - mssql_data:/var/opt/mssql
    # 데이터베이스 서비스 준비 상태를 감지하는 헬스체크
    healthcheck:
      test: [
        "CMD-SHELL",
        "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P $${MSSQL_SA_PASSWORD} -C -Q 'SELECT 1' || exit 1"
      ]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s
    # 컨테이너 리소스 제한 (호스트 OOM 방지)
    deploy:
      resources:
        limits:
          cpus: "${MSSQL_CPU_LIMIT:-2.0}"
          memory: "${MSSQL_MEMORY_LIMIT:-4g}"

volumes:
  mssql_data:
    driver: local

4) 실행 및 상태 점검 명령어

# 백그라운드로 서비스 기동
docker compose up -d

# 기동 상태 및 헬스체크 통과 여부 확인 (healthy 표시 확인)
docker compose ps

# 실시간 기동 로그 모니터링
docker compose logs -f mssql

5. Apple Silicon Mac (M1/M2/M3/M4 ARM64) 개발자를 위한 2가지 완벽 대안

M1, M2, M3, M4 등 애플 실리콘 칩셋이 탑재된 Mac을 사용하는 개발자들은 도커로 MSSQL을 실행할 때 당황스러운 상황을 마주합니다. 마이크로소프트가 SQL Server 공식 컨테이너를 오직 x86_64(linux/amd64) 아키텍처로만 빌드하여 배포하고 있기 때문입니다.

[Apple Silicon Mac (ARM64 Architecture)]
                 │
   ┌─────────────┴─────────────────────────┐
   ▼                                       ▼
[대안 1: Rosetta 2 amd64 에뮬레이션]      [대안 2: Azure SQL Edge ARM64 네이티브]
- 이미지: mcr.microsoft.com/mssql/server   - 이미지: mcr.microsoft.com/azure-sql-edge
- 아키텍처: linux/amd64 (에뮬레이션)       - 아키텍처: linux/arm64 (네이티브)
- 기능: SQL Server 2022 기능 100%          - 기능: 경량 T-SQL, IoT/CRUD 전용
- 용도: 프로덕션과 완벽한 기능 일치         - 용도: 배터리 절약, 고속 로컬 단위 테스트

대안 1. Rosetta 2 기반 amd64 에뮬레이션 (정식 SQL Server 2022 기능 100% 활용)

Docker Desktop for Mac의 Rosetta 2 변환 가속 기술을 활성화하고 컨테이너 플랫폼을 명시적으로 지정하여 실행합니다:

# Mac ARM64 환경에서 정식 SQL Server 2022 실행 (--platform 플래그 필수)
docker run -d \
  --name mssql-mac-rosetta \
  --platform linux/amd64 \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=YourStrong@Passw0rdMac!" \
  -e "MSSQL_PID=Developer" \
  -p 1433:1433 \
  -v mssql_mac_data:/var/opt/mssql \
  mcr.microsoft.com/mssql/server:2022-latest

대안 2. Azure SQL Edge ARM64 네이티브 컨테이너 (초경량 고속 개발용)

마이크로소프트 공식 ARM64 네이티브 엔진인 Azure SQL Edge를 사용하여 메모리 점유율 500MB대의 초경량 환경을 구동합니다:

docker run -d \
  --name mssql-sql-edge \
  -e "ACCEPT_EULA=Y" \
  -e "MSSQL_SA_PASSWORD=YourStrong@Passw0rdEdge!" \
  -p 1433:1433 \
  -v sqledge_data:/var/opt/mssql \
  mcr.microsoft.com/azure-sql-edge:latest

6. 도커 MSSQL 실행 시 가장 많이 겪는 4대 에러 트러블슈팅

Docker 환경에서 MSSQL 컨테이너를 올릴 때 겪는 에러의 95% 이상은 다음 4가지 원인으로 인해 발생합니다. 컨테이너가 이유 없이 죽거나 접속이 거부될 때 각 항목을 순서대로 점검하십시오.

[Gotcha 1] UID 10001 볼륨 권한 거부 (Operating system error 5: Access is denied)

/opt/mssql/bin/sqlservr: Error: The file '/var/opt/mssql/data/master.mdf' cannot be opened. 
Operating system error 5: "5(Access is denied.)".
Error: 17113 Severity: 16 State: 1.
Error 2(The system cannot find the file specified.) occurred while opening file

근본 원인: 컨테이너 내부의 MSSQL 프로세스는 보안 격리를 위해 root가 아닌 전용 시스템 계정인 UID 10001 (mssql), GID 0 권한으로 실행됩니다. 호스트의 디렉터리를 마운트했을 때 일반 사용자(UID 1000 등) 소유로 되어 있으면 쓰기 권한이 거부되어 컨테이너가 즉각 크래시 루프에 빠집니다.

# 호스트 디렉터리의 소유권을 컨테이너 프로세스 UID인 10001로 지정
sudo chown -R 10001:0 ./mssql-data

# 또는 개발 환경 한정 전체 권한 부여
sudo chmod -R 777 ./mssql-data

# (가장 안전한 방법) 호스트 바인드 대신 Docker Named Volume 사용
-v mssql_data:/var/opt/mssql

[Gotcha 2] SA 비밀번호 복잡도 미달로 인한 무언의 컨테이너 종료 (Silent Exit)

ERROR: The password does not meet the SQL Server password policy requirements 
because it is not complex enough. The password must be at least 8 characters long 
and contain characters from three of the following four categories: 
uppercase letters, lowercase letters, numbers, and symbols.

근본 원인: sa 계정의 비밀번호는 최소 8자리 이상이면서 대문자, 소문자, 숫자, 특수문자 중 최소 3개 범주 이상을 반드시 포함해야 합니다. 단순 비밀번호(1234, password 등)는 엔진 기동 시 즉시 강제 종료됩니다.

# 복잡도를 완벽히 충족하는 강력한 비밀번호 설정 예시
MSSQL_SA_PASSWORD="YourStrong@Passw0rd2026!"

# 주의: docker-compose.yml 에서는 $ 기호 사용 시 $$ 로 이스케이프 필요

[Gotcha 3] 메모리 2GB 미달로 인한 기동 거부 (requires at least 2000 megabytes)

sqlservr: This program requires a machine with at least 2000 megabytes of memory to run.

근본 원인: 리눅스용 SQL Server 바이너리 내부에는 가용 메모리를 검사하여 최소 2,000MB(약 2GB) RAM이 확보되지 않으면 즉각 구동을 거부하는 하드웨어 체크 로직이 하드코딩되어 있습니다. Docker Desktop 설정 기본값이 1~2GB 수준일 때 발생합니다.

1. Docker Desktop: Settings ➔ Resources ➔ Memory 슬라이더를 4GB (4096MB) 이상으로 설정
2. Windows WSL2: %USERPROFILE%\.wslconfig 파일에 [wsl2] memory=4GB 설정 후 wsl --shutdown

[Gotcha 4] sqlcmd v18+ 인증서 신뢰 오류 (SSL Provider: certificate verify failed)

Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : SSL Provider: 
[error:0A000086:SSL routines::certificate verify failed:self-signed certificate].
Sqlcmd: Error: Microsoft ODBC Driver 18 for SQL Server : Client unable to establish connection.

근본 원인: SQL Server 2022 및 최신 ODBC Driver 18 기반 mssql-tools18은 기본적으로 모든 네트워크 트래픽의 암호화를 강제(Encrypt=Mandatory)합니다. 로컬 컨테이너의 자체 서명(Self-Signed) 인증서를 신뢰하도록 선언하지 않으면 연결이 거부됩니다.

# CLI 접속 시 -C (Trust Server Certificate) 옵션 필수 전달
docker exec -it mssql-2022 /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd2022' -C

# JDBC 연결 문자열: ;trustServerCertificate=true;encrypt=true;
# C# / .NET 연결 문자열: TrustServerCertificate=True;Encrypt=True;

7. 접속 검증 및 실무 개발 툴 연동

컨테이너가 성공적으로 가동되었다면 명령행 인터페이스(CLI)와 실무 개발 도구(GUI)를 통해 데이터베이스 접속을 검증합니다.

1) CLI를 통한 즉시 버전 쿼리 검증

# SQL Server 2022 환경 (tools18 경로 + -C 옵션)
docker exec -it mssql-2022 /opt/mssql-tools18/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd2022' -C \
  -Q "SELECT @@VERSION AS [SQL_Server_Version];"

# SQL Server 2019 / 2017 환경 (기존 tools 경로)
docker exec -it mssql-2019 /opt/mssql-tools/bin/sqlcmd \
  -S localhost -U sa -P 'YourStrong@Passw0rd2019' \
  -Q "SELECT @@VERSION AS [SQL_Server_Version];"

SQL_Server_Version
--------------------------------------------------------------------------------------------------------------------------------
Microsoft SQL Server 2022 (RTM-CU14) (KB5039747) - 16.0.4135.4 (X64) 
        Jun 17 2024 16:32:00 
        Copyright (C) 2022 Microsoft Corporation
        Developer Edition (64-bit) on Linux (Ubuntu 22.04.4 LTS) <X64>

(1 rows affected)

2) DBeaver GUI 연결 설정 완벽 가이드

가장 널리 쓰이는 무료 오픈소스 데이터베이스 관리 도구인 DBeaver에서의 연결 단계입니다:

3) Visual Studio Code (mssql 확장) 연결

• VS Code 마켓플레이스에서 SQL Server (mssql) 검색 후 설치.
• 좌측 SQL Server 아이콘 클릭 ➔ Add Connection (+) 클릭.
• Server name: localhost,1433 입력.
• Authentication Type: SQL Login 선택 ➔ User sa 및 Password 입력.
• Trust server certificate?: Yes 선택.

8. 실무 체크리스트 및 최종 요약

운영 및 협업 환경에 도커 기반 SQL Server를 배포하기 전에 점검해야 할 6단계 프로덕션 체크리스트입니다.