멱등성 업서트를 위한 결정적 ULID

데이터베이스가 자동 쓰기 재시도를 금지할 때, 다른 어떤 것도 중복을 제거해주지 않기 때문에 보내는 모든 쓰기는 그 자체로 멱등성을 가져야 합니다. 이 게시물에서 다루는 기술은 결정론적 ULID입니다. 즉, 임의의 소스가 아닌, 문서를 식별하는 내용에서 파생된 문서 ID입니다. 도입하는 데 비용이 거의 들지 않으며, 구조적으로 재시도를 안전하게 만들고, 절대 어겨서는 안 되는 단 하나의 규칙이 따릅니다. 여기서는 전체 파생 과정, 이것이 방지하는 실패, 정확성을 유지하는 불변성, 그리고 적용되지 않는 경우를 다룹니다.

수동 재시도 시 랜덤 ID가 위험한 이유

ULID는 128비트 식별자입니다. 상위 비트에는 타임스탬프가, 하위 비트에는 랜덤값이 들어갑니다. 타임스탬프 접두사는 ULID가 생성 시간순으로 대략 정렬된다는 것을 의미하며, 이는 기본 키에 정말 유용합니다. 랜덤 접미사는 각 ULID를 고유하게 만드는 요소이며, 동시에 쓰기를 수동으로 재시도하는 순간 위험을 초래하는 요소이기도 합니다.

새로운 랜덤 ID를 사용하는 삽입 작업을 상상해 보세요. 쓰기 요청이 서비스를 떠나 데이터베이스에 적용된 후, 돌아오는 과정에서 확인 응답이 손실됩니다. 코드는 쓰기 성공 여부를 알 수 없으므로, 올바르게도, 재시도를 합니다. 새로운 ULID를 생성했기 때문에 재시도 요청에는 새로운 랜덤 ID가 포함됩니다. 이제 동일한 논리적 대상을 설명하는 두 개의 문서가 서로 다른 ID로 존재하게 되며, 시스템 내에서는 이들이 중복이라는 것을 알 수 없습니다. 모든 것을 올바르게 처리했지만 데이터는 손상되었습니다.

실제 MongoDB에서는 retryable writes 기능이 이 문제를 덮어줍니다. 드라이버가 트랜잭션 번호를 첨부하고 서버가 중복을 제거하므로 재시도는 안전합니다. 하지만 일부 엔진은 이 메커니즘을 지원하지 않고 retryWrites=false를 요구하며, 이 시점부터는 안전망이 사라지고 책임은 사용자에게 있습니다. 서버가 중복 제거를 해주던 때에는 괜찮았던 랜덤 ID가, 사용자가 직접 재시도하는 순간 부채가 됩니다.

id를 파생시키면 모호성이 완전히 제거됩니다

해결책은 무작위성으로 id를 생성하는 것을 멈추고, 문서를 식별하는 필드로부터 id를 파생시키는 것입니다. 동일한 논리적 문서가 항상 동일한 id를 생성한다면, 재시도된 쓰기는 동일한 id를 대상으로 하게 되고, upsert는 두 번째 행을 만드는 대신 무해한 덮어쓰기로 전환됩니다.

다국어 블로그의 경우, 게시물은 slug, 언어, 그리고 발행 시점으로 고유하게 식별됩니다. 따라서 우리는 바로 그 값들로부터 ULID를 만듭니다:

// PostID derives a stable ULID from the fields that identify a post.
// The same (slug, lang, publishedAt) always yields the same id, so an
// upsert is a no-op on every retry instead of a duplicate insert.
func PostID(slug, lang string, publishedAt int64) string {
	sum := sha256.Sum256([]byte(slug + ":" + lang))
	return buildULID(uint64(publishedAt), sum[:10])
}

