🛠️ AI 코딩 CLI 명령어 모음 시리즈 (전체 4편)

1. Claude Code 자주 쓰는 명령어 모음 — CLI 플래그부터 슬래시 명령어까지
2. Codex CLI 자주 쓰는 명령어 모음 — 서브커맨드부터 슬래시 명령어까지
3. Gemini CLI 자주 쓰는 명령어 모음 — 헤드리스 모드와 슬래시 명령어까지
4. Claude Code · Codex · Gemini CLI 비교 — 권한 모드부터 컨텍스트 파일까지 ← 지금 글

Summary

1편 ~ 3편 에서 Claude Code · Codex · Gemini CLI 세 도구의 명령어를 각각 정리했어요. 4편은 시리즈 마무리로, 셋을 같은 축으로 나란히 놓고 비교해보는 글이에요. 명령어 카탈로그를 다시 나열하기보단, 실제로 도구를 고를 때 갈리는 포인트(권한 모드 이름 차이, 헤드리스 모드의 깊이, 세션 이어가기 방식, 컨텍스트 파일 컨벤션, MCP/확장 통합)를 한 표에 정리하고 작업 성격별로 어떤 도구가 어울리는지 정리합니다.

💡 이 글에서 다루는 것

• 한눈에 보는 세 도구 비교 표 (모드·플래그·컨텍스트 파일 이름)
• 권한/승인 모델 비교 — permission-mode vs approval-mode vs /permissions
• 헤드리스 자동화 비교 — -p / codex exec / -p -o stream-json
• 세션 이어가기와 체크포인트 비교
• 컨텍스트 파일: CLAUDE.md / AGENTS.md / GEMINI.md 차이
• MCP·확장·스킬 통합 결의 차이
• 작업 유형별 추천 매트릭스

1. 한눈에 보는 차이

먼저 세 도구를 같은 축으로 나란히 놓아볼게요. “같은 개념인데 이름만 다른 것” 이 많아서 이 표가 머릿속 매핑에 도움 돼요.

큰 그림은 정말 비슷한데, 모드 이름과 컨텍스트 파일명이 각자 따로 진화한 거예요. 셋 다 쓰다 보면 머릿속에서 자연스럽게 매핑이 잡힙니다.

2. 권한·승인 모델 — 가장 헷갈리는 지점

세 도구가 모두 “위험한 액션은 사용자에게 묻는다” 는 같은 결인데, 모델 이름과 단계 수가 미묘하게 달라요.

2-1. Claude Code — 5단계, 플래그 중심

default → acceptEdits → auto → plan → bypassPermissions

• default 매번 묻기
• acceptEdits 파일 편집 자동 / 셸은 묻기
• auto 분류기 기반 자동 (위험한 것만 묻기) ← 일상에서 가장 자주 쓰는 모드
• plan 코드 안 건드림
• bypassPermissions 전부 자동 (위험)

CLI 띄울 때 --permission-mode auto 같이 박거나, 세션 안에서 Shift+Tab 으로 순환.

2-2. Codex — 3단계, 세션 내 전환 중심

Read-only → Auto (기본) → Full Access

• Read-only 파일/명령 손 못 댐
• Auto 작업 폴더 내 자동, 외부는 묻기
• Full Access 전 시스템·네트워크 자동

대부분 인터랙티브 세션 안에서 /permissions 로 전환하는 흐름. CLI 플래그로 한 번에 박는 경로가 다른 둘보다 약해요.

2-3. Gemini CLI — 4단계, 플래그 + alias

default → auto_edit → yolo → plan

• default 매번 묻기
• auto_edit 파일 편집 자동 / 셸은 묻기 (= Claude 의 acceptEdits)
• yolo 전부 자동 (= Claude 의 bypassPermissions)
• plan 코드 안 건드림

CLI 띄울 때 --approval-mode yolo 식으로 박는 게 가장 깔끔.

2-4. 같은 개념 매핑

🚨 풀자동 모드(bypassPermissions / Full Access / yolo) 는 호스트 파일·네트워크에 자유롭게 액션이 들어가서 한 번의 실수가 크게 번질 수 있어요. 세 도구 모두 격리된 컨테이너/VM 안에서만 권장합니다.

3. 헤드리스 자동화 비교

CI·스크립트에 끼워넣을 때의 사용감이 가장 갈리는 지점이에요.

3-1. Claude Code — -p + --output-format json

claude -p "/review" --output-format json

/review 같은 슬래시 명령을 -p 안에 그대로 박을 수 있는 게 특징. CI 에서 셀프 리뷰 봇 만들기 편해요.

3-2. Codex — codex exec + --json

codex exec --json "이 PR diff 요약"

전용 서브커맨드(exec)로 분리돼 있어서 의도가 명확해요. --json 한 줄로 깔끔.

3-3. Gemini — -p + -o stream-json

gemini -p "긴 리팩토링" -o stream-json | tee progress.jsonl

stream-json 출력이 두드러져요. 토큰 단위 스트리밍을 라인 단위로 받아서 파이프로 흘리면 진행 상황을 CI 로그에 실시간으로 박을 수 있어요. 셋 중 헤드리스 모드의 깊이가 가장 다듬어진 인상.

3-4. 매칭 매트릭스

4. 세션 이어가기와 체크포인트

작업 도중 끊겼다가 돌아올 때의 사용감 비교.

4-1. Claude Code

claude -c                # 현재 디렉토리 최근 세션
claude -r                # 피커
claude -r "blog"         # 이름 검색

--name 으로 세션에 이름 박아두면 -r "blog" 같이 검색해서 복귀 가능. 세션 명명 이 강점.

4-2. Codex

codex resume             # 피커
codex resume --last      # 최근
codex resume <SESSION_ID>

이름 검색이 별도로 없고 ID 기반. 단, codex cloud 와 결합되면 클라우드 세션도 같은 결로 이어가기 가능해서 멀리 떨어진 환경 간 연속성에서 강해요.

4-3. Gemini CLI

gemini -r                                 # 최근
gemini -r 1                               # 인덱스
gemini -r <UUID>                          # UUID
gemini --list-sessions
gemini --delete-session 2

세션 삭제·목록 같은 관리 명령이 CLI 1급 시민이라는 게 특징. 거기에 세션 안에서 /resume save <이름> 으로 체크포인트 를 박을 수 있어서 한 세션 안에서 가지치기가 깔끔해요.

4-4. 매칭

5. 컨텍스트 파일 — CLAUDE.md / AGENTS.md / GEMINI.md

각 도구가 저장소를 처음 열 때 자동으로 읽는 컨텍스트 파일이에요. 이름만 다를 뿐 역할은 거의 같아요.

같은 저장소에서 셋을 다 굴리고 싶다면 보통 두 가지 패턴이 있어요.

1. 세 파일 모두 같은 내용으로 유지 — 가장 단순. 한쪽 수정하면 나머지에 복붙. 작은 저장소에서 OK.
2. 한 파일을 마스터로 두고 나머지는 심볼릭 링크 — 예: CLAUDE.md 를 마스터로 하고 AGENTS.md, GEMINI.md 는 ln -s CLAUDE.md ... 로 링크. 한 곳만 고치면 셋 다 반영.

# 마스터 = CLAUDE.md 전략
ln -sf CLAUDE.md AGENTS.md
ln -sf CLAUDE.md GEMINI.md

💡 단, 도구별로 다른 규칙이 있다면 심볼릭 링크는 깨져요. 그땐 공통부와 도구별 추가분을 섹션으로 나눠두고 각 파일에서 필요한 섹션만 포함하는 식이 안전합니다.

6. MCP · 확장 · 스킬 — 외부 도구 통합

세 도구 모두 외부 도구를 붙이는 통로를 가지고 있는데, 결이 조금씩 달라요.

6-1. Claude Code

• MCP: /mcp 로 관리. 가장 표준에 가까움.
• 서브에이전트: /agents 로 페르소나 등록 (코드 리뷰 전용 등).
• 스킬/플러그인: /skills 로 외부 능력 모듈 호출. 표준화된 인터페이스.

6-2. Codex

• MCP: codex mcp 와 ~/.codex/config.toml 의 [mcp_servers] 섹션.
• 프로필: --profile <name> 으로 모델·MCP·권한 조합을 통째로 묶어서 띄움. 작업 컨텍스트 전환이 한 글자로 끝나는 강점.
• codex cloud 와 결합되면 클라우드 환경 안에서도 같은 도구 셋업 유지.

6-3. Gemini CLI

• MCP: gemini mcp 로 관리.
• 확장(Extensions): gemini extensions 로 더 큰 단위(파일·UI 통합 등) 의 확장 관리. @github 같은 mention 이 여기서 옴.
• 스킬(Skills): gemini skills 로 명시적인 능력 모듈 시스템. 셋 중 가장 모듈화 단위가 세분돼 있어요.

6-4. 매칭

7. 작업 유형별 추천 매트릭스

실제로 도구를 고를 때 가장 도움이 되는 표예요. “지금 하려는 작업” 을 기준으로 어떤 도구가 가장 매끄러운지 정리했어요.

물론 한 도구로 다 할 수 있는 작업이 대부분 이에요. 이 표는 “굳이 고른다면” 의 가이드이고, 실제 작업에선 본인이 손에 익은 도구를 그대로 쓰는 게 가장 빠릅니다.

8. 한 줄 결론

• Claude Code: 세션 명명·서브에이전트·플러그인 같은 워크플로우 인프라 가 가장 두텁다. 매일 여러 작업을 동시에 굴리는 사람에게 어울려요.
• Codex: 프로필 과 클라우드 통합 이 강점. 작업 컨텍스트 전환·원격 위임이 잦은 사람에게.
• Gemini CLI: 헤드리스 자동화 와 확장 mention 이 정돈됨. CI·스크립트 자동화 비중이 큰 사람에게.

셋 다 무료/저렴한 티어로 깔아볼 수 있으니, 이 표를 가이드 삼아 본인 워크플로우에서 한 번씩 굴려보고 손에 가장 잘 붙는 걸 메인으로 잡는 걸 추천드려요. 저는 작업 종류에 따라 셋을 번갈아 쓰고 있는데, 이 시리즈를 정리하면서 “어떤 작업엔 어떤 도구가 더 빠른지” 가 머릿속에서 한층 정리됐어요.

일단 오늘은 여기까지…..
다음 글에서는 시리즈 후속으로 CLAUDE.md / AGENTS.md / GEMINI.md 한 파일로 통합 관리하는 패턴 을 더 자세히 정리해볼게요.

← 이전 글: (3/4) Gemini CLI 자주 쓰는 명령어 모음 — 헤드리스 모드와 슬래시 명령어까지

🛠️ AI 코딩 CLI 명령어 모음 시리즈 (전체 4편)

1. Claude Code 자주 쓰는 명령어 모음 — CLI 플래그부터 슬래시 명령어까지
2. Codex CLI 자주 쓰는 명령어 모음 — 서브커맨드부터 슬래시 명령어까지
3. Gemini CLI 자주 쓰는 명령어 모음 — 헤드리스 모드와 슬래시 명령어까지 ← 지금 글
4. Claude Code · Codex · Gemini CLI 비교 — 권한 모드부터 컨텍스트 파일까지

Summary

1편 Claude Code, 2편 Codex CLI 에 이어 시리즈 마지막 편은 Google Gemini CLI 예요. 셋 다 결은 비슷한데, Gemini 는 --approval-mode 와 --prompt 중심으로 헤드리스(비대화) 자동화 친화적인 색깔이 강해요. 이 글에선 자주 쓰는 CLI 플래그, 서브커맨드, 세션 슬래시 명령어, 그리고 헤드리스 모드 활용 예시까지 한 번에 훑어볼게요.

💡 이 글에서 다루는 것

• Gemini CLI 플래그 (--model, -p, -i, --approval-mode, --sandbox, --worktree, --resume 등)
• 권한 모드(default / auto_edit / yolo / plan)
• 서브커맨드 (gemini mcp, gemini extensions, gemini skills, gemini update)
• 슬래시 명령어 (/help, /quit, /resume, /chat, /memory reload, /mcp reload, /settings, /bug)
• 입력 prefix @ 와 헤드리스 자동화 예시

⚠️ Gemini CLI 도 업데이트 주기가 짧고 공식 docs 가 모듈별로 분산돼 있어요. 본문의 옵션이 안 보이면 gemini --help 와 ~/.gemini/ 설정 디렉토리를 먼저 확인하는 걸 추천드려요.

1. CLI 플래그 — 자주 쓰는 것부터

1-1. --model / -m — 모델 지정

세션 단위로 모델을 지정해요. alias 와 풀네임 둘 다 됩니다.

gemini -m gemini-2.5-flash
gemini --model gemini-2.5-pro

용량 큰 추론은 Pro, 단순 대량 처리는 Flash 로 갈아끼우는 흐름이 일반적이에요.

1-2. --prompt / -p — 헤드리스 (비대화) 실행

Claude Code 의 -p, Codex 의 codex exec 와 같은 결. 결과만 한 번 뱉고 끝나서 스크립트·파이프에서 쓰기 좋아요.

gemini -p "이 디렉토리 구조 한 단락으로 요약해줘"
cat error.log | gemini -p "이 로그가 의미하는 에러는?"

stdin 입력이 있으면 거기에 프롬프트가 자동으로 덧붙어요. 파이프 친화적인 구조에요.

1-3. --prompt-interactive / -i — 한 줄 던지고 대화로 이어가기

-p 와 비슷한데, 결과 뱉고 종료하지 않고 인터랙티브 세션으로 들어가요. “첫 메시지만 미리 박고 시작” 모드.

gemini -i "이 저장소 구조부터 훑어줘"

1-4. --approval-mode — 권한 모드 (핵심)

Gemini 의 권한 모델은 모드 네 가지로 표현돼요.

gemini --approval-mode auto_edit
gemini --approval-mode plan
gemini --approval-mode yolo   # 위험

🚨 yolo 는 격리된 환경에서만 권장합니다. 호스트에 자유롭게 액션이 들어가서 한 번의 실수가 크게 번질 수 있어요. 일회용 컨테이너/VM 안에서만 쓰세요.

💡 옛 버전의 --yolo / -y 플래그는 deprecate 됐어요. 같은 동작은 --approval-mode=yolo 로 표현합니다.

1-5. --sandbox / -s — 샌드박스 실행

도구 호출을 격리된 샌드박스(컨테이너 등) 안에서 돌리는 모드. yolo 와 같이 박으면 안전성 + 자동화 균형이 잡혀요.

gemini -s
gemini -s --approval-mode yolo "이 마이그레이션 한 번에 끝내줘"

1-6. --include-directories — 추가 디렉토리 노출

작업 디렉토리 외에 다른 폴더도 컨텍스트에 같이 노출해요. 쉼표 또는 반복 지정 가능.

gemini --include-directories ../lib,../docs

모노레포에서 인접 패키지 같이 만질 때 자주 씁니다.

1-7. --worktree / -w — git worktree 격리

브랜치를 안 건드리고 별도 worktree 에서 실험할 때.

gemini -w                    # 자동 이름 (worktree-a1b2c3d4 같은 식)
gemini --worktree feature-x  # 이름 지정 시 디렉토리·브랜치 이름 동일

Claude Code 의 -w 와 동일한 결.

1-8. --resume / -r — 이전 세션 이어가기

이전 세션을 다시 열어요. 여러 방식 지원.

gemini --resume                                           # 가장 최근 세션
gemini --resume 1                                         # 인덱스로 지정
gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890      # UUID 로 지정

세션 목록·삭제도 같은 결로:

gemini --list-sessions
gemini --delete-session 2

1-9. --output-format / -o — 출력 포맷

-p 와 같이 쓸 때 결과 포맷을 바꿔요. 후처리 파이프라인에 끼워넣기 편함.

gemini -p "이 PR diff 요약" -o json
gemini -p "긴 작업 시작" -o stream-json

stream-json 은 결과를 토큰 단위로 스트리밍해서 실시간 진행 상황을 잡아낼 수 있어요.

1-10. --debug / -d — 디버그 모드

내부 호출·도구 실행 로그를 자세히 찍어요. 동작이 이상할 때 한 번씩 켭니다.

gemini -d

1-11. --extensions / -e — 확장만 골라 활성

설치된 확장 중 일부만 켜고 싶을 때.

gemini -e github,linear

2. 서브커맨드

gemini 뒤에 붙는 모드들. 자주 쓰는 것만 정리할게요.

gemini mcp           # MCP 서버 설정/관리
gemini extensions    # 확장 관리
gemini skills        # 스킬 관리 (등록/조회/리로드)
gemini update        # 최신 버전으로 업데이트

MCP·extension·skill 모두 외부 도구·기능을 Gemini 에 붙이는 통로에요. 새 도구 붙일 때 가장 먼저 손이 가는 명령들.

3. 세션 안 슬래시 명령어

세션에서 / 로 시작하는 명령어들. 다른 두 CLI 보다 더 모듈화돼 있어서 “리로드” 류 명령이 카테고리별로 따로 있어요.

3-1. /help / /quit

기본 중의 기본. 도움말 보기, 세션 종료.

/help
/quit

3-2. /memory reload — 컨텍스트 파일 리로드

GEMINI.md 같은 컨텍스트 파일을 세션 도중 다시 읽어와요. 파일 수정하고 바로 반영하고 싶을 때.

/memory reload

3-3. /mcp reload — MCP 서버 재시작

MCP 서버 설정을 바꿨거나 죽었을 때 한 번 리로드.

/mcp reload

3-4. /extensions reload / /skills reload / /agents reload / /commands reload

같은 결의 리로드 명령들. 확장, 스킬, 에이전트, 커스텀 슬래시 명령을 각각 따로 다시 불러옵니다.

