llm-wiki/raw/official-docs/mongock-migration-lock-maintenance-official.md

---
title: official-doc / Mongock — Migration Tool, Multi-Instance Lock & Maintenance Status
source_type: official-doc
url: https://docs.mongock.io/
archive_url:
related_branches: [feature-mongo-runtime-baseline-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, persistence, mongodb, distributed-lock]
created: 2026-07-28
---

# Mongock — Migration Tool, Multi-Instance Lock & Maintenance Status

> Layer: `raw/` — 외부 자료(공식 문서 / 대기업 기술 블로그)의 **원문 발췌·출처 기록**.
> 본 템플릿은 `raw/official-docs/` 와 `raw/company-tech-blogs/` 두 폴더가 공유.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-mongo-runtime-baseline-contract]] | "index manifest 적용 + drift 감지를 Mongock 이 아니라 Spring Data `IndexOperations` 기반 자체 러너로 구현한다" 결정의 양면 근거 — Mongock 을 선택하지 않는 근거(유지보수 상태: 신규 개발이 후속 프로젝트 Flamingock 으로 이동, critical bug fix/security update 만 지속)와, 선택했다면 얻었을 이점(멀티 인스턴스 동시 실행을 막는 DB 영속 pessimistic lock 내장)을 모두 verbatim 으로 확보 |

## 출처

- 원본 URL: https://docs.mongock.io/
- 아카이브 URL: (미제공)
- 저자 / 조직: Mongock (Flamingock 이 관리하는 OSS 프로젝트, Apache License 2.0)
- 발행일: 불명 (문서 사이트, 지속 갱신형 — 페이지 자체에 발행일 명시 없음)
- 마지막 확인일: 2026-07-28

## 왜 저장했는지

`feature-mongo-runtime-baseline-contract` branch 는 index manifest 적용 + drift 감지를 기성 migration 도구(Mongock) 대신 Spring Data `IndexOperations` 기반 자체 러너로 구현하기로 결정하려 한다. 이 결정은 "Mongock 이 EOL(신규 개발 중단, 후속 프로젝트 Flamingock 으로 이전)이라 채택하지 않는다"는 근거와, "Mongock 을 채택했다면 멀티 인스턴스 동시 실행 방지용 DB 영속 pessimistic lock 을 별도 구현 없이 얻었을 것이다"라는 trade-off 를 모두 인지한 상태에서 내려야 한다. 이 문서는 그 양면을 모두 verbatim 으로 뒷받침한다.

## 핵심 인용

> [Introduction] "Mongock is a Java based migration tool as part of your application code for Distributed environments. It allows developers to execute safer migrations by having ownership and control over data migrations during the Application deployment process as code and data changes are shipped together."

> [경고 배너, 페이지 최상단] "Mongock will continue receiving critical bug fixes and security updates only. All innovation is happening in Flamingock." (원문에서 "critical bug fixes and security updates only" 부분은 `<b>` 태그로 강조되어 있었음 — 볼드 마크업만 제거, 문구는 원문 그대로)

> [How it works → 3. The persistent layer] "As more than one instance of the client-service may be running simultaneusly [원문 그대로, typo 포함] in the environment, it will try to execute the same migration on startup. To prevent this, Mongock uses a pesimistic lock [원문 그대로, typo 포함] that is persisted in database."

> [How it works → 3. The persistent layer] "Mongock needs to track the ChangeUnits that have been executed, so the client-service doesn't execute them twice."

> [How it works → 2. Your migration changes] "Note: From version 5, ChangeLog annotation is deprecated (though remains for backwards compatibility). It's been replaced by @ChangeUnit."