여기서 두 가지 설계 결정이 핵심적인 역할을 합니다. ULID의 타임스탬프 부분은 쓰기 시점의 벽시계 시간(wall clock)이 아닌 publishedAt에서 가져오므로, 내일 동일한 게시물을 다시 수집하더라도 id는 변경되지 않습니다. 무작위 부분은 식별 필드들의 SHA-256 해시의 첫 10바이트로 대체되므로, 결정적이면서도 단일 인덱스 범위에서의 핫스팟(hot-spotting)을 피하기 위해 키스페이스(keyspace) 전반에 id를 분산시킵니다. 그 결과, 일반적인 ULID처럼 보이고 정렬되며, 여전히 의미 있는 타임스탬프 접두사를 가지면서도 콘텐츠만으로 재현 가능한 id가 만들어집니다.

이 id를 가지고, 쓰기는 이 id를 키로 사용하는 upsert가 됩니다:

// First call inserts, every retry overwrites identical data.
// Row count never grows, no server-side dedup required.
_, err := coll.UpdateByID(ctx, PostID(slug, lang, publishedAt),
	bson.M{"$set": doc},
	options.Update().SetUpsert(true),
)

이것을 한 번 실행하면 삽입됩니다. 백 번 실행해도 데이터베이스에는 정확히 하나의 문서만 존재하는데, 이는 첫 번째 호출 이후의 모든 호출이 동일한 필드를 동일한 id에 쓰기 때문입니다. 이 작업은 조정(coordination), 트랜잭션, 중복 제거 테이블 없이 멱등성을 가집니다.

멱등성은 단일 호출이 아닌 전체 파이프라인의 속성입니다

업서트(upsert)에서 멈추고 성공했다고 선언하고 싶을 수 있지만, 멱등성은 종단 간(end to end)에 걸쳐 유지되어야 하며 그렇지 않으면 전혀 유지되지 않는 것입니다. ID가 안정적이더라도 문서 본문에 새로 생성된 타임스탬프나 임의의 필드가 포함되어 있다면, 두 번의 실행은 동일한 ID에 대해 두 개의 다른 본문을 생성합니다. 중복된 행은 생기지 않겠지만, 불필요한 쓰기가 발생하고 파이프라인이 실행될 때마다 문서가 변경됩니다. 이는 변경 피드를 어지럽히고, 캐시를 무효화하며, 실제 편집과 아무 작업도 하지 않은 경우(no-op)를 구별하는 것을 불가능하게 만듭니다.

따라서 이러한 원칙은 페이로드까지 확장됩니다. 식별 콘텐츠에서 파생된 문서 내의 모든 것은 그 자체로 결정적이어야 합니다. 소스의 콘텐츠 해시가 좋은 예입니다. 입력으로부터 해시를 계산하여 문서에 저장하고, 저장된 해시가 들어오는 해시와 일치하면 쓰기 작업을 완전히 건너뜁니다. 이제 변경되지 않은 게시물을 다시 실행하는 것은 안전한 덮어쓰기일 뿐만 아니라, 아예 쓰기 작업이 없는 것입니다.

// Skip the write when nothing changed. Idempotent and cheap.
if existing != nil && existing.SourceHash == incoming.SourceHash {
	return nil // unchanged, nothing to do
}

이를 올바르게 유지하는 정신 모델은 다음과 같습니다. 동일한 입력, 동일한 ID, 동일한 본문, 그리고 이상적으로는 입력이 변경되지 않았을 때 쓰기 작업 없음. 각 계층은 그 위의 계층을 강화합니다.

반드시 지켜야 할 단 하나의 불변성

id는 publishedAt에서 파생됩니다. 이는 publishedAt가 문서의 수명 동안 불변해야 함을 의미합니다. 이것은 전체 체계가 의존하는 단 하나의 규칙이며, 이를 어기는 것은 별도의 경고가 필요할 만큼 미묘한 문제입니다.

