# 일관성과 transaction 가이드 설계서 §12–§16, 결정 D-07에서 D-10까지. 플랫폼에서 기본값을 잘못 고르면 가장 비싸고, 테스트에서는 가장 안 보이는 곳이다. 여기의 실패 모드는 모두 primary가 바뀌어야 재현되기 때문이다. ## 1. 문서 하나의 atomic 연산을 먼저 쓴다 D-09: transaction은 **여러 문서에 걸친 불변식**에만 쓴다. MongoDB에서 문서 하나는 이미 atomic이다. 문서 하나를 바꾸는 update를 transaction으로 감싸면 얻는 것은 없고, session 하나, two-phase commit, 결과를 모르는 새 경우 하나가 든다. D-07: 일부만 바꿀 때는 `save()`가 아니라 update operator를 쓴다. `MongoAtomicOperations` / `MongoAtomicOperationsTemplate`은 `MongoUpdateOperator`로 operator(`$set`, `$inc`, `$push`, `$pull`, `$addToSet`, `$min`, `$max`, `$currentDate`, …)를 내놓고, `AtomicFilter` 선행 조건과 `ReturnDocumentMode`를 받는다. `save()`로 읽고-고치고-쓰면 문서 전체를 바꾼다. 그 사이에 다른 쓰기가 바꾼 필드는 조용히 사라진다. 오류 없는 lost update다. ## 2. 문서 전체를 바꾸려면 revision이 필요하다 D-08. `VersionedMongoUpdater`는 `MongoRevision`을 요구한다. Spring Data `@Version` 필드이거나, `VersionedUpdateCommand` 안의 명시적인 기대 revision 조건이다. 교체 filter에 걸린 문서가 0개여도 「할 일 없음」이 아니다. `MongoOptimisticConflictTranslator`가 둘을 구분한다. - filter에 걸린 것이 없고 그 id가 없다 → `MongoDocumentNotFoundException` - filter에 걸린 것이 없고 그 id가 있다 → `MongoOptimisticConflictException` 이 둘을 하나로 합치면 동시 덮어쓰기가 404가 된다. ## 3. 일관성 profile `MongoConsistencyProfile`은 read/write concern 쌍에 이름을 붙인다. `MongoConsistencyRegistry`가 profile을 연산이나 collection에 묶고, `MongoConsistencyBinder`가 실행할 때 적용한다. | Profile | 뜻 | 쓰는 곳 | |---|---|---| | `PRIMARY_LOCAL` | primary 읽기, local concern | rollback 구간을 견디는, 처리량이 중요한 읽기. | | `PRIMARY_MAJORITY` | primary 읽기, majority 쓰기 | 사용자가 곧바로 다시 볼 모든 것의 기본값. | | `CAUSAL_MAJORITY` | causal session 안의 majority | 따로 떨어진 연산 사이에서 자기가 쓴 것을 읽기. | | `STALE_READ_ALLOWED` | secondary 읽기 허용 | 얼마나 낡았는지 밝히는 보고·분석. | | `SNAPSHOT_TRANSACTION` | snapshot 격리 | transaction 안의 여러 문서 읽기. | profile은 힌트가 아니라 선언이다. registry는 연산마다 조회되고, profile을 등록하지 않은 연산은 기본값으로 가지 않고 거부된다. ## 4. Causal session `MongoCausalSessionContext`와 `SpringMongoCausalSessionExecutor`가 연산 사이에 cluster time과 operation time을 옮긴다. 그래서 「쓰고 나서 읽기」가 다른 노드로 가도 쓴 값을 돌려받는다. causal session이 없으면 `PRIMARY_MAJORITY`는 내구성은 주지만, 호출 두 번에 걸쳐 자기가 쓴 것을 읽는 것은 보장하지 않는다. ## 5. Transaction `MongoTransactionExecutor`는 session factory로 session을 열고, 본문을 돌리고, commit한다. `MongoTransactionProfile`은 일관성 profile, `maxCommitTime`, 재시도 예산을 가진다. 토폴로지가 중요하다. transaction에는 replica set이 필요하다. `MongoStartupValidator`는 `STANDALONE`에서 transaction을 선언한 profile을 첫 호출이 아니라 시작할 때 거부한다. ## 6. 재시도: 본문과 commit은 다른 loop다 D-10이고, 설계에서 결과가 가장 큰 규칙이다. ``` for each body attempt: open a NEW session run the body TransientTransactionError -> abort, next body attempt commit UnknownTransactionCommitResult -> retry COMMIT ONLY, same session ``` `MongoTransactionRetryCoordinator`가 정확히 이것을 구현한다. - **본문 시도마다 새 session.** abort한 뒤 session을 다시 쓰면 abort한 transaction의 상태가 재시도로 넘어간다. - **commit 결과를 모르면 본문을 다시 돌리지 않는다.** commit 결과를 모른다는 것은 commit이 이미 적용됐을 수 있다는 뜻이다. 본문을 다시 돌리면 두 번 적용된다. commit만 재시도하고, 이미 commit된 transaction에 대한 commit 재시도는 설계상 아무 일도 하지 않는다. - **예산이 두 loop를 모두 제한한다.** `MongoRetryBudget`은 시도 횟수 *와* 흐른 시간을 제한하고, 흔들림을 준 backoff(`delayBefore(attempt, random)`)를 쓴다. 힘든 primary를 재시도로 짓누르지 않는다. `MongoRetryDecision`과 `MongoRetryScope`(`…api.error`에 있다)가 무엇을 재시도해도 되는지 말한다: `MongoRetryScope.BODY`, `COMMIT_ONLY`, `NONE`. ## 7. 결과를 모르는 경우 `MongoExecutionOutcome`의 값은 여섯이고, 그중 둘은 결과를 모르는 경우라 합치면 안 된다. | 결과 | 쓰기가 일어났나? | |---|---| | `NOT_SENT` | 아니다. 재시도해도 안전하다. | | `NO_WRITE_PERFORMED` | 아니다. 서버가 답했고 아무것도 하지 않았다. | | `WRITE_CONFIRMED` | 그렇다. | | `PARTIAL_BULK_WRITE` | 일부만. `MongoBulkResult`를 본다. | | `WRITE_RESULT_UNKNOWN` | **모른다.** | | `TRANSACTION_COMMIT_UNKNOWN` | **모른다.** | 결과를 모르는 것은 실패가 아니고, 호출자에게 실패로 알리면 안 된다. 호출자는 맞춰 보거나 (`MongoCommitReconciler`가 본문이 쓴 결정적 표시를 다시 읽는다) 모른다는 사실을 그대로 위로 올린다. [runbooks/unknown-commit.md](runbooks/unknown-commit.md)를 본다. `MongoFailureContext`는 설계가 허락한 필드만 남긴다: 결과, 분류, 연산 이름, collection profile, 재시도 범위, 시도 번호. query, 문서, 값은 남기지 않는다. ## 8. 실패 변환 `DefaultMongoFailureClassifier`는 **코드보다 label을 먼저** 본다. 서버의 error label (`TransientTransactionError`, `UnknownTransactionCommitResult`, `RetryableWriteError`)이 재시도 가능 여부에 대한 권위 있는 답이다. error code는 서버 버전마다 뜻이 바뀌는 보조 신호다. `DefaultMongoFailureTranslator`가 분류를 안정된 예외 계층에 대응시킨다. 맞는 것이 없으면 driver 타입을 흘리지 않고 `MongoUnclassifiedFailureException`이 된다. ## 9. Bulk 쓰기 `MongoBulkExecutor`는 항목별 `MongoBulkItemFailure`를 담은 `MongoBulkResult`를 돌려준다. 순서 없는 bulk 쓰기가 일부 실패하면 실패가 아니라 `PARTIAL_BULK_WRITE`다. 일부 문서는 쓰였다. 결과의 항목별 결과가 어느 index가 성공하고 어느 것이 실패했는지 말해 주므로, 호출자는 처음부터 다시 하지 않고 이어서 할 수 있다. `execute(context, documentType, plan)`은 문서 하나 경로와 같이 모든 filter와 update를 document type에 맞춰 변환한다. 그래서 `@Field` 이름과 등록한 converter(`DomainDocumentId`, `BigInteger`)가 batch에서도 같은 뜻이다. 명령의 바이트 상한은 무엇이든 보내기 전에 그렇게 변환한 문서로 잰다.