## Claims Extracted

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| MONGOCK-C1 | Mongock 은 애플리케이션 코드에 통합되어 분산 환경에서 안전한 DB migration 을 실행하는 Java 기반 도구다 | "Mongock is a Java based migration tool as part of your application code for Distributed environments. [...] as code and data changes are shipped together." | `official-vendor-doc` | Mongock 의 정의·목적 범위(코드-DB 변경 동시 배포) | ca-skeleton 의 index manifest / drift 감지 요구사항과의 기능 적합성 |
| MONGOCK-C2 | Mongock 은 신규 기능 개발이 후속 프로젝트 Flamingock 으로 이전되었고, Mongock 자체는 critical bug fix 와 security update 만 계속 받는다 | "Mongock will continue receiving critical bug fixes and security updates only. All innovation is happening in Flamingock." | `official-vendor-doc` | 2026-07-28 확인 시점 기준 Mongock 의 유지보수 상태(사실상 maintenance-mode/EOL 방향) — "기성 도구 대신 자체 러너를 택한다" 결정의 반대 방향 근거 | 정확한 EOL 날짜, critical bug fix 지원이 얼마나 오래 지속될지, Flamingock 이 ca-skeleton 에 더 적합한지 여부 — 이 페이지는 판단하지 않음 |
| MONGOCK-C3 | 멀티 인스턴스 환경에서 동시 실행되는 여러 client-service 인스턴스가 같은 migration 을 중복 실행하지 않도록, Mongock 은 DB 에 영속되는 pessimistic lock 을 사용한다 | "As more than one instance of the client-service may be running simultaneusly in the environment, it will try to execute the same migration on startup. To prevent this, Mongock uses a pesimistic lock that is persisted in database." | `official-vendor-doc` | Mongock 을 채택했을 경우 얻는 이점(멀티 인스턴스 락 내장) — "Mongock 을 선택하지 않는다"는 결정에 대한 trade-off 인지 근거 | 이 pessimistic lock 의 timeout·lease·재시도 세부 메커니즘(이 페이지는 존재만 언급, 구현 detail 은 별도 `/v5/lock/` 섹션 — 미조사) — 자체 러너로 이 lock 을 어떻게 대체할지는 이 자료가 답하지 않음 |
| MONGOCK-C4 | Mongock 은 실행된 ChangeUnit(구 ChangeLog, v5 부터 `@ChangeUnit` 으로 대체, `@ChangeLog` 는 하위호환만 유지)을 DB 에 추적해 client-service 가 동일 migration 을 두 번 실행하지 않도록 한다 | "Mongock needs to track the ChangeUnits that have been executed, so the client-service doesn't execute them twice." / "From version 5, ChangeLog annotation is deprecated (though remains for backwards compatibility). It's been replaced by @ChangeUnit." | `official-vendor-doc` | Mongock 의 changelog/변경 이력 추적 메커니즘 존재 및 명명 변화(ChangeLog→ChangeUnit) | **선언한 index manifest 와 실제 DB 인덱스 상태를 대조하는 drift 감지 기능은 이 페이지(https://docs.mongock.io/ 홈)에서 언급되지 않음 — "확인되지 않음"이며, 이는 그런 기능이 Mongock 에 없다는 증거가 아니다(부재의 증거 아님, 별도 페이지 확인 필요)** |

## Usage Boundaries

- 이 자료가 직접 증명하는 것:
  - `MONGOCK-C1`: Mongock 의 정의(Java 기반, 코드 통합형, 분산 환경 대상 migration 도구)
  - `MONGOCK-C2`: 2026-07-28 확인 시점 기준 Mongock 은 신규 개발이 중단되고 critical bug fix/security update 만 이어지는 유지보수 상태이며, 후속 프로젝트는 Flamingock
  - `MONGOCK-C3`: Mongock 이 멀티 인스턴스 동시 실행을 막기 위해 DB 영속 pessimistic lock 을 사용한다는 사실 자체
  - `MONGOCK-C4`: Mongock 이 실행된 ChangeUnit 을 DB 에 추적해 중복 실행을 막는다는 메커니즘 존재, `@ChangeLog`→`@ChangeUnit` 명명 변화(v5)
- 이 자료가 증명하지 않는 것:
  - index manifest 선언값과 실제 DB 인덱스 상태를 비교하는 **drift 감지** 기능 — 이 페이지에서 확인되지 않음(부재 확인일 뿐 미지원 확정 아님)
  - pessimistic lock 의 timeout/lease/재시도 구현 세부 — 별도 `/v5/lock/` 섹션 미조사
  - Mongock 이 MongoDB 외 CosmosDB/DocumentDB/Couchbase/DynamoDB 등에서 각각 어떤 수준으로 동작하는지의 세부 비교
  - "Mongock 대신 자체 러너를 만드는 것이 더 낫다"는 가치 판단 — 이 자료는 사실(유지보수 상태·락 메커니즘)만 제공, 선택은 branch 의 trade-off 판단 몫
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-skeleton 의 index manifest·drift 감지 요구사항을 자체 `IndexOperations` 러너로 구현할 때, Mongock 의 pessimistic lock 이 제공하던 멀티 인스턴스 보호를 어떤 메커니즘(예: 별도 advisory lock, 배포 전략 등)으로 대체할지는 별도 branch-local 결정 필요

## 메모

- Q1(유지보수 상태) 문구는 원문 HTML 에서 `<b>` 태그로 감싸인 강조 표시였음 — 강조 마크업만 제거하고 문구는 그대로 옮김.
- Q3 의 "simultaneusly"와 "pesimistic"은 원문 사이트의 오탈자로, 그대로 보존함(교정하지 않음).
- 이 페이지는 Mongock v5 "How it works" 개요 페이지이며, lock 메커니즘·drift 감지 여부에 대한 상세는 사이드바의 `/v5/lock/`, `/v5/technical-overview` 등 하위 페이지에 있을 수 있음 — 미조사, 추후 필요 시 별도 dispatch.
- WebFetch 도구의 1차 결과는 소형 모델이 "원문 그대로"라 표시했음에도 실제로는 문장이 재구성(paraphrase)되어 있었음(예: "Existing deployments can migrate seamlessly" vs 실제 원문 "Existing Mongock deployments migrate automatically"). 이에 따라 `curl` 로 raw HTML 을 별도 확보해 tag 만 제거한 텍스트를 self-grep 대상으로 사용했고, 본 문서의 모든 인용은 그 raw HTML 대조본 기준.

## 관련

- 같은 주제 다른 official-doc: (Mongock lock/technical-overview 하위 페이지 미조사 — 필요 시 추가 dispatch)
- 이 자료를 인용한 wiki 요약: (아직 없음, `/ingest` 이후 생성 시 추가)