게시물이 발행되었고, 그 id가 발행일로부터 계산되어 데이터베이스에 저장되어 있다고 가정해 봅시다. 나중에 누군가 소스에서 발행일을 수정합니다. 다음 수집 시 파생 입력이 변경되었기 때문에 새로운 id가 계산됩니다. 새로운 id를 사용한 업서트(upsert)는 완전히 새로운 문서를 삽입하고, 이전 id 하의 기존 문서는 이제 어떤 코드도 다시는 업데이트하거나 삭제하지 않을 고아(orphan)가 됩니다. 게시물을 덮어쓴 것이 아닙니다. 포크(fork)한 것입니다.

작성자가 기억할 것이라고 믿기보다는 명시적으로 이를 방지해야 합니다. 수집 시 식별 필드로 기존 문서를 조회하고, id를 다시 계산한 후, 저장된 id와 새로 계산된 id가 일치하지 않으면 쓰기를 중단하고 큰 오류를 발생시키십시오.

// If publishedAt changed, the derived id changed, and a blind upsert would
// orphan the old document. Refuse to proceed.
if existing != nil && existing.ID != PostID(slug, lang, publishedAt) {
	return fmt.Errorf("publishedAt is immutable for %s/%s: changing it orphans the old document", slug, lang)
}

본문은 id의 일부가 아니므로 언제든지 수정해도 괜찮습니다. 파생에 사용되는 필드만 동결됩니다. 작성 문서에 그 경계를 명시하여 이 규칙이 사람들이 우연히 발견하는 함정이 아니라 알려진 제약 조건이 되도록 하십시오.

결정론적 ID가 잘못된 선택일 때

이 기술은 보편적이지 않으며, 적합하지 않은 곳에 사용하면 그 자체로 문제를 일으킵니다. 이 기술은 문서가 자연스러운 정체성, 즉 어떤 문서인지를 진정으로 정의하는 필드 집합을 가질 때 효과적입니다. 블로그 게시물에는 slug, language, date가 있고, 사용자 계정에는 이메일이나 외부 ID가 있습니다.

문서에 자연 키가 없고 각 문서가 고유한 이벤트일 때는 효과가 없습니다. 독립적인 발생의 추가 전용 로그, 클릭 스트림, 동일하게 보이는 두 항목이 합법적으로 두 개의 다른 것인 작업 큐 등, 이 모든 것들은 두 번째 동일한 이벤트가 첫 번째 이벤트를 덮어쓰는 것을 원하지 않기 때문에 고유한 무작위 ID를 필요로 합니다. 이러한 경우에는 일반적인 무작위 ULID를 사용하고, 재시도 안전성이 필요하다면 기본 ID에 내장하는 대신 요청에 포함된 멱등성 키에서 가져오세요.

테스트는 단 하나의 질문입니다. 두 쓰기가 동일한 내용을 담고 있다면, 두 번째가 첫 번째를 대체해야 할까요, 아니면 그 옆에 나란히 있어야 할까요? 대체해야 한다면 ID를 파생시키세요. 나란히 있어야 한다면 무작위로 유지하세요. 전체 시스템에 대해 한 번이 아니라 컬렉션별로 이 질문에 답하세요.

노력의 대가

해시와 헬퍼 함수 하나만 있으면 되므로 노력은 거의 들지 않으며, 그 대가로 분산 시스템 버그의 한 부류 전체가 아예 발생할 수 없게 됩니다. 재시도는 동일한 ID로 수렴되기 때문에 안전합니다. 본문과 해시가 안정적이기 때문에 변경되지 않은 콘텐츠를 다시 수집하는 것은 비용이 적게 드는 무연산(no-op)이 됩니다. 또한, 자동 쓰기 재시도를 금지하는 데이터베이스의 규칙은 더 이상 극복해야 할 한계가 아니라, 쓰기 작업이 애초에 멱등성을 가지므로 이미 만족시킨 제약 조건이 됩니다. 데이터베이스의 엄격함과 여러분의 ID 체계는 결국 같은 방향을 가리키게 됩니다.