/extensions reload
/skills reload
/agents reload
/commands reload

저는 새 확장이나 커스텀 명령 만들면서 테스트할 때 이 네 개를 자주 두드립니다.

3-5. /resume / /chat — 세션 브라우저와 체크포인트

/resume 은 세션 브라우저 UI 를 띄워서 이전 세션을 고르거나, 현재 세션에 이름 붙은 체크포인트를 만들어요.

/resume                          # 세션 브라우저
/resume save decision-point      # 현재 시점에 체크포인트 저장
/resume list                     # 체크포인트 목록
/resume resume decision-point    # 특정 체크포인트로 복귀

/chat 은 /resume 의 호환 alias 에요. 작업 중간에 “여기서 가지치기 한 번 해볼까” 싶을 때 save 로 체크포인트 박아두는 흐름이 정말 편합니다.

3-6. /settings — 세션 설정

세션 정책(권한·도구·로깅 등) 을 인터랙티브하게 바꿔요.

/settings

3-7. /bug — 이슈 리포트

문제 만났을 때 그 자리에서 이슈 리포트 양식을 띄워줘요.

/bug

4. 입력창 prefix — @

Gemini 의 입력 prefix 는 @ 이 가장 두드러져요. 단순 파일 참조가 아니라 확장 기반 mention 으로 동작해서, 확장(@github, @linear 등) 을 통한 외부 자원 참조가 자연스러워요.

@github 내 열린 PR 목록 보여줘
@src/api/handlers.py 이 파일 리팩토링 해줘

💡 Claude Code 의 ! (쉘) / # (메모리) 같은 prefix 는 Gemini CLI 공식 레퍼런스에서 명시적으로 잡혀있진 않아요. 같은 결의 기능은 권한 모드(auto_edit, yolo) 와 컨텍스트 파일(GEMINI.md) + /memory reload 조합으로 풀어요.

5. 헤드리스 자동화 예시 (Gemini 만의 색깔)

Gemini CLI 가 다른 두 CLI 대비 두드러지는 건 헤드리스 모드 의 깔끔함이에요. -p + --output-format json 조합으로 스크립트·CI 에 끼워넣기 쉬워요.

5-1. JSON 출력으로 후처리

gemini -p "이 저장소 라이선스 한 줄 요약" -o json > out.json
jq '.text' out.json

5-2. 스트리밍 결과 받기

gemini -p "긴 리팩토링 작업 시작" -o stream-json | tee progress.jsonl

stream-json 으로 받으면 진행 상황을 라인 단위로 받을 수 있어서 CI 로그에 그대로 흘릴 수 있어요.

5-3. 안전 모드로 첫 훑기

gemini -i "이 저장소 구조 한 단락으로 요약" --approval-mode plan

plan 모드는 코드를 절대 안 건드리고 계획만 세워줘서, 처음 보는 저장소 훑을 때 부담 없이 시작 가능.

5-4. 격리된 컨테이너에서 풀자동

gemini -s --approval-mode yolo "이 마이그레이션 끝까지 진행해줘"

-s 로 샌드박스 켜고 yolo 로 묻지 않는 자동 실행. 호스트는 안전, 작업은 끝까지.

5-5. 모노레포 멀티 디렉토리

gemini --include-directories ../shared,../types -w mono-experiment

인접 디렉토리 노출 + 새 worktree 까지 한 줄로.

6. 세 CLI 비교 한 줄 정리

시리즈 마지막인 만큼, 세 CLI 의 비슷한 결과 다른 결을 한 표로 정리할게요.

큰 그림은 정말 비슷한데, 모드 이름과 컨텍스트 파일명이 각자 다르다는 게 가장 헷갈리는 지점이에요. 셋 다 쓰다 보면 머릿속에 자연스럽게 매핑이 잡혀요.

마무리

여기까지 Gemini CLI 의 플래그·서브커맨드·슬래시 명령어·prefix 를 훑고, 시리즈 마무리로 세 CLI 의 비교 표까지 같이 정리해봤어요.

• 자주 쓰는 플래그: -m, -p, -i, --approval-mode, -s, -w, -r, --include-directories, -o
• 권한 모드: default / auto_edit / yolo / plan — --approval-mode 로 지정
• 서브커맨드: gemini mcp, extensions, skills, update
• 슬래시 명령: /help, /quit, /resume, /chat, /memory reload, /mcp reload, /extensions reload, /skills reload, /agents reload, /commands reload, /settings, /bug
• 입력 prefix: @ (확장 기반 mention)
• 시그니처: -p + -o stream-json 조합의 깔끔한 헤드리스 모드

셋 다 익혀두면 작업 성격에 맞는 도구를 골라서 띄울 수 있고, 모드/플래그가 헷갈릴 때마다 이 표만 한 번 보면 됩니다.

일단 오늘은 여기까지…..
다음 글에서는 시리즈 마무리로 세 CLI 를 권한 모드·헤드리스·세션 이어가기·컨텍스트 파일·MCP 축으로 깊게 비교해볼게요.

← 이전 글: (2/4) Codex CLI 자주 쓰는 명령어 모음 — 서브커맨드부터 슬래시 명령어까지 ｜ 다음 글 → (4/4) Claude Code · Codex · Gemini CLI 비교 — 권한 모드부터 컨텍스트 파일까지

🛠️ AI 코딩 CLI 명령어 모음 시리즈 (전체 4편)

1. Claude Code 자주 쓰는 명령어 모음 — CLI 플래그부터 슬래시 명령어까지
2. Codex CLI 자주 쓰는 명령어 모음 — 서브커맨드부터 슬래시 명령어까지 ← 지금 글
3. Gemini CLI 자주 쓰는 명령어 모음 — 헤드리스 모드와 슬래시 명령어까지
4. Claude Code · Codex · Gemini CLI 비교 — 권한 모드부터 컨텍스트 파일까지

Summary

1편 에서 Claude Code 의 CLI 플래그와 슬래시 명령어를 정리했는데, OpenAI 의 Codex CLI 도 비슷한 결로 자주 굴리고 있어서 같이 정리해두면 좋을 것 같았어요. Codex 는 Claude Code 와 닮은 점이 많지만 서브커맨드 구조, 권한 모드 이름, 슬래시 명령어 라인업이 미묘하게 달라서 한 번에 비교해두면 헷갈리지 않아요. 이 글에서는 자주 쓰는 서브커맨드, CLI 플래그, 세션 슬래시 명령어, 입력 prefix(!, @), 단축키까지 한 번에 훑어볼게요.

💡 이 글에서 다루는 것

• Codex CLI 서브커맨드 (exec, resume, cloud, mcp, features, completion)
• 자주 쓰는 CLI 플래그 (--model, -i, --cd, --add-dir, --profile, --search, --json)
• 세션 안 슬래시 명령어 (/model, /review, /permissions, /status, /clear, /copy, /theme)
• 입력창 단축 prefix — ! 쉘 실행, @ 파일 참조
• 권한 모드(Auto / Read-only / Full Access) 와 자주 쓰는 조합 예시

⚠️ Codex CLI 는 업데이트 주기가 짧아서 옵션 이름·기본값이 자주 바뀌어요. 본문의 옵션이 안 보이면 codex --help 로 한 번 확인하는 걸 추천드려요.

1. 서브커맨드 — codex 뒤에 붙는 모드들

Codex 는 같은 바이너리 안에 모드가 여러 개 들어있어요. 가장 손이 자주 가는 것부터 정리할게요.

1-1. codex — 인터랙티브 TUI

아무것도 안 붙이면 대화형 터미널 UI 가 떠요. 가장 기본 모드.

codex
codex "이 저장소 구조 한 줄로 요약해줘"

뒤에 프롬프트를 바로 박으면 그 메시지로 세션이 시작됩니다.

1-2. codex exec — 비대화 실행 (파이프 친화)

Claude Code 의 -p 와 같은 결이에요. 결과만 한 번 뱉고 끝나서 스크립트나 파이프에서 쓰기 좋아요.

codex exec "CI 실패 원인 찾아서 패치 만들어줘"
codex exec --json "이 디렉토리에서 TODO 갯수만 세줘"

--json 까지 같이 박으면 후처리 파이프라인에 끼워넣기 편합니다.

1-3. codex resume — 이전 세션 이어가기

작업 중이던 세션을 다시 열어요. 옵션 세 가지가 있는데 손에 익는 순서대로:

codex resume               # 최근 세션 피커
codex resume --last        # 가장 최근 세션으로 바로
codex resume <SESSION_ID>  # 특정 세션 지정

저는 --last 가 압도적으로 많아요. 잠깐 터미널 닫고 돌아올 때 한 줄로 복귀 가능.

1-4. codex cloud — 클라우드 작업 관리

로컬이 아니라 OpenAI 가 호스팅하는 환경에서 코덱스를 돌리는 모드. 사양 큰 환경/긴 작업 돌릴 때 유용해요.

codex cloud exec --env ENV_ID "오픈된 버그 요약"
codex cloud exec --env ENV_ID --attempts 3 "리팩토링 PR 만들어줘"

--attempts 1~4 로 best-of-N 실행을 요청하면 같은 작업을 여러 번 돌리고 가장 좋은 결과를 골라요.

1-5. codex mcp — MCP 서버 관리

MCP(Model Context Protocol) 서버를 코덱스에 붙이고 떼는 명령. Notion, Linear, Gmail 같은 외부 도구를 코덱스가 직접 쓰게 해주는 통로에요.

codex mcp

1-6. codex features — 피처 플래그

베타·실험 기능을 켜고 끄는 토글. 새 기능이 나왔는데 안 보일 때 한 번씩 들여다봅니다.

codex features list
codex features enable <feature>
codex features disable <feature>

1-7. codex completion — 쉘 자동완성

서브커맨드/플래그 자동완성을 셸에 박아주는 스크립트 생성기.

codex completion zsh > ~/.zsh/completions/_codex
codex completion bash > ~/.local/share/bash-completion/completions/codex

한 번만 설정해두면 codex --<TAB> 으로 옵션 다 뜨니까 처음 설치하면 무조건 박아두는 걸 추천드려요.

2. CLI 플래그 — 세션 동작 바꾸기

서브커맨드와 같이 쓸 수 있는 플래그들이에요.

2-1. --model — 모델 지정

세션 단위로 모델을 지정해요. 기본값은 코덱스 추천 모델인데, 특정 작업에서는 갈아끼우는 게 나아요.

codex --model gpt-5.5
codex exec --model gpt-5.5 "단순 포맷팅 작업"

💡 사용 가능한 모델 alias 는 codex --help 또는 ~/.codex/config.toml 의 프로필 설정으로 확인할 수 있어요. 버전마다 이름이 바뀌니까 직접 확인하는 게 정확합니다.

세션 도중에는 /model 슬래시 명령으로 바꿀 수 있어요.

2-2. -i, --image — 이미지 첨부

스크린샷이나 디자인 시안을 코덱스에게 같이 보여줘요. 에러 화면 디버깅, UI 컴포넌트 만들 때 정말 유용.

codex -i screenshot.png "이 에러 화면 의미하는 게 뭐야?"
codex -i mockup.png,style.png "이 디자인대로 React 컴포넌트 만들어줘"

쉼표로 여러 이미지 한 번에 첨부 가능해요.

2-3. --cd — 작업 디렉토리 변경

cd 안 치고 코덱스에게 작업 디렉토리만 알려줘요.

codex --cd /path/to/project "여기서 시작해줘"

2-4. --add-dir — 추가 디렉토리 노출

현재 디렉토리 외에 다른 폴더도 코덱스가 읽고 쓸 수 있게 해줘요.

codex --add-dir ../backend --add-dir ../shared

모노레포에서 인접 패키지 같이 만질 때 자주 씁니다.

2-5. --profile — 설정 프로필 적용

$CODEX_HOME/<profile>.config.toml 에 미리 박아둔 설정 묶음을 한 번에 적용해요.

codex --profile work
codex --profile sandbox-only

프로젝트별로 모델·권한·MCP 서버 조합이 달라질 때 프로필을 미리 만들어 두면 띄울 때 한 글자로 끝납니다.

2-6. --search — 실시간 웹 검색

기본은 캐시 결과를 쓰는데, 최신 정보가 필요할 때 이걸 박으면 실시간 검색을 같이 돌려요.

codex --search "Node.js 24 의 최신 변경사항 정리해줘"

2-7. --json — JSON 출력

exec 와 같이 쓰면 결과를 구조화된 JSON 으로 받을 수 있어요. 후처리 스크립트에서 파싱하기 편함.

codex exec --json "이 PR diff 요약" > review.json

3. 권한 모드 — Auto / Read-only / Full Access

코덱스의 권한 모델은 세 단계예요. 세션 안에서 /permissions 로 바꿀 수 있어요.

Auto 가 일상 작업에서 가장 균형 좋은 기본값이에요. Read-only 는 처음 보는 저장소 훑어볼 때, Full Access 는 일회용 샌드박스에서만.

4. 세션 안 슬래시 명령어

세션에서 / 로 시작하는 명령어들. / 만 쳐도 자동완성이 떠요.

4-1. /model — 모델 바꾸기

/model gpt-5.5

4-2. /permissions — 권한 모드 전환

위의 Read-only / Auto / Full Access 사이를 세션 도중 바꾸는 명령. 처음 훑을 땐 Read-only 로 두다가, 본격적으로 패치 만들기 시작하면 Auto 로 올리는 흐름.

/permissions

4-3. /review — 코드 리뷰 프리셋

베이스 브랜치 대비 diff, 워킹트리 미커밋, 특정 커밋, 커스텀 지시 중에서 골라서 리뷰를 받을 수 있어요.

/review

4-4. /status — 세션 상태

현재 모델, 권한 모드, 작업 디렉토리, MCP 서버 등을 한 페이지로 보여줘요.

/status

4-5. /clear — 화면+컨텍스트 초기화

지금까지의 대화를 통째로 비우고 새로 시작.

/clear

4-6. /copy — 마지막 출력 복사

마지막 코덱스 응답을 클립보드로. 셸 명령 결과 그대로 옮길 때 편해요.

/copy

4-7. /theme — TUI 테마 변경

테마 미리보기 + 저장. 선택값은 ~/.codex/config.toml 에 박힙니다.

/theme

4-8. /exit — 세션 종료

/exit

5. 입력창 단축 prefix — !, @

Claude Code 와 거의 똑같은 결인데 한 가지가 빠져 있어요.

5-1. ! — 쉘 명령어 즉시 실행

입력 첫 글자가 ! 면 그 줄을 쉘로 실행하고 결과가 대화에 들어와요.

!ls -la
!git status

5-2. @ — 파일 퍼지 검색 / 참조

@ 를 치면 워크스페이스 안에서 파일 자동완성이 떠요. Tab 또는 Enter 로 경로 박힘.

이 두 파일 비교해줘 @src/handlers.py @src/legacy_handlers.py

💡 Claude Code 의 # (메모리 추가) 같은 prefix 는 코덱스에는 없어요. 메모리/장기 컨텍스트는 AGENTS.md 와 ~/.codex/config.toml 로 관리합니다.

6. 단축키

저는 Ctrl + G 가 진짜 편해요. 멀티라인 긴 지시 칠 때 vim 으로 바로 열려서 편집 쾌적합니다 ($EDITOR 가 잡혀 있어야 동작).

7. 실제로 쓰는 조합 예시

7-1. 처음 보는 저장소 훑기 (안전 모드)

codex --cd /path/to/unknown-repo
# 세션 안에서:
/permissions   # Read-only 로 전환
"이 저장소 구조 한 단락으로 요약해줘"

권한을 Read-only 로 내려두면 코덱스가 절대 파일/명령을 건드릴 수 없어서 위험 없이 구조 파악만 가능해요.

7-2. PR 셀프 리뷰

codex
/review

베이스 브랜치 기준 diff 리뷰를 한 번 받고 보내는 흐름. CI 에 넣고 싶으면 codex exec --json "/review" 식으로도 가능.

7-3. 멀티 디렉토리 모노레포 작업

codex --cd packages/api --add-dir ../shared --add-dir ../types --profile mono

작업 폴더를 api 로 두고 shared, types 까지 읽기·쓰기 허용. --profile mono 로 모노레포 전용 설정(모델·MCP 등) 한 번에 적용.

7-4. 일회용 컨테이너에서 풀자동

docker run -it --rm -v $PWD:/work codex-sandbox codex
# 세션 안에서:
/permissions   # Full Access 로 전환
"이 마이그레이션 끝까지 진행해줘"

격리 컨테이너 안에서 권한을 Full Access 로 올리면 묻지 않고 끝까지 자동 진행. 호스트는 안전.

🚨 Full Access 는 호스트 파일·네트워크에 자유롭게 접근할 수 있는 상태예요. 한 번의 실수가 크게 번질 수 있어서 일회용 컨테이너/VM/원격 격리 환경 안에서만 쓰는 걸 추천드립니다.

마무리

여기까지 코덱스 CLI 의 서브커맨드·플래그·슬래시 명령어·prefix·단축키를 한 번에 훑었어요. 정리하면 이렇게 기억해두면 좋아요.

• 서브커맨드: codex, codex exec, codex resume --last, codex cloud, codex mcp
• 자주 쓰는 플래그: --model, -i, --cd, --add-dir, --profile, --search, --json
• 권한 모드: Read-only / Auto / Full Access — /permissions 로 전환
• 슬래시 명령: /model, /review, /status, /clear, /copy, /theme, /permissions, /exit
• 입력 prefix: ! (쉘), @ (파일 퍼지 검색)
• 단축키: Tab(큐잉), Ctrl+G(외부 에디터), Esc Esc(이전 메시지 편집)

Claude Code 자주 쓰는 명령어 모음 글과 같이 두고 비교해보면 두 도구가 얼마나 닮았고 얼마나 다른지 한눈에 들어와요. 큰 그림은 비슷한데 권한 모델 이름(auto vs Auto/acceptEdits), prefix 종류(# 없음), 워크트리 통합(코덱스는 -w 없음, 대신 --cd + 외부 worktree) 정도가 갈리는 포인트.

일단 오늘은 여기까지…..
다음 글에서는 시리즈 마지막 편으로 Google Gemini CLI 의 플래그·슬래시 명령어를 같은 결로 정리하고, 세 CLI 를 한 표로 비교해볼게요.

← 이전 글: (1/4) Claude Code 자주 쓰는 명령어 모음 — CLI 플래그부터 슬래시 명령어까지 ｜ 다음 글 → (3/4) Gemini CLI 자주 쓰는 명령어 모음 — 헤드리스 모드와 슬래시 명령어까지

🛠️ AI 코딩 CLI 명령어 모음 시리즈 (전체 4편)

1. Claude Code 자주 쓰는 명령어 모음 — CLI 플래그부터 슬래시 명령어까지 ← 지금 글
2. Codex CLI 자주 쓰는 명령어 모음 — 서브커맨드부터 슬래시 명령어까지
3. Gemini CLI 자주 쓰는 명령어 모음 — 헤드리스 모드와 슬래시 명령어까지
4. Claude Code · Codex · Gemini CLI 비교 — 권한 모드부터 컨텍스트 파일까지

Summary

저는 작업 종류별로 claude --enable-auto-mode --name "infra" 같은 식으로 Claude Code 세션을 따로따로 띄워서 굴려요. 익숙해지면 정말 편해지는데, 처음에는 “이 옵션들이 다 뭐 하는 거지?” 싶을 거예요. 이 글에서는 제가 매일 쓰는 CLI 플래그, 세션 안에서 쓰는 슬래시 명령어, 그리고 입력창의 단축 prefix(!, #, @)까지 한 번에 정리해볼게요.

💡 이 글에서 다루는 것

• Claude Code 를 띄울 때 자주 쓰는 CLI 플래그 (--name, --permission-mode, -c, -r, -p, -w 등)
• 세션 안에서 자주 두드리는 슬래시 명령어 (/clear, /compact, /model, /agents, /mcp 등)
• 입력창의 단축 prefix — ! 쉘 실행, # 메모리 추가, @ 파일 참조
• 제가 실제로 쓰는 조합 예시 (일상 모드, 리뷰 모드, 워크트리 격리 등)

이 글의 기준 버전은 claude --version 기준 2.1.158 이에요. 버전이 올라가면 옵션이 추가/이름 변경될 수 있어서 claude --help 로 한 번 확인하는 걸 추천드려요.

1. 세션 띄우기 — CLI 플래그

가장 많이 쓰는 옵션부터 정리할게요. 셸에서 claude 뒤에 붙이면 그 세션 동안만 적용돼요.

1-1. --name / -n — 세션에 이름 붙이기

세션을 여러 개 띄울 때 가장 먼저 손이 가는 옵션이에요. 이름을 박아두면 프롬프트 박스, /resume 피커, 터미널 타이틀에 다 같이 노출돼서 “어떤 작업하던 창이지?” 헷갈리지 않아요.

claude --name "infra"
claude -n "review"

저는 작업 종류별로 동시에 두세 개 띄우는 일이 많아서 거의 항상 박습니다.

1-2. --permission-mode — 권한 모드 고르기

Claude 가 파일 수정·셸 실행 같은 액션을 할 때 매번 물어볼지, 알아서 진행할지 정하는 옵션이에요. 모드는 다섯 가지가 있어요.

claude --permission-mode auto
claude --permission-mode plan

--enable-auto-mode 같은 단축 플래그도 같이 쓸 수 있어요 (제가 글 상단에 적은 예시처럼). 결과적으로는 --permission-mode auto 와 같은 효과예요.

⚠️ bypassPermissions 와 --dangerously-skip-permissions 는 진짜 위험할 때 — 격리된 샌드박스/인터넷 차단 환경에서만 권장합니다. 일반 작업에는 쓰지 마세요.

1-3. -c, --continue / -r, --resume — 이전 세션 이어가기

작업하다가 터미널을 닫아도 세션은 디스크에 남아 있어요. 다시 켜고 싶을 때 두 가지 옵션이 있어요.

claude -c                       # 현재 디렉토리의 가장 최근 세션 그대로 이어가기
claude -r                       # 세션 피커 띄워서 고르기
claude -r "blog"                # 이름/검색어로 필터링해서 피커 띄우기

-c 가 정말 자주 손이 가요. 잠깐 다른 터미널로 빠졌다 돌아올 때 한 글자로 복귀 가능.

1-4. --model — 모델 바꿔서 띄우기

세션 단위로 모델을 지정하는 옵션이에요. alias(sonnet, opus, haiku) 또는 풀네임 둘 다 됩니다.

claude --model opus
claude --model sonnet
claude --model claude-opus-4-7

저는 기본은 Opus 로 띄우고, 양이 많은 단순 변환 작업에만 Sonnet 으로 띄워요. 세션 도중에 바꾸고 싶으면 안에서 /model 슬래시 명령으로도 됩니다.

1-5. -p, --print — 비대화 모드 (파이프 친화적)

인터랙티브 세션 대신 결과만 한 번 뱉고 끝나는 모드. 셸 파이프나 스크립트에서 쓰기 좋아요.

claude -p "이 파일에서 TODO 가 몇 개 있나?" < src/main.py
echo "log line" | claude -p "이 로그가 의미하는 에러는?"

--output-format json 과 같이 쓰면 결과를 JSON 으로 받을 수 있어서 후처리 파이프라인에 끼워넣기도 좋습니다.

claude -p "한 줄 요약해줘" --output-format json < README.md

1-6. -w, --worktree — git worktree 로 격리해서 띄우기

작업 중인 브랜치를 건드리지 않고 별도 worktree 에서 실험할 때 한 줄로 만들어 줘요.

claude -w feature-x
claude -w experiment-mig --tmux

--tmux 까지 같이 박으면 tmux 세션을 자동으로 만들어 줘서 (iTerm2 면 네이티브 페인) 분리 작업이 정말 편해져요.

1-7. --add-dir — 작업 디렉토리 추가하기

기본 동작은 현재 디렉토리만 도구로 접근 가능한데, 인접한 디렉토리도 같이 열어두고 싶을 때 씁니다.

claude --add-dir ../shared-lib ../other-repo

저는 모노레포 한쪽에서 작업하면서 옆 폴더의 노트를 같이 참조해야 할 때 자주 씁니다.

1-8. --allowedTools / --disallowedTools — 도구 화이트/블랙리스트

세션 단위로 어떤 도구를 쓸지/막을지 명시적으로 지정해요. CI 나 스크립트에서 안전하게 돌릴 때 좋아요.

# 읽기만 허용
claude -p "이 코드 베이스 구조 한 줄 요약" \
  --allowedTools "Read,Grep,Glob"

# Bash 는 git 명령만 허용
claude --allowedTools "Bash(git *) Edit Read"

# 절대 쉘은 못 쓰게
claude --disallowedTools "Bash"

2. 세션 안에서 — 슬래시 명령어

세션 안에서 / 로 시작하는 명령어들이에요. 입력창에서 / 만 쳐도 자동완성 목록이 떠요. 손에 익는 순서대로 정리해볼게요.

2-1. /clear — 컨텍스트 비우기

지금까지의 대화를 통째로 비우고 새로 시작해요. 작업이 바뀌었을 때 컨텍스트 오염 막으려고 자주 누릅니다.

/clear

저는 한 세션 안에서 “이제 다른 글 쓸게” 라고 주제가 바뀌면 무조건 한 번 비워요. 안 그러면 직전 글의 톤/소재가 새 글에 묻어 나와요.

2-2. /compact — 컨텍스트 압축

/clear 처럼 완전히 비우지는 않고, 지금까지의 대화를 요약본으로 압축해서 계속 이어가요. “조금 길었지만 여기까지의 흐름은 살리고 싶을 때” 쓰는 절충안.

/compact
/compact 핵심 결정사항만 남기고 나머지는 정리해줘

뒤에 지시를 붙이면 어떤 관점으로 압축할지도 가이드 할 수 있어요.

2-3. /model — 모델 바꾸기

세션 도중에 모델 갈아끼울 때. 토큰 많이 쓰는 작업이면 Opus, 단순 반복이면 Sonnet 으로 자주 옮겨 다닙니다.

/model sonnet
/model opus

2-4. /init — 프로젝트에 CLAUDE.md 만들기

새 저장소에서 처음 Claude Code 돌릴 때 한 번 치면, 코드베이스를 훑어보고 CLAUDE.md 초안을 만들어줘요. 이 파일은 이후 모든 세션의 컨텍스트로 자동 주입돼서 정말 강력해요.

/init

저는 새 저장소 받을 때 거의 반사적으로 한 번 돌리고, 만들어진 CLAUDE.md 를 손으로 다듬어서 쓰는 패턴이에요.

2-5. /cost — 토큰/달러 비용 보기

이번 세션에서 토큰 얼마 썼고 달러로 얼마나 됐는지 보여줘요. Opus 로 길게 작업할 때 한 번씩 확인합니다.

/cost

2-6. /status — 세션 상태 한눈에

지금 어떤 모델, 어떤 권한 모드, 어떤 디렉토리, 어떤 MCP 서버 붙어있는지 한 페이지로 보여줘요.

/status

2-7. /agents — 커스텀 서브에이전트 관리

특정 작업 전용 서브에이전트를 만들거나 관리하는 명령. “코드 리뷰 전용”, “테스트 작성 전용” 같은 식으로 페르소나를 따로 등록해두면 메인 컨텍스트 안 더럽히면서 위임이 가능해요.

/agents

2-8. /mcp — MCP 서버 관리

MCP(Model Context Protocol) 서버를 붙이고 떼는 명령. Gmail, Google Drive, Notion, Linear 같은 외부 도구를 Claude 가 직접 쓰게 해주는 통로에요.

/mcp

2-9. /review — 현재 diff 코드 리뷰

브랜치에 쌓인 변경분에 대해 한 번 훑어주는 리뷰 명령. PR 올리기 직전에 셀프 리뷰용으로 자주 씁니다.

/review

2-10. /help — 단축키/명령어 도움말

까먹은 명령어/단축키를 빠르게 확인. / 자동완성도 좋지만 이쪽이 더 친절해요.

/help

3. 입력창 단축 prefix — !, #, @

슬래시 명령어보다 더 가볍게 한 글자로 동작이 바뀌는 prefix 들이 있어요. 이게 진짜 손에 익으면 생산성이 다릅니다.

3-1. ! — 쉘 명령어 즉시 실행

입력 첫 글자가 ! 면 그 줄을 쉘로 실행해요. 결과가 대화 안에 그대로 들어와서 Claude 가 바로 다음 턴부터 활용할 수 있어요.

! ls -la src/ | tail -10
! git status
! gcloud auth login

특히 인터랙티브 로그인(gcloud auth login, aws sso login)처럼 Claude 가 직접 못 돌리는 명령을 사용자가 직접 쳐야 할 때 이 prefix 가 답이에요.

3-2. # — 메모리에 추가

입력 첫 글자가 # 이면 그 내용이 메모리(또는 CLAUDE.md)에 저장돼요. 다음 세션부터도 계속 기억해주길 바라는 사실/규칙을 한 줄로 던질 수 있어요.

# 이 프로젝트에서 PR 만들 때는 영어 제목 + 한국어 본문으로 작성
# 빌드는 ./run.sh 로만 띄울 것 (bundle exec jekyll serve 직접 호출 X)

저는 같은 안내를 두 번 반복하게 됐다 싶으면 그 순간 # 으로 박아넣어요.

3-3. @ — 파일/디렉토리 참조

입력 도중에 @ 를 치면 파일 자동완성이 떠요. 선택하면 그 파일이 컨텍스트로 첨부돼요.

이 두 파일 비교해줘 @src/api/handlers.py @src/api/legacy_handlers.py

긴 경로를 손으로 안 쳐도 돼서 진짜 편해요.

4. 단축키 몇 가지

키보드만으로 자주 쓰는 단축키들도 같이 정리할게요.

특히 Esc Esc 는 응답이 마음에 안 들 때 메시지 자체를 고쳐서 다시 보낼 수 있어서 정말 자주 씁니다.

5. 실제로 쓰는 조합 예시

플래그들을 어떻게 조합해서 쓰는지 제 워크플로우 몇 개를 옮겨볼게요.

5-1. 일상 작업 모드

claude --enable-auto-mode --name "daily"

--name 으로 어떤 창인지 명확히 하고, auto 모드로 띄워서 자잘한 파일 편집은 자동 진행. 매일 켜는 기본 조합이에요.

5-2. PR 올리기 직전 셀프 리뷰

claude --name "review" -p "/review"

대화형으로 안 가도 되니까 -p 로 한 방에 리뷰만 받고 끝. CI 에 넣으면 자동 PR 리뷰 봇처럼도 쓸 수 있어요.

5-3. 위험한 실험은 worktree 에 격리

claude -w mig-experiment --tmux --name "mig"

브랜치 일은 별도 worktree 로 빼고, tmux 페인까지 자동으로 분리. 메인 작업 환경 안 망가지면서 실험 가능.

5-4. 읽기만 시키는 안전 모드

claude -p "이 저장소 구조 한 단락으로 요약해줘" \
  --allowedTools "Read,Grep,Glob" \
  --model sonnet

Bash / Edit 를 빼고 읽기 도구만 허용. 모델도 Sonnet 으로 내려서 비용도 절약. 처음 보는 저장소 훑을 때 이 조합을 자주 씁니다.

마무리

여기까지 자주 쓰는 CLI 플래그, 슬래시 명령어, 입력 prefix, 단축키를 한 번에 훑었어요. 정리하면 이런 흐름이에요.

• 세션을 띄울 때: --name, --permission-mode, -c, -r, --model, -w
• 세션 안에서: /clear, /compact, /model, /status, /cost, /agents, /mcp, /review
• 입력창 prefix: ! (쉘), # (메모리), @ (파일)
• 단축키: Shift+Tab, Esc Esc, Ctrl+R

전부 외울 필요는 없고, 본인 워크플로우에 자주 등장하는 두세 개부터 손에 익히는 걸 추천드려요. 저는 처음에 --name 하나만 박아 쓰다가, /clear 와 # 두 개를 추가로 익히면서 작업 속도가 눈에 띄게 빨라졌어요.

일단 오늘은 여기까지…..
다음 글에서는 같은 결로 OpenAI Codex CLI 의 서브커맨드와 슬래시 명령어를 정리해볼게요.

다음 글 → (2/4) Codex CLI 자주 쓰는 명령어 모음 — 서브커맨드부터 슬래시 명령어까지

📚 MSSQL → AWS RDS 마이그레이션 시리즈 (전체 5편)

1. 방법 비교 — 6가지 중에서 고르기
2. Native Backup/Restore 실전 — 옵션 그룹부터 컷오버까지
3. DMS + CDC 무중단 컷오버 — 풀로드 후 변경분 따라잡기
4. 변경분 계속 쌓기 — NORECOVERY 체인과 CDC-only 결합
5. 정합성 트러블슈팅 — 케이스별 8가지 함정 ← 지금 글

지난 글에서 풀백업/복원 + DMS CDC-only 결합 패턴을 정리했어요. 흐름 자체는 깔끔한데, 실제로 운영해보면 데이터가 100% 1:1 로 떨어지지 않는 케이스를 자주 만나요. 이번 글은 그 결합 패턴(또는 DMS 단독)에서 실제로 자주 만나는 정합성 문제들 을 케이스별로 정리한 글이에요. 원인 → 증상 → 대응 순서로 풀게요.

💡 이 글에서 다루는 것

• 중복 키 (Duplicate PK) — 풀로드와 CDC 시작 시점 겹침
• NOT NULL / DEFAULT 컬럼 — 풀로드는 OK, CDC 에서 깨지는 케이스
• IDENTITY 시드 어긋남 — 컷오버 후 첫 INSERT 가 PK 충돌
• 외래키 적용 순서 — 풀로드 중/후의 cascade 문제
• Computed column / rowversion — 옮기지 않아야 하는 컬럼
• Collation / 데이터 타입 미스매치 — 비교 결과는 같아 보이는데 정합성 검증에서 다름
• 트리거 fire-on-replication — 적용 측에서 데이터가 두 번 변형
• 검증 체크리스트

1. 큰 그림 — 정합성 문제가 어디서 생기나

DMS 든 백업/복원이든, 데이터가 한 시점에 딱 고정되지 않는 한 정합성 문제는 어디서든 끼어들 수 있어요. 결합 패턴에서 정합성 문제가 잘 끼는 지점은 세 군데.

[원본]                          [타깃]
   │
   ├── A. 풀백업 시작 시점 (T1)
   │       풀백업이 도는 동안의 변경분이 CDC 와 겹침
   │
   ├── B. CDC 시작 시점 (T5)
   │       cdc-start-time 의 미세한 오차로 일부 변경 중복/누락
   │
   └── C. 컷오버 시점
           트리거/제약/IDENTITY 가 양쪽에서 동시에 발동

대부분의 함정은 이 세 지점에서 발생해요. 케이스별로 풀게요.

2. 케이스 1 — 중복 키 (Duplicate PK)

증상

DMS Task 의 Table statistics 에 Apply errors 가 쌓이고, CloudWatch Logs 에 이런 메시지가 떨어져요.

Violation of PRIMARY KEY constraint 'PK_Orders'. 
Cannot insert duplicate key in object 'dbo.Orders'. 
The duplicate key value is (12345).

원인

풀백업 시점 ~ CDC 시작 시점 사이에 들어온 row 가 풀로드로 한 번, CDC INSERT 로 한 번 적용되면서 충돌해요. CDC start time 을 풀백업 시작 시각으로 잡으면 이게 흔히 일어나요(의도된 안전마진).

대응

DMS Task settings 에서 INSERT 충돌을 흡수하도록 설정.

{
  "ErrorBehavior": {
    "ApplyErrorInsertPolicy": "INSERT_OR_UPDATE",
    "ApplyErrorUpdatePolicy": "LOG_ERROR",
    "ApplyErrorDeletePolicy": "IGNORE_RECORD",
    "ApplyErrorEscalationPolicy": "LOG_ERROR",
    "FullLoadIgnoreConflicts": true
  }
}

⚠️ INSERT_OR_UPDATE 는 PK 가 있어야 동작해요. PK 없는 테이블엔 적용 안 됨. PK 없는 테이블은 별도 처리가 필요.

검증

컷오버 후 양쪽 row count + CHECKSUM_AGG() 비교.

SELECT COUNT(*) AS cnt, CHECKSUM_AGG(BINARY_CHECKSUM(*)) AS chk
FROM dbo.Orders;

같은 값이 나와야 정합 OK.

3. 케이스 2 — NOT NULL / DEFAULT 컬럼

증상

풀로드는 정상인데, CDC 에서 특정 컬럼만 NULL 로 들어오면서 NOT NULL 제약 위반.

Cannot insert the value NULL into column 'created_at', table 'dbo.Orders'. 
Column does not allow nulls.

원인

두 가지가 흔해요.

1. 타깃에 DEFAULT 가 빠짐 — 원본에는 DEFAULT GETDATE() 가 걸려있어서 NULL 이 안 들어오는데, 타깃 스키마를 새로 만들면서 DEFAULT 가 누락됨. CDC 가 NULL 을 그대로 INSERT 함.
2. 컬럼 추가/변경이 원본에만 적용됨 — 마이그레이션 도중 원본 스키마가 바뀜. DMS 는 기본적으로 DDL 을 안 따라가요.

대응

• DEFAULT 누락 점검 — 풀로드 끝난 직후 스키마 비교 한 사이클 돌리기.

-- 양쪽에서 동일 쿼리로 DEFAULT 비교
SELECT t.name AS table_name, c.name AS column_name, dc.definition AS default_value
FROM sys.tables t
JOIN sys.columns c ON t.object_id = c.object_id
LEFT JOIN sys.default_constraints dc ON c.default_object_id = dc.object_id
WHERE t.name = 'Orders'
ORDER BY c.column_id;

• 마이그레이션 기간 동안 원본 스키마 freeze 가 가장 안전. 강제 못 하면 DMS Task settings 의 HandleSourceTableAltered, HandleSourceTableDropped 옵션으로 동작 명시.

4. 케이스 3 — IDENTITY 시드 어긋남

증상

컷오버 후 앱이 첫 INSERT 를 치자마자 PK 충돌.

Violation of PRIMARY KEY constraint 'PK_Orders'. 
Cannot insert duplicate key in object 'dbo.Orders'. 
The duplicate key value is (10001).

원인

복원/CDC 는 row 의 PK 값을 그대로 옮기지만, IDENTITY 의 “다음에 발급할 시드” 는 같이 안 따라와요. 타깃의 IDENTITY 다음 값이 1 부터 시작하는 채로 남아있다가, 앱이 INSERT 하면서 이미 존재하는 키를 다시 만들어요.

대응

컷오버 직후 모든 IDENTITY 테이블에 대해 DBCC CHECKIDENT(..., RESEED, ...) 로 시드 보정.

-- 1. 원본의 현재 MAX 값 확인
SELECT MAX(id) FROM dbo.Orders;
-- => 10000

-- 2. 타깃에서 RESEED
DBCC CHECKIDENT('dbo.Orders', RESEED, 10000);

-- 3. 검증
DBCC CHECKIDENT('dbo.Orders', NORESEED);
-- 'Checking identity information: current identity value '10000'.'

자동화 팁

IDENTITY 컬럼이 많으면 동적 SQL 로 한 번에.

DECLARE @sql NVARCHAR(MAX) = N'';

SELECT @sql = @sql + 
  N'DECLARE @m BIGINT; SELECT @m = ISNULL(MAX(' + c.name + N'),0) FROM ' 
  + QUOTENAME(s.name) + N'.' + QUOTENAME(t.name) + N'; '
  + N'DBCC CHECKIDENT(''' + s.name + N'.' + t.name + N''', RESEED, @m);' + CHAR(13)
FROM sys.tables t
JOIN sys.schemas s ON t.schema_id = s.schema_id
JOIN sys.columns c ON t.object_id = c.object_id
WHERE c.is_identity = 1;

EXEC sp_executesql @sql;

💡 IDENTITY 시드 보정은 컷오버 절차의 필수 단계 예요. 이전 글 컷오버 체크리스트에도 들어있어요. 한 번이라도 빼먹으면 운영 첫 분에 사고.

5. 케이스 4 — 외래키 적용 순서

증상

풀로드 중에 자식 테이블이 부모 테이블보다 먼저 들어가면서 외래키 위반.

The INSERT statement conflicted with the FOREIGN KEY constraint 'FK_OrderItems_Orders'. 
The conflict occurred in database 'MyDB', table 'dbo.Orders', column 'id'.

CDC 단계에서도 트랜잭션 경계가 어긋나면 비슷한 에러가 떨어져요.

원인

DMS 의 풀로드는 테이블을 병렬로 로드해요. 부모/자식 의존성을 모르고 동시에 진행하니까, 자식이 먼저 끝나는 시점이 생겨요.

CDC 도 한 트랜잭션 안에 있던 변경을 항상 같은 트랜잭션 단위로 보장하진 않아요(BatchApplyPreserveTransaction 옵션이 켜져야).

대응

풀로드 전에 타깃의 외래키를 비활성화, 풀로드/CDC 끝나면 다시 활성화 + 검증.

-- 1. 타깃의 모든 FK 비활성화
DECLARE @sql NVARCHAR(MAX) = N'';
SELECT @sql = @sql + 
  N'ALTER TABLE ' + QUOTENAME(s.name) + N'.' + QUOTENAME(t.name)
  + N' NOCHECK CONSTRAINT ' + QUOTENAME(fk.name) + N';' + CHAR(13)
FROM sys.foreign_keys fk
JOIN sys.tables t ON fk.parent_object_id = t.object_id
JOIN sys.schemas s ON t.schema_id = s.schema_id;

EXEC sp_executesql @sql;

-- 2. 풀로드/CDC 진행

-- 3. 컷오버 후 FK 재활성화 + 검증 (WITH CHECK 가 핵심)
SELECT @sql = N'';
SELECT @sql = @sql + 
  N'ALTER TABLE ' + QUOTENAME(s.name) + N'.' + QUOTENAME(t.name)
  + N' WITH CHECK CHECK CONSTRAINT ' + QUOTENAME(fk.name) + N';' + CHAR(13)
FROM sys.foreign_keys fk
JOIN sys.tables t ON fk.parent_object_id = t.object_id
JOIN sys.schemas s ON t.schema_id = s.schema_id;

EXEC sp_executesql @sql;

WITH CHECK CHECK CONSTRAINT 의 두 번째 CHECK 가 중요. 기존 데이터까지 다시 검증 하라는 옵션이에요. 그냥 CHECK CONSTRAINT 만 쓰면 제약은 다시 켜지지만 기존 위반은 안 잡혀요(is_not_trusted = 1 로 남음).

검증

SELECT s.name + '.' + t.name AS table_name, fk.name AS fk_name, fk.is_not_trusted
FROM sys.foreign_keys fk
JOIN sys.tables t ON fk.parent_object_id = t.object_id
JOIN sys.schemas s ON t.schema_id = s.schema_id
WHERE fk.is_not_trusted = 1;

위 쿼리 결과가 비어야 정합성 OK.

6. 케이스 5 — Computed column / rowversion

증상

DMS 가 computed column 또는 rowversion(timestamp) 컬럼에 직접 값을 쓰려다 실패.

The column 'total_amount' cannot be modified because it is either a computed column 
or is the result of a UNION operator.

Cannot insert an explicit value into a timestamp column.

원인

이 두 종류 컬럼은 DB 가 자동 계산/발급 해요. 값을 직접 INSERT 하면 안 됨.

• computed column (예: total_amount AS price * quantity)
• rowversion / timestamp (자동 증가 8-byte 바이너리)

대응

DMS Table mapping 에서 transformation rule 로 해당 컬럼을 제외.

{
  "rule-type": "transformation",
  "rule-id": "100",
  "rule-name": "exclude-computed",
  "rule-target": "column",
  "object-locator": {
    "schema-name": "dbo",
    "table-name": "Orders",
    "column-name": "total_amount"
  },
  "rule-action": "remove-column"
}

rowversion 도 같은 식으로 remove-column. 타깃 테이블에는 동일 정의가 그대로 있으므로, INSERT 시점에 자동 계산됨.

사전 검출

-- computed column 목록
SELECT s.name + '.' + t.name AS table_name, c.name AS column_name
FROM sys.computed_columns c
JOIN sys.tables t ON c.object_id = t.object_id
JOIN sys.schemas s ON t.schema_id = s.schema_id;

-- rowversion/timestamp 컬럼 목록
SELECT s.name + '.' + t.name AS table_name, c.name AS column_name
FROM sys.columns c
JOIN sys.tables t ON c.object_id = t.object_id
JOIN sys.schemas s ON t.schema_id = s.schema_id
JOIN sys.types ty ON c.user_type_id = ty.user_type_id
WHERE ty.name IN ('timestamp', 'rowversion');

이 두 쿼리 결과를 사전에 다 뽑아서 transformation rule 로 다 빼두면 깔끔.

7. 케이스 6 — Collation / 데이터 타입 미스매치

증상

row count 는 같은데 CHECKSUM_AGG 가 안 맞음. 특정 문자열 컬럼을 비교하면 같은 글자처럼 보이는데 다름.

SELECT * FROM source.dbo.Orders WHERE customer_name = N'홍길동';   -- 1건
SELECT * FROM target.dbo.Orders WHERE customer_name = N'홍길동';   -- 0건

원인

• Collation 차이 — 원본 DB 가 Korean_Wansung_CI_AS, 타깃이 SQL_Latin1_General_CP1_CI_AS 같은 경우. 한글이 깨지거나, 비교가 case-insensitive 가 아니거나, trailing space 처리 다름.
• 타입 변경 — DMS 가 자동으로 VARCHAR(MAX) → NVARCHAR(MAX) 같은 변환을 할 때 옵션에 따라 trailing space 가 잘림.

대응

• 타깃 DB 의 collation 을 원본과 동일하게 만들어두는 게 정공법.

-- 새 DB 생성 시 collation 명시
CREATE DATABASE [MyDB] COLLATE Korean_Wansung_CI_AS;

-- 기존 DB collation 변경 (다소 무거운 작업)
ALTER DATABASE [MyDB] COLLATE Korean_Wansung_CI_AS;

• 이미 다른 collation 으로 만들어버렸으면 컬럼 단위 collation 변경 으로 보정.

ALTER TABLE dbo.Orders
ALTER COLUMN customer_name NVARCHAR(100) COLLATE Korean_Wansung_CI_AS NOT NULL;

검증

-- 의심되는 문자열 컬럼은 LEN, DATALENGTH 둘 다 비교
SELECT TOP 10 id, customer_name, LEN(customer_name), DATALENGTH(customer_name) 
FROM dbo.Orders ORDER BY id;

LEN 은 같지만 DATALENGTH 가 다르면 trailing space 차이.

8. 케이스 7 — 트리거 fire-on-replication

증상

CDC 가 INSERT 한 row 에 대해 타깃의 트리거가 발동되면서, 데이터가 한 번 더 변형되거나 다른 테이블에까지 영향이 번짐.

원인

기본적으로 SQL Server 트리거는 모든 INSERT/UPDATE/DELETE 에 발동 해요. CDC 가 흘리는 INSERT 도 예외 없음. 원본에선 트랜잭션 한 번에 트리거 + 본 데이터가 같이 처리됐을 텐데, CDC 는 본 데이터만 흘려요 → 타깃에서 트리거가 또 발동 → 중복 처리.

대응

트리거를 NOT FOR REPLICATION 으로 정의 하면, replication/CDC 로 들어온 변경에는 발동 안 해요.

CREATE TRIGGER trg_Orders_AfterInsert
ON dbo.Orders
AFTER INSERT
NOT FOR REPLICATION
AS
BEGIN
  -- 트리거 로직
END;

기존 트리거 변경은 ALTER TRIGGER 로 똑같이.

⚠️ 이 옵션은 SQL Server 의 replication / CDC 기반 변경을 인식해서 skip 해요. DMS 가 일반 SQL INSERT 로 적용하는 경우엔 안 통할 수 있어요. 안 통하면 마이그레이션 기간 동안 트리거 자체를 DISABLE 해두는 게 가장 확실해요.

-- 컷오버 전: 트리거 다 끄기
DISABLE TRIGGER ALL ON dbo.Orders;

-- 컷오버 후: 다시 켜기
ENABLE TRIGGER ALL ON dbo.Orders;

9. 케이스 8 — LOB / 큰 컬럼

증상

VARBINARY(MAX), NVARCHAR(MAX), XML, IMAGE 같은 LOB 컬럼이 잘려서 들어오거나, 풀로드 자체가 느려짐.

원인

DMS 의 기본 LOB 처리 모드가 Limited LOB mode 인 경우, LOB 컬럼을 일정 크기(기본 32KB) 로 잘라요. 큰 BLOB 가 있는 테이블에선 데이터 손실.

대응

DMS Task settings 의 LOB 모드를 명시.

{
  "TargetMetadata": {
    "SupportLobs": true,
    "FullLobMode": false,
    "LobChunkSize": 64,
    "LimitedSizeLobMode": true,
    "LobMaxSize": 1024
  }
}

💡 Full LOB mode 는 속도가 크게 떨어져요. LOB 가 큰 테이블은 별도 task 로 분리해서 옮기는 게 일반적.

사전 검출

-- 테이블별 LOB 컬럼 + 평균/최대 크기
SELECT s.name + '.' + t.name AS table_name, c.name AS column_name,
       AVG(DATALENGTH(c.name)) AS avg_size,
       MAX(DATALENGTH(c.name)) AS max_size
FROM sys.columns c
JOIN sys.tables t ON c.object_id = t.object_id
JOIN sys.schemas s ON t.schema_id = s.schema_id
JOIN sys.types ty ON c.user_type_id = ty.user_type_id
WHERE ty.name IN ('varbinary', 'nvarchar', 'varchar', 'xml', 'image', 'text', 'ntext')
  AND c.max_length IN (-1, 8000)  -- MAX 타입
GROUP BY s.name, t.name, c.name
ORDER BY max_size DESC;

10. 검증 체크리스트 — 컷오버 전후

마이그레이션 마지막 단계에서 한 번에 돌리는 검증 모음이에요. 이 정도면 정합성에 대해 안심하고 컷오버할 수 있어요.

• DBCC CHECKDB — 무결성 (타깃)
• 테이블별 row count 비교 — 양쪽 동일
• CHECKSUM_AGG(BINARY_CHECKSUM(*)) 비교 — 핵심 테이블 전수
• MAX(updated_at) 비교 — CDC 따라잡힘 확인
• DEFAULT 제약 비교 — 누락된 DEFAULT 가 있는지
• IDENTITY 시드 보정 — 모든 IDENTITY 테이블
• 외래키 is_not_trusted = 0 — 전부 신뢰 상태
• 트리거 enable 상태 — 컷오버용으로 disable 했던 것 복원
• 인덱스/통계 재구성 — 풀로드 중 비활성화했다면 재생성 + UPDATE STATISTICS
• 앱 권한/로그인 매핑 — 고아 사용자 0

11. 정리

데이터 정합성 문제는 사전 점검 → DMS 옵션 → 컷오버 후 보정 의 3단계로 잡히는 게 대부분이에요. 케이스별 핵심만 다시.

저희 사내 마이그레이션에선 위 8가지 중 3 (IDENTITY) + 4 (외래키) + 7 (트리거) 가 가장 자주 발목을 잡았어요. 컷오버 절차의 표준 체크리스트에 넣어두면 사고가 거의 안 납니다.

일단 오늘은 여기까지…..
다음 글에서는 이 시리즈를 한 페이지로 정리하는 MSSQL → AWS RDS 마이그레이션 마스터 체크리스트 를 한 장으로 묶어볼게요.

← 이전 글: (4/5) 변경분 계속 쌓기 — NORECOVERY 체인과 CDC-only 결합

📚 MSSQL → AWS RDS 마이그레이션 시리즈 (전체 5편)

1. 방법 비교 — 6가지 중에서 고르기
2. Native Backup/Restore 실전 — 옵션 그룹부터 컷오버까지
3. DMS + CDC 무중단 컷오버 — 풀로드 후 변경분 따라잡기
4. 변경분 계속 쌓기 — NORECOVERY 체인과 CDC-only 결합 ← 지금 글
5. 정합성 트러블슈팅 — 케이스별 8가지 함정

Native Backup/Restore 실전편을 따라 풀백업 복원까지 끝내고 나면, 다음 질문이 바로 나와요. “이제 운영 중인 원본에서 새로 들어오는 데이터는 어떻게 따라잡지?” 풀백업이 끝난 시점 이후 원본은 계속 INSERT/UPDATE 가 들어오는 중이니까요. 이번 글은 그 “복원 위에 변경분 계속 쌓기” 문제를 RDS for SQL Server 의 제약을 짚어가며 정리해볼게요.

💡 이 글에서 다루는 것

• 왜 “복원이 끝난 DB 위에 다시 백업을 못 올리는가” — RECOVERY/NORECOVERY 차이
• 옵션 A: 차등 + 트랜잭션 로그 백업 체인 (NORECOVERY 유지)
• 옵션 B: 한 번 ONLINE 된 후에는 DMS CDC-only 로 흘리기
• 옵션 C: 앱 레벨 dual-write / 쿼리 기반 증분 ETL
• 베스트 패턴: 풀백업/복원 + CDC-only 결합으로 비용/속도 모두 잡기

1. 먼저 짚어야 하는 제약 — RECOVERY vs NORECOVERY

가장 많이 헷갈리는 부분부터 정리할게요. SQL Server 의 복원은 두 가지 상태로 끝낼 수 있어요.

🚨 여기가 함정입니다. 풀백업 복원을 WITH RECOVERY (기본값) 로 끝내면, 그 위에 차등/로그 백업을 더 못 올려요. RDS for SQL Server 의 rds_restore_database 도 마찬가지로, 한 번 ONLINE 으로 올라온 DB 에 또 백업 적용을 시도하면 LSN 체인 에러가 떨어집니다.

💡 그래서 이전 글에서 풀백업 복원에 @with_norecovery = 1 을 강조했던 거예요. 차등 백업까지 다 적용하고, 마지막 복원에만 @with_norecovery = 0 으로 ONLINE 으로 올리는 패턴.

2. 옵션 A — 차등 + 로그 백업 체인 (NORECOVERY 유지)

가장 정공법. 컷오버 직전까지 타깃 DB 를 RESTORING 상태로 두고, 원본에서 떠오는 차등/로그 백업을 계속 적용해요.

2-1. 흐름

[원본]                                  [타깃 RDS]
  1) FULL backup --------- 업로드 ----> rds_restore_database (NORECOVERY)
  2) LOG backup #1 ------- 업로드 ----> rds_restore_log     (NORECOVERY)
  3) LOG backup #2 ------- 업로드 ----> rds_restore_log     (NORECOVERY)
  ...
  N) 컷오버 시점 LOG ----- 업로드 ----> rds_restore_log     (RECOVERY=ONLINE)

2-2. 원본 — 로그 백업 만들기

차등은 이전 글에서 다뤘으니, 여기선 트랜잭션 로그 백업 위주로.

-- 원본 MSSQL 의 복구 모델이 FULL 또는 BULK_LOGGED 여야 로그 백업이 의미 있음
ALTER DATABASE [MyDB] SET RECOVERY FULL;

-- 10분마다 로그 백업 (예시)
BACKUP LOG [MyDB]
TO DISK = N'D:\backup\log\MyDB_log_20260530_1000.trn'
WITH COMPRESSION, CHECKSUM, STATS = 10;

⚠️ 복구 모델이 SIMPLE 이면 로그 백업 자체가 불가능해요. 운영 DB 가 SIMPLE 이면 옵션 A 는 사용 불가 → 옵션 B(CDC) 로.

2-3. 타깃 RDS — 로그 백업 적용

EXEC msdb.dbo.rds_restore_log
  @restore_db_name = 'MyDB',
  @s3_arn_to_restore_from = 'arn:aws:s3:::my-mssql-migration/log/MyDB_log_20260530_1000.trn',
  @with_norecovery = 1;

진행은 rds_task_status 로 확인. 로그 백업은 보통 풀백업보다 훨씬 작아서 1~5분 단위로 빠르게 흘릴 수 있어요.

2-4. 컷오버 — 마지막 로그만 RECOVERY 로

-- 원본: 쓰기 차단
ALTER DATABASE [MyDB] SET READ_ONLY WITH ROLLBACK IMMEDIATE;

-- 원본: 마지막 tail-log 백업
BACKUP LOG [MyDB]
TO DISK = N'D:\backup\log\MyDB_tail.trn'
WITH NORECOVERY, COMPRESSION, CHECKSUM;

-- 타깃: 마지막 로그를 RECOVERY 로 적용 → DB ONLINE
EXEC msdb.dbo.rds_restore_log
  @restore_db_name = 'MyDB',
  @s3_arn_to_restore_from = 'arn:aws:s3:::my-mssql-migration/log/MyDB_tail.trn',
  @with_norecovery = 0;

🎉 이 시점에 타깃 DB 가 ONLINE 으로 올라오면서 컷오버 완료.

2-5. 옵션 A 의 장단점

장점

• 순정 MSSQL 방식. 추가 매니지드 서비스 비용 없음
• 데이터 손실 0 (트랜잭션 로그 단위로 정확히 따라잡힘)
• “그대로” 보존이 가장 잘 됨

단점

• 타깃 DB 가 컷오버 전까지 계속 RESTORING 상태 → 쿼리/검증 불가
• 로그 백업 주기 / 업로드 / 복원이 모두 수동 파이프라인. 자동화 필요
• 원본 복구 모델이 SIMPLE 이면 사용 불가

3. 옵션 B — DMS CDC-only 모드 (이미 ONLINE 된 DB 에 흘리기)

만약 이미 WITH RECOVERY 로 ONLINE 시켜버렸거나, 검증을 위해 타깃에서 쿼리를 돌려보고 싶다면 옵션 A 는 쓸 수 없어요. 이때 쓰는 게 DMS 의 CDC-only 모드.

3-1. 핵심 아이디어

• 풀로드는 이미 끝났다 (Native Backup/Restore 로)
• DMS 한테 “풀로드 건너뛰고 변경분만 잡아 흘려” 라고 시킴
• 시작 시점(timestamp 또는 LSN)을 명시해서, 풀백업 시점 이후의 변경을 잡아냄

3-2. Migration Type

aws dms create-replication-task \
  --replication-task-identifier mssql-cdc-only \
  --source-endpoint-arn arn:aws:dms:...:MSSQL-SOURCE \
  --target-endpoint-arn arn:aws:dms:...:RDS-TARGET \
  --replication-instance-arn arn:aws:dms:...:DMS-MSSQL-MIG \
  --migration-type cdc \
  --cdc-start-time 2026-05-30T10:00:00Z \
  --table-mappings file://table-mappings.json \
  --replication-task-settings file://task-settings.json

핵심 옵션 두 개.

3-3. 시작 시점을 어떻게 정하나

가장 안전한 방법은 풀백업을 시작하기 직전의 시각 을 기록해두는 거예요.

-- 원본에서 풀백업 시작 전에
SELECT GETUTCDATE() AS backup_start_utc;
-- => 2026-05-30 09:55:00

-- 이 값을 cdc-start-time 으로 넣음. backup 진행 중 변경은 중복 적용되겠지만,
-- DMS 의 idempotent 동작과 PK 충돌 처리로 보통 안전하게 흡수됨.

💡 LSN 기준으로 더 정확하게 잡고 싶다면 --cdc-start-position 에 LSN:xxxxx:xxxxxxxx 형태로 줄 수 있어요. 풀백업 직전 LSN 을 sys.fn_dblog 로 따와서 넣는 패턴.

3-4. 옵션 B 의 장단점

장점

• 풀로드를 DMS 로 안 돌려도 됨 → 비용 절감 + 시간 단축
• 타깃 DB 를 ONLINE 으로 두고도 변경 따라잡기 가능 → 검증/대시보드 미리 붙여볼 수 있음
• CDC latency 를 보면서 컷오버 타이밍을 잡을 수 있음 (이전 글의 7단계 컷오버 그대로 적용)

단점

• 원본에 CDC 활성화 가 필요 (이전 DMS 글 참고)
• 풀백업 시점 ~ CDC 시작 시점 사이의 변경이 중복 적용 될 수 있음. PK/UPSERT 동작 사전 점검
• DMS Replication Instance 비용은 발생

4. 옵션 C — 앱 레벨 dual-write / 쿼리 기반 증분 ETL

DB 단 메커니즘(백업 체인, CDC) 을 못 쓰는 환경에선 마지막 카드로.

4-1. Dual-write

애플리케이션이 INSERT/UPDATE 를 칠 때 원본 + 타깃 양쪽에 동시 기록.

• 장점: DB 메커니즘 의존 없음. 앱이 통제 가능
• 단점: 코드 수정 필요. 실패/재시도 시 양쪽 일관성 보장이 까다로움. 두 DB 가 잠시라도 다르면 디버깅 지옥

4-2. 쿼리 기반 증분 ETL

타임스탬프나 버전 컬럼이 있는 테이블에 한해, 주기적으로

SELECT * FROM dbo.Orders 
WHERE updated_at > @last_sync_ts;

식으로 끌어와 타깃에 MERGE.

• 장점: 구현 간단. 추가 서비스 불필요
• 단점: DELETE 를 못 잡음(soft delete 면 OK). updated_at 이 없는 테이블엔 적용 불가. PK 충돌 처리 직접 구현

🚨 옵션 C 는 “다른 게 다 안 될 때” 의 카드예요. 실무에선 잔불 정도로만 쓰고, 본진은 A 또는 B 로.

5. 베스트 패턴 — 풀백업/복원 + CDC-only 결합

이게 이전 DMS 글 마지막에 예고한 패턴이에요. 두 방법의 장점만 가져와요.

시점         원본                             타깃 RDS
─────────────────────────────────────────────────────────────
T0           ┌─ CDC 활성화                     
T1           │  GETUTCDATE() = T1 기록
T1+ε         │  FULL BACKUP 시작                                       
T2           │  FULL BACKUP 완료 → S3 업로드                            
T3           │                                rds_restore_database
T4           │                                (WITH RECOVERY=ONLINE) 🎉
T5           │  DMS CDC-only Task 시작
             │   --cdc-start-time = T1
T5+          │  CDC latency 안정화 추적
컷오버       │  앱 쓰기 차단 → latency 0 대기
             └─ 앱 connection string 전환

5-1. 왜 이게 좋은가

핵심은 “풀카피의 무거운 일은 백업/복원 으로, 변경분 추적의 가벼운 일은 DMS 로” 분담시키는 것. DMS 가 풀로드까지 하면 시간/비용이 다 무거워지는데, 그 부분을 백업/복원으로 떼어내요.

5-2. 실전 순서 (정리)

• T0: 원본에 CDC 활성화 (DB + 모든 대상 테이블)
• T1: 풀백업 시작 시각 기록 (SELECT GETUTCDATE())
• T1+ε: 원본 풀백업 → S3 업로드
• T3: RDS 에서 rds_restore_database (@with_norecovery = 0 → ONLINE)
• T4: 타깃 검증 (DBCC CHECKDB, row count 스냅샷)
• T5: DMS CDC-only task 시작 (--migration-type cdc, --cdc-start-time T1)
• T5+: CloudWatch 의 CDCLatencyTarget 안정화 확인 (5~10분 연속 < 3초)
• 컷오버: 앱 쓰기 차단 → latency 0 수렴 대기 → 앱 connection string 전환
• 사후: DMS Task / Endpoints / Replication Instance 삭제, 원본 CDC 비활성화

💡 풀백업 시작 ~ CDC 시작 사이의 변경은 재적용 돼요. PK 충돌 발생 시 DMS 가 어떻게 처리하는지 사전에 확인하세요. Task 설정의 ErrorBehavior 에서 duplicate key 를 IGNORE_RECORD 로 두면 보통 안전하게 흡수됩니다.

6. 자주 깨지는 함정

이 패턴에서 한 번씩 다 밟아본 함정들이에요.

• 🚨 풀백업 복원을 WITH RECOVERY 로 끝낸 뒤 차등 백업 더 올리려고 시도 → LSN 체인 에러. 옵션 A 를 끝까지 가려면 마지막까지 NORECOVERY 유지
• 🚨 CDC 활성화 시점을 풀백업 시작 뒤로 미룸 → 두 시각 사이의 변경이 캡처 안 됨 → 영원히 누락
• 🚨 cdc-start-time 을 풀백업 완료 시각으로 넣음 → 풀백업 진행 도중의 변경 누락
• 🚨 로그 백업과 차등 백업을 섞었는데 LSN 체인이 어긋남 → 복원 거부. 차등을 적용했다면 그 뒤로는 로그 백업 체인만 쭉 가야 함
• 🚨 타깃 DB 의 외래키/트리거가 활성화된 상태에서 CDC 적용 시작 → 적용 실패. 컷오버 직전까지 트리거 disable 권장
• 🚨 원본 트랜잭션 로그가 폭증 → 로그 백업 주기가 너무 길거나 CDC 캡처 잡이 멈춤. log_reuse_wait_desc 확인

7. 정리 — 상황별 선택 가이드

저희 사내 케이스에서 가장 자주 쓰는 건 옵션 A+B 결합 이에요. 풀카피는 백업/복원으로 한 방에 끝내고, 변경분은 DMS CDC-only 로 가볍게 따라잡는 구성. 비용/속도/다운타임 세 마리 토끼를 잡아요.

일단 오늘은 여기까지…..
다음 글에서는 이 결합 패턴에서 실제로 자주 만나는 데이터 정합성 문제 — 중복 키 처리, NULL 컬럼, IDENTITY 시드 어긋남, 외래키 적용 순서 — 를 케이스별로 풀어볼게요.

← 이전 글: (3/5) DMS + CDC 무중단 컷오버 — 풀로드 후 변경분 따라잡기 ｜ 다음 글 →: (5/5) 정합성 트러블슈팅 — 케이스별 8가지 함정

📚 MSSQL → AWS RDS 마이그레이션 시리즈 (전체 5편)

1. 방법 비교 — 6가지 중에서 고르기
2. Native Backup/Restore 실전 — 옵션 그룹부터 컷오버까지
3. DMS + CDC 무중단 컷오버 — 풀로드 후 변경분 따라잡기 ← 지금 글
4. 변경분 계속 쌓기 — NORECOVERY 체인과 CDC-only 결합
5. 정합성 트러블슈팅 — 케이스별 8가지 함정

지난 글에서 Native Backup/Restore 로 풀카피 → 컷오버 순서를 정리했어요. 그런데 운영 DB 라 단 몇 분의 다운타임도 허용 안 되는 케이스가 있죠. 이번 글은 그런 상황에서 쓰는 AWS DMS + CDC 구성법이에요. 원본을 운영 중 그대로 두고 풀로드 → 변경분 실시간 따라잡기 → 컷오버 순서로 다운타임을 분 단위 이하로 줄이는 흐름을 정리합니다.

💡 이 글에서 다루는 것

• 원본 MSSQL 에서 CDC 활성화 (DB 레벨 + 테이블 레벨)
• DMS Replication Instance / Endpoints / Task 세팅
• Full Load + CDC 동시 모드 vs 분리 모드 차이
• 스키마/인덱스/IDENTITY 는 DMS 가 안 가져온다는 점과 대응
• CloudWatch 로 latency 추적해서 안전하게 컷오버하는 절차
• 마이그레이션 끝난 뒤 CDC/DMS 정리(cleanup)

1. 큰 그림 — 무엇이 어디서 도는가

[내부망 MSSQL]
   │  (1) CDC 로 변경분 캡처 (트랜잭션 로그 기반)
   │
   ▼
[DMS Replication Instance (VPC)]
   │  (2) Full Load + 캡처된 변경분을 타깃에 적용
   │
   ▼
[AWS RDS for SQL Server]

DMS 는 Replication Instance 라는 EC2 같은 워커를 하나 띄워두고, 거기서 소스의 트랜잭션 로그 를 읽어와 타깃에 흘려줘요. 원본은 CDC 만 켜두면 되고, DMS 가 직접 원본을 폴링하면서 변경을 잡아갑니다.

💡 풀로드 + CDC 를 같은 task 에서 켜면 풀로드 진행 중에도 변경을 캐시해두고, 풀로드 끝나는 순간부터 따라잡기를 시작해요. “다운타임 거의 0” 의 핵심.

2. 원본 MSSQL 준비 — CDC 활성화

DMS 가 MSSQL 의 변경분을 잡아가려면 원본에서 CDC 가 켜져 있어야 해요. SQL Server 의 CDC 는 트랜잭션 로그를 읽어서 변경을 별도 시스템 테이블에 기록하는 기능이에요.

2-1. DB 레벨 CDC 켜기

USE [MyDB];
EXEC sys.sp_cdc_enable_db;

-- 확인
SELECT name, is_cdc_enabled 
FROM sys.databases 
WHERE name = 'MyDB';

is_cdc_enabled = 1 이면 OK.

2-2. 테이블 레벨 CDC 켜기

CDC 는 테이블 단위로 한 번 더 켜줘야 해요. 마이그레이션 대상 테이블 전부에 대해 돌립니다.

USE [MyDB];

EXEC sys.sp_cdc_enable_table
  @source_schema = N'dbo',
  @source_name   = N'Orders',
  @role_name     = NULL,           -- 별도 role 안 쓰면 NULL
  @supports_net_changes = 1;

테이블 많으면 동적 SQL 로 한 번에 돌려요.

DECLARE @sql NVARCHAR(MAX) = N'';
SELECT @sql = @sql + 
  N'EXEC sys.sp_cdc_enable_table @source_schema=N''' + s.name 
  + N''', @source_name=N''' + t.name 
  + N''', @role_name=NULL, @supports_net_changes=1;' + CHAR(13)
FROM sys.tables t
JOIN sys.schemas s ON t.schema_id = s.schema_id
WHERE s.name = 'dbo';

EXEC sp_executesql @sql;

2-3. SQL Server Agent 가 떠 있어야 함

CDC 캡처 잡(cdc.MyDB_capture) 은 SQL Server Agent 가 돌려요. Agent 가 죽어있으면 변경이 안 잡혀요.

EXEC msdb.dbo.sp_help_job @job_name = N'cdc.MyDB_capture';

current_execution_status 가 1 (idle 아닌 실행 중) 또는 정상 스케줄로 도는지 확인.

⚠️ RDS for SQL Server 소스 였다면 CDC 활성화 절차가 조금 달라요(rds_cdc_enable_db). 이 글은 온프레미스/EC2 소스 기준.

3. AWS 측 사전 세팅 — Replication Instance / Endpoints

3-1. Replication Subnet Group + Instance

aws dms create-replication-subnet-group \
  --replication-subnet-group-identifier dms-subnet-grp \
  --replication-subnet-group-description "DMS subnet group" \
  --subnet-ids subnet-aaaa subnet-bbbb

aws dms create-replication-instance \
  --replication-instance-identifier dms-mssql-mig \
  --replication-instance-class dms.r5.large \
  --allocated-storage 100 \
  --vpc-security-group-ids sg-xxxxxxxx \
  --replication-subnet-group-identifier dms-subnet-grp \
  --no-publicly-accessible \
  --multi-az

인스턴스 사이즈는 풀로드 데이터량/병렬도/CDC 부하 따라 골라요. 보통 dms.r5.large 부터 시작해서 latency 보면서 키워요.

3-2. Source / Target Endpoints

Source (내부망 MSSQL) — S2S VPN 으로 접근.

aws dms create-endpoint \
  --endpoint-identifier mssql-source \
  --endpoint-type source \
  --engine-name sqlserver \
  --server-name 10.x.x.x \
  --port 1433 \
  --database-name MyDB \
  --username dms_user \
  --password '<DMS_USER_PASSWORD>'

Target (AWS RDS for SQL Server)

aws dms create-endpoint \
  --endpoint-identifier rds-target \
  --endpoint-type target \
  --engine-name sqlserver \
  --server-name my-mssql-rds.xxxx.ap-northeast-2.rds.amazonaws.com \
  --port 1433 \
  --database-name MyDB \
  --username admin \
  --password '<RDS_ADMIN_PASSWORD>'

3-3. Connection 테스트

엔드포인트를 만들면 반드시 한 번 테스트.

aws dms test-connection \
  --replication-instance-arn arn:aws:dms:ap-northeast-2:123456789012:rep:DMS-MSSQL-MIG \
  --endpoint-arn arn:aws:dms:ap-northeast-2:123456789012:endpoint:MSSQL-SOURCE

✅ 결과가 successful 이어야 다음 단계로 갈 수 있어요. 실패 사유는 콘솔의 Last failure message 에 떨어져요.

3-4. 소스 계정 권한

dms_user 에는 최소 권한만. 흔히 깨지는 권한 세트는 다음 세 가지에요.

USE master;
GRANT VIEW SERVER STATE TO dms_user;

USE MyDB;
EXEC sp_addrolemember 'db_owner', 'dms_user';   
-- 또는 SELECT + VIEW DATABASE STATE + db_datareader 조합

DMS 가 CDC 함수(fn_cdc_get_all_changes_*) 를 호출하기 때문에 단순 db_datareader 만으론 부족해요. db_owner 가 가장 깔끔하지만, 보안상 줄이고 싶다면 EXECUTE 권한을 CDC 함수에 별도 부여하는 방식이 있어요.

4. 스키마는 따로 — DMS 가 안 챙기는 것들

🚨 여기서 가장 많이 헷갈려요. DMS 는 데이터 위주 로 옮기는 서비스라, 다음을 직접 챙겨야 해요.

일반적인 대응 패턴

1. 원본에서 SqlPackage /Action:Extract 로 DACPAC 만들기 (스키마만, 데이터 X)
2. 타깃 RDS 에 SqlPackage /Action:Publish 로 스키마 먼저 적용
3. 그 다음 DMS 로 데이터만 채우기
4. DMS 끝난 후 외래키 / 트리거 / 시퀀스 시드 보정

또는 SSMS 의 “Generate Scripts” 로 스키마 + 보조 객체 만 추출해도 OK.

💡 풀로드 중에는 타깃의 외래키와 인덱스를 잠시 끄거나 비활성화 하는 게 빨라요. Task 설정의 Target metadata 에서 BatchApplyEnabled + 인덱스/제약 처리를 조정할 수 있어요.

5. Migration Task 만들기

이제 본 task. Full Load + CDC 모드로 만들고, table mapping 으로 옮길 테이블을 지정해요.

5-1. Table mappings (table-mappings.json)

{
  "rules": [
    {
      "rule-type": "selection",
      "rule-id": "1",
      "rule-name": "select-dbo",
      "object-locator": {
        "schema-name": "dbo",
        "table-name": "%"
      },
      "rule-action": "include"
    }
  ]
}

dbo 스키마의 모든 테이블을 선택. 일부만 옮길 거면 table-name 을 구체적으로.

5-2. Task settings (task-settings.json)

{
  "TargetMetadata": {
    "BatchApplyEnabled": true,
    "ParallelLoadThreads": 8,
    "ParallelLoadBufferSize": 500
  },
  "FullLoadSettings": {
    "TargetTablePrepMode": "TRUNCATE_BEFORE_LOAD",
    "MaxFullLoadSubTasks": 8,
    "CommitRate": 10000
  },
  "Logging": {
    "EnableLogging": true,
    "LogComponents": [
      { "Id": "SOURCE_CAPTURE", "Severity": "LOGGER_SEVERITY_DEFAULT" },
      { "Id": "SOURCE_UNLOAD",  "Severity": "LOGGER_SEVERITY_DEFAULT" },
      { "Id": "TARGET_APPLY",   "Severity": "LOGGER_SEVERITY_DEFAULT" },
      { "Id": "TARGET_LOAD",    "Severity": "LOGGER_SEVERITY_DEFAULT" }
    ]
  },
  "ChangeProcessingTuning": {
    "BatchApplyPreserveTransaction": true,
    "BatchApplyTimeoutMin": 1,
    "BatchApplyTimeoutMax": 30,
    "MinTransactionSize": 1000
  }
}

5-3. Task 생성

aws dms create-replication-task \
  --replication-task-identifier mssql-fullload-cdc \
  --source-endpoint-arn arn:aws:dms:...:MSSQL-SOURCE \
  --target-endpoint-arn arn:aws:dms:...:RDS-TARGET \
  --replication-instance-arn arn:aws:dms:...:DMS-MSSQL-MIG \
  --migration-type full-load-and-cdc \
  --table-mappings file://table-mappings.json \
  --replication-task-settings file://task-settings.json

# 시작
aws dms start-replication-task \
  --replication-task-arn arn:aws:dms:...:task:MSSQL-FULLLOAD-CDC \
  --start-replication-task-type start-replication

💡 full-load-and-cdc 가 핵심. full-load 만이면 풀로드 끝난 시점부터의 변경이 누락돼요.

6. 진행 모니터링 — 무엇을 봐야 하는가

6-1. Task 통계

콘솔에서 Task 의 Table statistics 탭이 가장 직관적이에요. 테이블별로

• Full load rows / Total
• Inserts / Updates / Deletes (CDC 단계)
• Load state (Table completed, Before load, Full load, Table error)

6-2. CloudWatch 핵심 지표

✅ 컷오버 직전 체크 — CDCLatencyTarget 이 연속 5~10분간 1~3초 이내 유지되면 따라잡기 안정 상태로 봐도 됩니다.

⚠️ CDCLatencyTarget 이 점점 커지면 DMS 인스턴스 사양 / 타깃 디스크 IOPS / 타깃 인덱스가 병목. 이 상태로 컷오버하면 안 됩니다.

7. 컷오버 절차 — 다운타임 분 단위 이하로

여기서부터가 본 게임이에요. 절차는 한 줄도 빼먹지 마세요.

Step 1. 사전 정렬

• CDC latency 가 안정적으로 작음 (5~10분 연속)
• Table statistics 의 에러 0
• 타깃에 인덱스/외래키 보조 객체 사전 생성 완료 (또는 사전 비활성)
• 애플리케이션 측 새 접속 정보(RDS 엔드포인트) 준비 완료

Step 2. 원본 쓰기 차단

가장 안전한 방법은 애플리케이션 측에서 새 트랜잭션을 막는 거예요. DB 단에서 막으려면

-- 원본 MSSQL
ALTER DATABASE [MyDB] SET READ_ONLY WITH ROLLBACK IMMEDIATE;

또는 앱 계정의 권한을 일시적으로 회수.

Step 3. 마지막 변경분 따라잡기 대기

CDCLatencyTarget → 0 으로 수렴
CDCIncomingChanges → 0 으로 수렴

10~30초 정도면 보통 마지막 트랜잭션까지 다 따라잡아요.

Step 4. 검증

-- 양쪽 row count 비교
SELECT COUNT(*) FROM dbo.Orders;       -- 원본
SELECT COUNT(*) FROM dbo.Orders;       -- 타깃

-- 최신 데이터 비교
SELECT MAX(updated_at) FROM dbo.Orders;

핵심 테이블 몇 개만 빠르게 비교.

Step 5. 외래키/시퀀스/IDENTITY 복구

-- 외래키 다시 enable
ALTER TABLE dbo.Orders WITH CHECK CHECK CONSTRAINT ALL;

-- IDENTITY 시드 재설정 (원본의 최댓값으로)
DBCC CHECKIDENT('dbo.Orders', RESEED, <원본 MAX(id)>);

Step 6. 앱 connection string 전환

DNS 변경 or config 핫스왑. 새 쿼리는 RDS 로 흐름.

Step 7. Task 중지

aws dms stop-replication-task --replication-task-arn arn:aws:dms:...:task:MSSQL-FULLLOAD-CDC

🎉 컷오버 완료. 다운타임은 보통 1~3분 안에 끝나요.

8. 사후 정리 — 비싸게 두지 말기

DMS Replication Instance 는 시간당 요금이 꾸준히 나와요. 컷오버 끝나면 빠르게 정리.

# 1. Task 삭제
aws dms delete-replication-task --replication-task-arn ...

# 2. Endpoints 삭제
aws dms delete-endpoint --endpoint-arn arn:aws:dms:...:endpoint:MSSQL-SOURCE
aws dms delete-endpoint --endpoint-arn arn:aws:dms:...:endpoint:RDS-TARGET

# 3. Replication Instance 삭제
aws dms delete-replication-instance --replication-instance-arn arn:aws:dms:...:rep:DMS-MSSQL-MIG

원본 MSSQL 의 CDC 도 더 이상 필요 없으면 끄세요. 트랜잭션 로그 보존 부담이 줄어요.

USE [MyDB];

-- 테이블별 CDC 끄기
EXEC sys.sp_cdc_disable_table 
  @source_schema = N'dbo', 
  @source_name = N'Orders', 
  @capture_instance = N'all';

-- DB 레벨 CDC 끄기
EXEC sys.sp_cdc_disable_db;

9. 자주 깨지는 함정

저도 한 번씩 다 밟아본 함정들이에요.

• 🚨 CDC 안 켜고 task 시작 → full-load-and-cdc 가 CDC source endpoint not configured 에러로 죽음
• 🚨 SQL Server Agent 가 꺼져있음 → CDC 캡처 잡이 안 돌아 변경이 누적되다 폭주
• 🚨 타깃에 외래키가 켜진 채 풀로드 → 부모/자식 로드 순서 때문에 실패. 풀로드 전 disable
• 🚨 IDENTITY 시드 미보정 → 컷오버 후 새 INSERT 가 키 충돌
• 🚨 권한 부족 (VIEW SERVER STATE, CDC 함수 EXECUTE) → CDC 단계에서 silent 하게 latency 만 늘어남
• 🚨 CDCLatencyTarget 이 점점 커짐 → DMS 인스턴스 / 타깃 IOPS / 인덱스 병목. 이 상태로 컷오버 절대 금지
• 🚨 트랜잭션 로그 폭증 → CDC 가 안 따라잡고 있거나, 풀백업/로그백업 주기가 너무 길어서. log_reuse_wait_desc 확인

10. Native Backup/Restore vs DMS + CDC — 다시 정리

이전 글과 함께 의사결정 표 한 장으로 정리해드릴게요.

저희 사내 케이스 기준으로는

• 유지보수 창이 1~2시간 허락 → Native Backup/Restore 단독
• 유지보수 창이 거의 없음 → Native Backup/Restore 로 풀카피 후 DMS 의 CDC-only 모드 로 변경분만 흘려 컷오버

두 번째 패턴이 사실상 베스트에요. 풀로드 비용은 백업/복원으로 절약하고, CDC 만 DMS 로 처리해서 latency 안정화 후 컷오버.

일단 오늘은 여기까지…..
다음 글에서는 이 두 번째 패턴 — 백업/복원 + CDC-only DMS 의 결합을 단계별로 풀어볼게요.

← 이전 글: (2/5) Native Backup/Restore 실전 — 옵션 그룹부터 컷오버까지 ｜ 다음 글 →: (4/5) 변경분 계속 쌓기 — NORECOVERY 체인과 CDC-only 결합

📚 MSSQL → AWS RDS 마이그레이션 시리즈 (전체 5편)

1. 방법 비교 — 6가지 중에서 고르기
2. Native Backup/Restore 실전 — 옵션 그룹부터 컷오버까지 ← 지금 글
3. DMS + CDC 무중단 컷오버 — 풀로드 후 변경분 따라잡기
4. 변경분 계속 쌓기 — NORECOVERY 체인과 CDC-only 결합
5. 정합성 트러블슈팅 — 케이스별 8가지 함정

지난 글에서 내부망 MSSQL → AWS RDS for SQL Server 마이그레이션 방법 6가지를 비교하고, Native Backup/Restore 를 1순위로 추천드렸어요. 이번 글은 그 실전편이에요. RDS 옵션 그룹 세팅부터 시작해서, 풀백업 → S3 업로드 → 복원, 마지막으로 컷오버 시점의 차등 백업(differential) 으로 다운타임을 짧게 끊는 데까지 한 번에 따라가봅니다.

💡 이 글에서 다루는 것

• RDS 옵션 그룹(SQLSERVER_BACKUP_RESTORE) + IAM Role + S3 버킷 사전 세팅
• 원본에서 BACKUP DATABASE 로 풀백업 (STRIPE / COMPRESSION / CHECKSUM)
• S3 업로드 시 주의점 (KMS, 멀티파트, 리전 매칭)
• RDS 에서 rds_restore_database 로 복원하고 rds_task_status 로 진행 따라가기
• 컷오버 시점의 차등 백업 + NORECOVERY 흐름
• 복원 후 반드시 챙겨야 하는 로그인/사용자 매핑

1. 사전 그림 — 무엇이 어디에 있어야 하나

먼저 그림 한 번 그려두면 머리가 정리돼요.

[내부망 MSSQL]
    │
    │ (1) BACKUP DATABASE → .bak (stripe N개, 압축)
    ▼
[내부망 파일 서버 / jump 서버]
    │
    │ (2) aws s3 cp  (S2S VPN 또는 인터넷)
    ▼
[S3 버킷 (AWS, 같은 리전)]
    │
    │ (3) EXEC msdb.dbo.rds_restore_database
    ▼
[AWS RDS for SQL Server]

세 가지를 사전에 세팅해두면 본 작업은 사실상 명령어 몇 줄이에요.

• S3 버킷 — RDS 인스턴스와 같은 리전.
• IAM Role — RDS 가 S3 에 접근할 수 있도록.
• RDS Option Group — SQLSERVER_BACKUP_RESTORE 옵션을 붙이고, 위 IAM Role 을 지정.

이 셋 중 하나라도 어긋나면 rds_restore_database 가 곧장 권한 에러를 뱉어요. 순서대로 해두면 한 번에 통과합니다.

2. S3 버킷 + IAM Role 만들기

2-1. S3 버킷

리전만 잘 맞춰주세요. 그리고 버킷 정책은 처음엔 굳이 손대지 않아도 동작해요. IAM Role 권한으로 처리되니까요.

aws s3 mb s3://my-mssql-migration --region ap-northeast-2

⚠️ 인스턴스 리전과 버킷 리전이 다르면 RDS 가 접근 자체를 거부해요. 가장 흔히 깨지는 포인트 1위.

2-2. IAM Role

RDS 의 SQL Server 서비스가 S3 에 접근하도록 신뢰관계를 잡아줘야 해요. trust policy 와 권한 정책 둘 다 필요.

Trust policy (rds-s3-trust.json)

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "rds.amazonaws.com" },
    "Action": "sts:AssumeRole"
  }]
}

권한 정책 (rds-s3-policy.json)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::my-mssql-migration"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:ListMultipartUploadParts",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::my-mssql-migration/*"
    }
  ]
}

aws iam create-role \
  --role-name rds-sqlserver-s3-role \
  --assume-role-policy-document file://rds-s3-trust.json

aws iam put-role-policy \
  --role-name rds-sqlserver-s3-role \
  --policy-name rds-sqlserver-s3-policy \
  --policy-document file://rds-s3-policy.json

💡 KMS 로 암호화된 버킷이면 위 정책에 kms:Decrypt, kms:GenerateDataKey 권한도 추가해주세요. 이거 빼먹고 한참 헤매는 분 많아요.

3. RDS Option Group 만들고 붙이기

이제 만든 IAM Role 을 RDS 인스턴스가 쓰도록 옵션 그룹을 만들고 attach 해요.

# 1. 옵션 그룹 생성 (SQL Server 버전/에디션 맞춰서)
aws rds create-option-group \
  --option-group-name mssql-backup-restore-og \
  --engine-name sqlserver-se \
  --major-engine-version 15.00 \
  --option-group-description "Native backup/restore for migration"

# 2. SQLSERVER_BACKUP_RESTORE 옵션 추가 + IAM Role 연결
aws rds add-option-to-option-group \
  --option-group-name mssql-backup-restore-og \
  --options "OptionName=SQLSERVER_BACKUP_RESTORE,OptionSettings=[{Name=IAM_ROLE_ARN,Value=arn:aws:iam::123456789012:role/rds-sqlserver-s3-role}]" \
  --apply-immediately

# 3. 인스턴스에 옵션 그룹 적용
aws rds modify-db-instance \
  --db-instance-identifier my-mssql-rds \
  --option-group-name mssql-backup-restore-og \
  --apply-immediately

옵션 그룹은 동적(dynamic) 옵션이라 인스턴스 재부팅 없이도 붙어요. 단, modify-db-instance 가 완전히 끝날 때까지(상태 available) 기다린 다음에 다음 단계로 가세요.

✅ 검증: SSMS / sqlcmd 로 인스턴스에 붙어서 아래 한 줄 실행해 보세요.

EXEC msdb.dbo.rds_show_configuration;

옵션이 잘 붙었으면 S3 ARN access for backup/restore 같은 라인이 보여요.

4. 원본에서 풀백업 만들기 (STRIPE + COMPRESSION)

이제 원본 MSSQL 에서 백업을 떠요. 한 파일로 통째로 떨어뜨리지 말고 STRIPE 으로 4~8 분할 하는 걸 추천드려요. 백업/복원 둘 다 병렬화돼서 훨씬 빠릅니다.

BACKUP DATABASE [MyDB]
TO DISK = N'D:\backup\MyDB_full_01.bak',
   DISK = N'D:\backup\MyDB_full_02.bak',
   DISK = N'D:\backup\MyDB_full_03.bak',
   DISK = N'D:\backup\MyDB_full_04.bak'
WITH 
  COMPRESSION,
  CHECKSUM,
  MAXTRANSFERSIZE = 4194304,  -- 4MB
  BUFFERCOUNT = 50,
  STATS = 5;

옵션 의미 한 줄씩.

⚠️ BUFFERCOUNT 너무 크게 잡으면 백업 세션이 메모리를 많이 먹어요. 운영 DB 라면 50 정도가 무난.

백업 끝나면 파일 크기와 무결성을 한 번 더 확인.

RESTORE VERIFYONLY 
FROM DISK = N'D:\backup\MyDB_full_01.bak',
     DISK = N'D:\backup\MyDB_full_02.bak',
     DISK = N'D:\backup\MyDB_full_03.bak',
     DISK = N'D:\backup\MyDB_full_04.bak'
WITH CHECKSUM;

🎉 The backup set on file 1 is valid. 가 떨어지면 OK.

5. S3 로 업로드

내부망 → S3 업로드는 S2S VPN 으로 가도 되고, 인터넷 게이트웨이로 가도 돼요. VPC endpoint(S3 Gateway Endpoint) 가 있으면 RDS 가 복원할 때도 더 안정적이고 빨라요.

aws s3 cp D:\backup\ s3://my-mssql-migration/mssql/ \
  --recursive \
  --include "MyDB_full_*.bak" \
  --expected-size 50000000000  # 대용량이면 명시

큰 파일은 CLI 가 자동으로 멀티파트 업로드로 끊어 올려요. 멀티파트 기본 chunk 가 작으면 업로드 객체 수가 너무 많아져서 느려질 수 있는데, 이때는 chunk 를 키워주세요.

aws configure set default.s3.multipart_chunksize 64MB
aws configure set default.s3.max_concurrent_requests 16

업로드 끝나면 객체 리스트 한 번 확인.

aws s3 ls s3://my-mssql-migration/mssql/

💡 업로드 중간에 끊겨도 멀티파트는 이어 올라가요. aws s3 cp 를 다시 실행하면 이미 업로드된 파일은 skip 됩니다 (--no-progress 떼고 보면 보임).

6. RDS 에서 복원 — rds_restore_database

이제 본 게임. RDS 의 msdb.dbo.rds_restore_database 저장 프로시저를 호출해요. STRIPE 백업은 콤마로 ARN 을 이어 붙여요.

EXEC msdb.dbo.rds_restore_database
  @restore_db_name = 'MyDB',
  @s3_arn_to_restore_from = 
    'arn:aws:s3:::my-mssql-migration/mssql/MyDB_full_01.bak,
     arn:aws:s3:::my-mssql-migration/mssql/MyDB_full_02.bak,
     arn:aws:s3:::my-mssql-migration/mssql/MyDB_full_03.bak,
     arn:aws:s3:::my-mssql-migration/mssql/MyDB_full_04.bak',
  @with_norecovery = 1;  -- 차등 백업을 뒤이어 적용할 거라면 1

@with_norecovery = 1 로 두면 DB 가 RESTORING 상태로 남아서, 이어서 차등 백업을 추가 복원할 수 있어요. 마지막 복원에만 0 으로 두면 DB 가 ONLINE 으로 올라옵니다.

복원은 비동기로 큐에 들어가요. 진행 상황은 따로 조회.

EXEC msdb.dbo.rds_task_status @db_name = 'MyDB';

진행 단계는 lifecycle 컬럼으로 봐요.

✅ SUCCESS 가 뜨면 풀백업 복원 끝.

7. 컷오버 — 차등 백업으로 다운타임 줄이기

풀백업이 큰 DB 라면, 풀백업을 먼저 옮겨놓고 + 컷오버 직전에 차등 백업만 다시 옮기는 방식으로 다운타임을 분 단위로 줄일 수 있어요.

7-1. 원본에서 차등 백업

BACKUP DATABASE [MyDB]
TO DISK = N'D:\backup\MyDB_diff_01.bak',
   DISK = N'D:\backup\MyDB_diff_02.bak'
WITH 
  DIFFERENTIAL,
  COMPRESSION,
  CHECKSUM,
  STATS = 5;

차등 백업은 풀백업 이후 변경된 페이지만 떠요. 보통 풀의 1~10% 크기로 끝납니다.

7-2. S3 업로드 후 RDS 에 차등 복원

EXEC msdb.dbo.rds_restore_database
  @restore_db_name = 'MyDB',
  @s3_arn_to_restore_from = 
    'arn:aws:s3:::my-mssql-migration/mssql/MyDB_diff_01.bak,
     arn:aws:s3:::my-mssql-migration/mssql/MyDB_diff_02.bak',
  @type = 'DIFFERENTIAL',
  @with_norecovery = 0;  -- 마지막 복원이므로 ONLINE 으로 올림

@type = 'DIFFERENTIAL' 가 핵심. @with_norecovery = 0 으로 끝내면 DB 가 ONLINE 으로 올라와요.

💡 RDS for SQL Server 의 차등 복원은 비교적 최근에 추가된 기능이에요. 인스턴스의 엔진 버전 이 차등 복원을 지원하는지 사전 확인하세요. 안 되면 풀백업만 반복하거나 컷오버 시간을 길게 잡아야 해요.

8. 복원 후 반드시 챙길 것 — 로그인 / 사용자 매핑

.bak 으로 복원하면 DB 사용자(users)는 들어오지만, 서버 레벨의 로그인(logins) 은 안 들어와요. 원본 서버에 있던 로그인을 RDS 마스터에 똑같이 만들고, DB 사용자와 다시 매핑해줘야 해요.

-- 1. RDS 에 로그인 생성 (원본에 있던 SQL 로그인 그대로)
CREATE LOGIN [app_user] WITH PASSWORD = '<APP_USER_PASSWORD>';

-- 2. 복원된 DB 의 user 를 새 로그인에 다시 묶기 (orphaned user 정리)
USE [MyDB];
EXEC sp_change_users_login 'Update_One', 'app_user', 'app_user';

-- 또는 ALTER USER ... WITH LOGIN = ...
ALTER USER [app_user] WITH LOGIN = [app_user];

✅ 검증: EXEC sp_change_users_login 'Report'; 로 고아 사용자가 남아있는지 한 번 더 확인.

⚠️ Windows 인증 기반 로그인은 RDS 가 Active Directory 연동(SQLSERVER_AUDIT / SQLSERVER_AD 옵션)되어 있어야 매핑 가능해요. 단순 SQL 로그인이면 위 절차로 충분.

9. 데이터 일관성 검증 — 한 번 더

복원이 끝나면 마지막으로 데이터 검증 한 사이클 돌려요.

-- 무결성 검사
DBCC CHECKDB ([MyDB]) WITH NO_INFOMSGS;

-- 테이블별 row count 스냅샷 비교용
SELECT s.name + '.' + t.name AS table_name, p.rows
FROM sys.tables t
JOIN sys.schemas s ON t.schema_id = s.schema_id
JOIN sys.partitions p ON t.object_id = p.object_id
WHERE p.index_id IN (0,1)
ORDER BY p.rows DESC;

같은 쿼리를 원본 / 대상 양쪽에서 돌려서 결과를 비교해요. 큰 테이블 몇 개만이라도 row count 와 MAX(updated_at), CHECKSUM_AGG() 정도는 맞춰보고 컷오버 결정.

10. 자주 깨지는 포인트 — 체크리스트

이번 작업하면서 한 번씩 다 밟아봤던 함정들이에요. 미리 알면 안 밟습니다.

• S3 버킷 리전과 RDS 인스턴스 리전 일치 했는가
• IAM Role 의 trust principal 이 rds.amazonaws.com 인가
• KMS 암호화 버킷이면 IAM Role 에 kms:Decrypt 권한 있는가
• 옵션 그룹의 IAM_ROLE_ARN 값이 위 Role 의 ARN 과 정확히 일치하는가
• STRIPE 백업의 모든 파일이 S3 에 다 올라갔는가 (하나라도 빠지면 복원 실패)
• rds_task_status 의 lifecycle 이 SUCCESS 인지 확인했는가
• 차등 복원 전에 풀 복원이 NORECOVERY 로 끝났는가
• 복원 후 로그인 재생성 + 고아 사용자 매핑까지 했는가
• DBCC CHECKDB 클린인가
• 원본/대상 row count 스냅샷 비교 완료했는가

11. 정리

Native Backup/Restore 는 단계가 많아 보이지만, 한 번 셋업해두면 명령어 몇 줄로 끝나는 깔끔한 흐름이에요. 핵심만 다시 짚으면

• 옵션 그룹 + IAM Role + S3 버킷 → 한 번만 세팅
• 풀백업은 STRIPE + COMPRESSION + CHECKSUM 으로
• 컷오버는 NORECOVERY 풀백업 → 차등 백업 패턴으로 다운타임 단축
• 복원 후 로그인 재생성 + DBCC + row count 비교 까지 해야 끝난 거예요

일단 오늘은 여기까지…..
다음 글에서는 같은 마이그레이션을 AWS DMS + CDC 로 풀어서, “다운타임 거의 0” 컷오버를 어떻게 구성하는지 정리해볼게요.

← 이전 글: (1/5) 방법 비교 — 6가지 중에서 고르기 ｜ 다음 글 →: (3/5) DMS + CDC 무중단 컷오버 — 풀로드 후 변경분 따라잡기

📚 MSSQL → AWS RDS 마이그레이션 시리즈 (전체 5편)

1. 방법 비교 — 6가지 중에서 고르기 ← 지금 글
2. Native Backup/Restore 실전 — 옵션 그룹부터 컷오버까지
3. DMS + CDC 무중단 컷오버 — 풀로드 후 변경분 따라잡기
4. 변경분 계속 쌓기 — NORECOVERY 체인과 CDC-only 결합
5. 정합성 트러블슈팅 — 케이스별 8가지 함정

내부망에 있던 MSSQL DB 한 덩어리를 AWS RDS for SQL Server 로 그대로 옮겨야 했어요. 다행히 양쪽은 S2S VPN 으로 이미 통신이 되는 상태였고, 조건은 두 가지였어요. 첫째 원본을 그대로 옮길 것(스키마/식별자/인덱스 보존), 둘째 운영 중인 원본 DB에 부하를 주지 말 것. 이 글은 그때 검토했던 방법들과 최종 선택, 그리고 건수별 소요 시간 추정을 정리한 글이에요.

💡 이 글에서 다루는 것

• 내부망 → AWS RDS for SQL Server 마이그레이션 방법 6가지 비교
• “부하 방지” 관점에서 각 방법이 원본에 주는 영향
• 1만 건 / 100만 건 / 1억 건 기준 예상 소요 시간
• 최종 추천: 어떤 상황엔 무엇을 골라야 하는가

1. 전제 — 우리 환경 정리

먼저 작업 시작 전에 짚어둔 전제예요.

여기서 가장 중요한 두 가지는 “그대로” 와 “부하 없이” 예요. 이 두 단어가 방법 선택의 거의 모든 기준이 돼요.

2. 옵션 정리 — 6가지 방법

먼저 후보를 다 펼쳐놓고 시작할게요. 표 한 번 보고 본문으로 들어가요.

⚠️ 표의 별 개수 의미 — “보존” 은 많을수록 좋음(원본 그대로), “부하” 와 “네트워크 부담” 은 많을수록 나쁨(원본/네트워크에 부담). 별 1개가 좋은 것일 수도, 나쁜 것일 수도 있어요. 헷갈리지 않게 ⭐ 옆에 (낮음)/(높음) 으로도 표시했어요.

3. 방법 1 — Native Backup/Restore (.bak → S3 → RDS)

MSSQL 의 정공법. 원본에서 BACKUP DATABASE 로 .bak 파일을 만들고, S3 에 올린 다음, RDS 의 저장 프로시저 msdb.dbo.rds_restore_database 로 복원하는 방법이에요.

-- 원본 (내부망 MSSQL)
BACKUP DATABASE [MyDB]
TO DISK = N'D:\backup\MyDB_full.bak'
WITH COMPRESSION, CHECKSUM, STATS = 10;

# S3 업로드 (내부망 jump 서버에서 → S2S VPN 통해 S3 endpoint)
aws s3 cp D:\backup\MyDB_full.bak s3://my-mssql-migration/MyDB_full.bak

-- AWS RDS for SQL Server 에서 실행
EXEC msdb.dbo.rds_restore_database
  @restore_db_name = 'MyDB',
  @s3_arn_to_restore_from = 'arn:aws:s3:::my-mssql-migration/MyDB_full.bak';

진행상황은 EXEC msdb.dbo.rds_task_status @db_name='MyDB'; 로 따라갈 수 있어요.

장점

• 스키마/인덱스/제약/식별자 시드/CLR 어셈블리 전부 그대로 보존돼요. “그대로 넣는다” 의 끝판왕.
• 원본 부하는 풀백업 시점의 디스크 I/O 만. row-by-row 쿼리가 없으니 운영 쿼리에 영향이 작아요.
• 큰 DB 도 압축 백업이면 보통 1/4~1/8 로 줄어들어 전송도 빨라요.

단점

• RDS 가 Native Backup/Restore 옵션 그룹 활성화 + S3 권한이 사전에 세팅되어 있어야 해요.
• AWS RDS for SQL Server 에서 differential 복원은 일정 버전 이상부터 지원돼요. 풀백업 + 차등은 미리 RDS 버전 확인.
• 한 파일이 큼 → 전송 중 끊기면 처음부터 다시 (멀티파트 업로드로 어느 정도 보완 가능).

✅ “그대로” 가 가장 잘 지켜지는 방법. one-shot 마이그레이션이라면 1순위 후보.

4. 방법 2 — AWS DMS (Database Migration Service)

AWS 가 만든 마이그레이션 전용 매니지드 서비스. Replication Instance 를 띄우고, 소스(내부망 MSSQL) / 타깃(RDS for SQL Server) 엔드포인트를 등록한 뒤, Full Load 또는 Full Load + CDC 로 돌려요.

[내부망 MSSQL] --(S2S VPN)--> [DMS Replication Instance] --> [AWS RDS for SQL Server]

장점

• 테이블/스키마 단위로 병렬 로드 가능. 큰 DB 를 시간 안에 끝내고 싶을 때 좋아요.
• CDC(Change Data Capture) 를 켜면 풀 로드 후 변경분만 따라잡아 줘서 다운타임 거의 0 컷오버 가능.
• 진행률/에러/지표가 콘솔에 다 보임 → 운영하기 편함.

단점

• 보존 측면에서 인덱스/식별자 시드/제약을 별도 챙겨야 해요. DMS 는 데이터 위주로 옮기고, 보조 인덱스는 옵션으로 따로 만들거나 컷오버 후 생성하는 게 일반적이에요. “그대로” 라는 관점에선 백업/복원만 못해요.
• 풀로드 도중 원본에 장기 SELECT 가 걸려요. 트랜잭션 격리 수준/락 옵션을 잘못 두면 오히려 원본에 부담.
• DMS Replication Instance 비용이 따로 들어요.

💡 “운영 중인 DB 를 무중단에 가깝게 옮기고 싶다” 가 강한 요건이면 DMS + CDC 가 최선.

5. 방법 3 — bcp (Bulk Copy Program)

MSSQL 의 고전 명령어. 테이블 단위로 원본에서 파일로 추출(bcp out)하고, 대상에 일괄 적재(bcp in 또는 BULK INSERT)해요.

# 원본에서 추출 (네이티브 포맷이 가장 빠르고 안전)
bcp MyDB.dbo.Orders out Orders.dat ^
  -S 192.168.x.x -U sa -P <PASSWORD> -n -b 10000

# AWS RDS 로 적재
bcp MyDB.dbo.Orders in Orders.dat ^
  -S mydb.xxxx.ap-northeast-2.rds.amazonaws.com -U admin -P <PASSWORD> -n -b 10000 -h "TABLOCK"

옵션 의미는 짧게.

• -n : 네이티브(바이너리) 포맷. 파싱 비용이 적어서 빠르고 타입 오차도 없음.
• -b 10000 : 배치 사이즈. 트랜잭션을 잘게 끊어서 로그 폭주를 막아요.
• -h "TABLOCK" : 대상 테이블에 락을 잡고 적재 → minimally logged operation 으로 빨라져요.

장점

• 테이블별로 골라서 옮길 수 있음. “이 테이블만 빨리” 가 가능.
• 배치 사이즈 / 병렬 처리(여러 bcp 동시 실행) 로 부하 조절 이 비교적 쉬워요.
• AWS 서비스 의존성 없음. 사내 jump 서버에서 그냥 돌리면 끝.

단점

• 풀 DB 옮기려면 테이블/제약/인덱스 스크립트는 별도로 준비해야 함.
• 외래키/식별자 시드/순서 의존성을 직접 관리해야 함 (적재 순서, IDENTITY_INSERT 등).

⚠️ bcp 에서 부하 방지의 핵심은 -b 배치 사이즈 와 동시 실행 수 둘이에요. 무작정 -b 0 으로 한 트랜잭션에 다 밀어넣지 마세요. 트랜잭션 로그가 폭주합니다.

6. 방법 4 — SSIS / 방법 5 — SqlPackage(BACPAC)

두 개는 묶어서 짧게.

SSIS (SQL Server Integration Services)

• ETL GUI 가 익숙하다면 좋아요. 패키지 한 번 만들어두면 재실행도 편함.
• 내부적으로는 결국 bulk insert + 데이터 흐름이라 속도는 bcp 와 비슷한 급.
• 단점: 패키지를 어디서 돌릴지(SSIS 카탈로그 서버) 가 필요. 일회성 마이그레이션엔 좀 무거워요.

SqlPackage (BACPAC / DACPAC)

• SqlPackage.exe /Action:Export ... → .bacpac 파일 생성 → S3 업로드 → 대상에 Import.
• 스키마 + 데이터를 한 덩어리로 들고 다니기에 좋아요. 작은 DB 에 잘 맞음.
• 큰 DB(수십 GB 이상)는 내보내기/들여오기 둘 다 느려서 .bak 보다 불리해요.

이 둘은 원본 부하 관점에선 bcp 와 비슷하거나 살짝 더 무거워요(스키마 메타데이터 추출이 추가됨).

7. 방법 6 — Linked Server INSERT ... SELECT (비추)

가장 쉬워 보이지만, 실제론 운영 환경에서 거의 안 쓰는 방법.

-- 대상(RDS) 에서 원본을 Linked Server 로 등록 후
INSERT INTO MyDB.dbo.Orders
SELECT * FROM [SRC_LINK].[MyDB].[dbo].[Orders];

왜 비추인가

• 원본에서 한 줄 한 줄 네트워크로 끌어옴. S2S VPN 왕복 지연이 매 row 마다 발생해요.
• 원본 트랜잭션 로그/락 부담이 큼. 부하 방지가 요건인데 정반대로 가요.
• 도중에 끊기면 일관성 회복도 까다로움.

🚨 이 방법은 테스트용 작은 테이블 외엔 쓰지 마세요. 100만 건만 돼도 시간이 끝없이 늘어집니다.

8. 추천 — 우리 케이스에서의 베스트

요건이 “그대로” + “부하 최소” + “S2S VPN 있음” 이라면 결론은 명확해요.

🎉 1순위 — Native Backup/Restore (.bak → S3 → RDS)

이유.

• 원본에서 발생하는 부하는 백업 작업 한 번뿐. 그것도 디스크 I/O 라 운영 쿼리(메모리/CPU 위주)와 겹치는 영역이 작아요.
• 풀백업 시점에 원본을 점적(point-in-time) 으로 떠오므로 데이터 일관성 보장.
• 인덱스/제약/IDENTITY/통계까지 그대로 복원. 사용자 요건 그대로.

🎉 2순위 — DMS Full Load + CDC (다운타임 거의 0 이 필요한 경우)

• 컷오버 시간을 분 단위로 줄여야 한다면 DMS.
• 단, “그대로” 가 아니라 “내용은 같지만 인덱스 등은 새로 만들어도 됨” 이 허용돼야 가성비가 좋아요.

🎉 3순위 — bcp (특정 테이블만 빠르게)

• “이 테이블 하나만 옮기면 돼요” 같은 부분 마이그레이션에 최적.

✅ 사내 케이스에서 저는 1순위(Native Backup/Restore) 로 풀카피 → 컷오버 시점에 차등 백업 한 번 더 로 정리하는 패턴을 가장 선호해요.

9. 소요 시간 추정 — 1만 건 / 100만 건 / 1억 건

이 부분은 환경마다 차이가 큰 영역이에요. 그래도 기준선이 있어야 계획이 가능하니, 평균 행 크기 1KB, 인덱스 보통 수준, S2S VPN 실효 200~500Mbps 가정으로 정리할게요.

9-1. 방법별 처리량(throughput) 감

9-2. 건수별 예상 시간

⚠️ 아래 숫자는 단일 task / 단일 connection 기준 추정치예요. 실제로는 병렬화로 단축돼요.

핵심 포인트

• 1만 건 수준은 어떤 방법이든 1분 안에 끝남. 시간 차이가 거의 없음.
• 100만 건부터는 방법별로 분~시간 단위 차이가 벌어져요. bcp 와 .bak 가 압도적으로 빠름.
• 1억 건 이상은 단일 task 로 끌고 가지 말고, 테이블/파티션 단위 병렬화 가 필수.

💡 정확한 수치는 결국 행 크기, 인덱스 개수, 트랜잭션 로그 설정, 네트워크 실효 대역폭에 좌우돼요. 본격 작업 전엔 샘플 테이블 100만 건으로 한 번 실측 해두는 걸 추천해요.

10. 부하 방지 체크리스트

방법을 골랐다면, 실행 단계에서 챙겨야 할 부하 방지 포인트들이에요.

• 작업 시간대를 운영 트래픽 적은 시간 으로 잡기 (보통 새벽 2~5시)
• 원본 쿼리는 가능하면 READ UNCOMMITTED 또는 스냅샷 격리 로 잡아서 락 충돌 회피
• bcp/DMS 사용 시 배치 사이즈 를 작게 시작해서 점진적으로 키우기
• 트랜잭션 로그 백업 주기 짧게 유지 (단순 복구 모델이면 더 좋음)
• Resource Governor 로 마이그레이션 세션 CPU/IO 상한 걸기
• 백업 파일은 원본 디스크와 다른 볼륨 에 떨어뜨리기 (IO 분리)
• 작업 중 원본 DB 모니터링 대시보드 띄워두기 (CPU, IO, lock waits)

11. 정리 — 어떤 상황엔 무엇

마지막으로 상황별 추천을 한 번 더 정리해드릴게요.

저희 사내 케이스처럼 “그대로” + “부하 최소” + “S2S 가능” 이면 Native Backup/Restore 가 거의 항상 1순위예요. DMS 는 컷오버 단축이 필요할 때 더해서 쓰는 식.

일단 오늘은 여기까지…..
다음 글에서는 실제로 Native Backup/Restore 를 RDS 옵션 그룹 세팅부터 끝까지 따라가는 실전편을 정리해볼게요.

다음 글 → (2/5) Native Backup/Restore 실전 — 옵션 그룹부터 컷오버까지

💡 이 글에서 다루는 것

• GitHub 잔디(컨트리뷰션 그래프) 카운팅의 4가지 조건
• 왜 fork repo 의 커밋은 잔디로 안 잡히는지
• GitHub Support 에 “fork 분리” 요청을 보냈더니 거절당한 이야기
• 안전하게 standalone repo 로 옮기는 실제 절차 (rename → new repo → push → Pages)

1. 증상 — 잔디가 휑한데 커밋은 매일 쌓이고 있다

상황은 단순했어요.

• 블로그(https://dorumugs.github.io)에 글을 거의 매일 쓰고 push 도 잘 됨
• repo dorumugs/dorumugs.github.io 의 commit history 에는 제 커밋이 줄줄이 찍힘 (author: Jaehyun So <do***@gmail.com>)
• 그런데 https://github.com/dorumugs 프로필의 잔디는 하나도 안 채워짐

뭔가 한 가지가 어긋났다는 신호인데, 그 한 가지를 정확히 찍어내려면 GitHub 가 잔디 카운팅을 어떤 조건으로 하는지부터 알아야 했어요.

2. GitHub 잔디 카운팅의 4가지 조건

GitHub 공식 문서에 따르면 커밋이 컨트리뷰션 그래프에 잡히려면 네 조건 전부 만족해야 해요. 하나라도 어긋나면 무시당해요.

제 케이스에서 1, 2, 4 는 다 통과했는데, 3 이 문제였어요.

3. 원인 확인 — 내 repo 가 fork 였다

GitHub REST API 로 한 줄 확인해봤어요.

curl -s https://api.github.com/repos/dorumugs/dorumugs.github.io | \
  grep -E '"(fork|parent|default_branch)"'

결과는 이렇게 떨어졌어요.

  "fork": true,
  "parent": { "full_name": "mmistakes/minimal-mistakes" }
  "default_branch": "gh-pages",

✅ 범인 확인 — "fork": true.

블로그는 minimal-mistakes 테마를 기반으로 시작했는데, 그때 GitHub 의 “Fork” 버튼으로 시작해서 그대로 콘텐츠를 채워나간 거였어요. 시간이 지나면서 테마는 거의 통째로 갈아엎고 내 글이 99% 인 상태가 됐지만, GitHub 가 보기엔 여전히 mmistakes/minimal-mistakes 의 fork 였어요. 그리고 fork 의 커밋은 잔디 정책상 무조건 카운트 제외.

⚠️ fork 여부는 repo 페이지 상단의 “forked from mmistakes/minimal-mistakes” 표기로도 확인할 수 있어요. 평소에는 안 보고 지나치게 되니까 본인 repo 가 fork 인지 모르고 있는 경우가 의외로 많아요.

4. 해결 시도 1 — GitHub Support 에 detach 요청 (실패)

옛날에는 GitHub Support 에 “이 repo 를 parent 와 detach 해주세요” 라고 요청하면 처리해줬다는 글들을 봐서 support 폼을 열었어요. 라우팅은 이런 흐름이에요.

Contributions → Missing contributions → Commit → 상세 폼

제목/본문 다 채우고 제출 직전, GitHub 가 폼 아래에 자동 응답을 띄웠어요.

🚨 Forked repositories don’t count toward contribution graphs. This behavior is expected and can’t be overridden by Support. GitHub Support also can’t manually “detach” a repository from its parent fork.

To have future commits count toward your contributions graph, you’ll need to move your site to a standalone repository.

요약하면 정책이 바뀌어서 GitHub 가 더 이상 fork detach 안 해줘요. 유일한 해결책은 새 standalone repo 만들어서 옮기기.

5. 해결 시도 2 — Rename + 새 repo + push

문제는 제 사이트가 GitHub Pages user site 라서 repo 이름이 정확히 dorumugs.github.io 여야 한다는 거였어요. 즉 같은 이름을 비워주고 새로 만들어야 하는데, 기존 repo 를 그냥 삭제하면 백업이 없을 때 너무 위험해요.

그래서 좀 더 안전한 순서로 진행했어요.

1. 기존 repo 를 다른 이름으로 rename 해서 살려둠 (아카이브)
2. 같은 이름 dorumugs.github.io 로 새 standalone repo 생성
3. 로컬에서 origin 갈아끼우고 push
4. 새 repo 에서 Pages 활성화
5. 이메일 verified 확인

URL 도 보존되고 (https://dorumugs.github.io 그대로), 잘못되면 archive 로 복구 가능. 실제 진행한 과정 정리할게요.

5-0. 로컬 백업 — 사고 났을 때 살아남는 보험

뭐든 시작하기 전에 로컬에서 한 번 더 백업.

git fetch --all --tags
git bundle create ~/dorumugs.github.io-backup-$(date +%Y%m%d).bundle \
  gh-pages \
  refs/remotes/origin/gh-pages \
  refs/remotes/origin/master
git bundle verify ~/dorumugs.github.io-backup-$(date +%Y%m%d).bundle

번들 한 파일에 전체 히스토리가 들어가요. 복구할 일이 생기면 git clone <bundle파일> restored-repo 한 줄로 되돌릴 수 있어요.

만든 다음에 verify 까지 통과시켜놓으면 안심.

5-1. 기존 repo 를 rename — archive 로 살려두기

GitHub 웹에서:

• Settings → General → Repository name
• dorumugs.github.io → dorumugs.github.io-archive 로 변경
• Rename 클릭

⚠️ rename 직후 https://dorumugs.github.io 가 잠시 404 가 될 수 있어요. 다음 단계들이 끝나면 다시 살아나요.

이 시점에 원래 URL github.com/dorumugs/dorumugs.github.io 는 GitHub 가 자동으로 archive 로 리다이렉트해줘요. 새 repo 를 만드는 순간 그 리다이렉트는 끊기고 새 repo 가 그 이름을 차지.

5-2. 새 standalone repo 생성

GitHub 웹 https://github.com/new 에서 새 repo 생성.

• Owner: dorumugs
• Repository name: dorumugs.github.io ← 정확히 같은 이름
• Public
• README / .gitignore / license 추가 안 함 (빈 repo 여야 push 가 깔끔)
• ⚠️ template / fork 옵션 절대 건드리지 말기

생성된 repo 페이지가 비어있고 “Quick setup” 가이드만 보이면 정상.

5-3. 로컬 remote 갈아끼우고 push

여기서부터는 로컬 터미널에서 진행.

# origin URL 명시적으로 새 repo 가리키게
git remote set-url origin git@github.com:dorumugs/dorumugs.github.io.git

# mmistakes 가리키던 upstream 정리
git remote remove upstream

# 확인
git remote -v

브랜치 push.

git push -u origin gh-pages
git push origin refs/remotes/origin/master:refs/heads/master

• gh-pages 는 현재 사이트의 본체 브랜치. 이게 본문임
• master 는 옛날 워크플로 잔재인데 일부 콘텐츠(이미지 등)가 살아있을 수 있어서 같이 보존
• tags 는 mmistakes 테마 태그라 푸시 안 함 (git push --tags 했다가는 mmistakes 의 4.x.x 릴리스 태그들이 통째로 따라옴)

✅ 푸시 후 GitHub API 로 확인했을 때 커밋 SHA 가 그대로 보존돼야 해요. 예를 들어 가장 최근 커밋 798c73fa 가 새 repo 에서도 동일한 798c73fa 로 들어가있어야 GitHub 가 그 커밋을 잔디로 인식해줘요.

curl -s https://api.github.com/repos/dorumugs/dorumugs.github.io | \
  grep -E '"(fork|default_branch)"'
# "fork": false,
# "default_branch": "gh-pages",

fork: false 가 나오면 standalone 전환 성공.

5-4. Pages 활성화

새 repo 의 GitHub 웹에서:

• Settings → Pages
• Source: Deploy from a branch
• Branch: gh-pages / /(root)
• Save

1~5분 뒤 Actions 탭에서 “pages build and deployment” 가 success 로 끝나면 https://dorumugs.github.io 가 다시 살아나요.

확인 포인트.

• https://dorumugs.github.io HTTP 200
• 글 상세 페이지 한두 개 정상 렌더링
• 커스텀 도메인 쓰고 있었다면 도메인 설정 + CNAME 파일 재확인

5-5. 이메일 verified 확인 — 자주 빼먹는 단계

Settings → Emails 에서 commit author 로 쓰는 이메일이 verified 상태인지 확인.

⚠️ “Keep my email addresses private” 가 켜져 있으면 push 할 때 실제 이메일 대신 *****+dorumugs@users.noreply.github.com 으로 마스킹돼서 들어가요. 그러면 잔디 안 잡혀요. 끄거나, git config 를 noreply 이메일로 통일하거나, 둘 중 하나로 정리해두는 게 좋아요.

# 내 최근 커밋의 author email 확인
git log --format='%ae' -10

여기서 나오는 이메일이 GitHub Settings → Emails 의 verified 목록에 있어야 해요.

6. 검증 — 잔디가 다시 자라기까지

push 끝나고 Pages 도 잘 떴다면 이제 GitHub 가 백필을 돌려요.

🎉 fork 가 아닌 standalone repo 가 되는 순간부터 과거 커밋도 사후 카운팅 대상으로 풀려요.

만약 48시간 지나도 잔디가 안 잡힌다면 이 두 가지를 다시 확인.

• commit author email 이 정말 verified email 인지
• repo 가 정말 fork: false 인지

7. 정리

• GitHub 잔디는 fork repo 의 커밋은 무조건 제외. 정책이고, 정책상 detach 도 더 이상 안 해줘요.
• 해결책은 standalone repo 로 옮기는 것 한 가지뿐.
• user site (<username>.github.io) 인 경우 rename → new repo (같은 이름) → push 순서로 가면 URL 도 보존돼요.
• 가장 자주 빼먹는 함정은 commit author email 이 verified email 인지, Keep email private 설정 여부.

블로그 시작할 때 “Fork” 버튼을 누른 게 1년 넘게 잔디를 가렸던 셈이에요. 새 프로젝트 시작할 때는 가능하면 Use this template 가 있으면 그걸 쓰거나, 그게 없으면 fork 후 가능한 빨리 standalone 으로 옮겨두는 게 좋아요.

일단 오늘은 여기까지…..
다음 글에서는 새 repo 환경에서 이어가는 minimal-mistakes 커스터마이즈 작업 정리해볼게요.