Huny's Dev Blog
huny.dev

AWS ExtendDB 1.0 오픈소스 아키텍처 해부: DynamoDB 와이어 프로토콜·4대 스토리지 백엔드(PostgreSQL·SQLite·MongoDB·Cassandra)와 트랜잭션·아이템 크기·백업 경계 점검하기

2026년 11월 18일 AWS가 발표한 오픈소스 DynamoDB 호환 API 어댑터 ExtendDB 1.0(Apache-2.0, Rust 1.91.1)의 내부 아키텍처와 스토리지 백엔드별 동작 경계를 분석한다. Cargo 컴파일 타임 백엔드 선택 구조, PostgreSQL·SQLite(Stable)·MongoDB(Beta)·Cassandra(Experimental) 지원 등급과 차이, TransactWriteItems/TransactGetItems 잠금·스냅샷 시맨틱, 400KB 아이템 크기·PartiQL 스로틀링·backup.store 복구 경계 및 로컬 Python 사전 검증 스크립트를 정리한다.

Hun Jang
Hun Jang Nov 20, 2026

AWS ExtendDB 1.0 추상 표지 아트워크: 단일 DynamoDB 와이어 프로토콜 어댑터가 4대 스토리지 백엔드로 분기되는 개념 그래픽

AWS가 2026년 11월 18일 공식 발표한 ExtendDB 1.0은 AWS가 유지보수하는 Apache-2.0 라이선스의 오픈소스 Amazon DynamoDB 호환 API 어댑터다. 애플리케이션 코드를 수정하지 않고 AWS SDK나 AWS CLI의 엔드포인트(--endpoint-url)만 바꾸면, 자체 운영 중인 PostgreSQL·SQLite·MongoDB·Cassandra 위에서 DynamoDB 와이어 프로토콜(CRUD, Query, Scan, Batch, Transactions, Streams, TTL, PartiQL, Vector Search, Import/Export)을 그대로 실행할 수 있다.

핵심 아키텍처 판단 기준을 먼저 요약하면, ExtendDB 1.0(Rust 1.91.1 / Edition 2024)은 Amazon DynamoDB 소스 코드를 포함하지 않은 클린룸(Clean-room) 프로토콜 번역 서버이며 관리형 클라우드 서비스가 아니다. 바이너리 1개당 상호 배타적 Cargo 피처로 스토리지 백엔드 1종만 컴파일 타임에 선택해 내장하며, 1.0 기준 프로덕션 안정(Stable) 등급은 PostgreSQL 14+와 단일 노드용 SQLite뿐이고 MongoDB 7.0+는 Beta, Cassandra 4.1+는 Experimental 등급이다. 모든 백엔드에서 카탈로그당 서버 1대 원칙이 적용되며(SQLite만 파일 잠금으로 강제), TLS와 내장 SigV4 인증(접두사 AKIAEXTENDDB·ASIAEXTENDDB)이 필수다. 또한 PostgreSQL·SQLite에서는 TransactGetItems나 경합하는 TransactWriteItems가 DynamoDB와 달리 TransactionConflict를 반환하지 않고 스냅샷·행 잠금으로 직렬화되므로, 충돌 예외 기반 재시도 로직이나 PITR(미지원)·Global Tables(미구현)·PartiQL 테이블별 스로틀링 경계를 도입 전 반드시 점검해야 한다. 이 글은 2026년 11월 20일 기준 AWS 공식 발표와 ExtendDB GitHub 저장소의 README.md, Cargo.toml, 그리고 Differences from DynamoDB 명세를 교차 검증해 정리한 내용이며, 백엔드 실측 벤치마크 대신 공식 명세의 정량 수치와 로컬 Python 검증 스크립트를 기준으로 설명한다.

1. Rust 기반 단일 바이너리 아키텍처와 4대 스토리지 백엔드(Stable · Beta · Experimental)

ExtendDB 1.0 워크스페이스(version = "1.0.0")는 crates/core(순수 동기식 타입·표현식·크기 계산), crates/engine(연산 핸들러), crates/auth(SigV4 검증 및 로컬 IAM 정책 엔진), crates/cache, crates/backup-store, crates/server(HTTP, /health, /metrics, /console), crates/storage(플러거블 스토리지 트레이트) 및 4개의 백엔드 크레이트로 구성된다.

AWS ExtendDB 1.0 내부 크레이트 계층과 PostgreSQL·SQLite·MongoDB·Cassandra 4대 스토리지 백엔드별 등급 및 제약 경계 도식

1.1 컴파일 타임 백엔드 선택과 카탈로그당 단일 인스턴스 원칙

  • 바이너리당 백엔드 1종 고정: 스토리지 백엔드는 런타임 플러그인이 아니라 빌드 시점의 상호 배타적 Cargo 피처로 선택한다. 프로덕션 컨테이너 이미지는 PostgreSQL·MongoDB·Cassandra용으로 분리 배포되며, SQLite는 프로덕션 이미지 없이 소스 빌드 또는 로컬·CI 전용 개발 패키지(@extenddb/dev, extenddb/extenddb-dev)로 제공한다.
  • 카탈로그당 서버 1대(One instance per database): ExtendDB 1.0은 하나의 카탈로그에 여러 서버 인스턴스를 동시에 붙이는 멀티 서버 구성을 지원하지 않는다. SQLite는 <database>.lock 독점 잠금으로 두 번째 서버 기동을 차단하지만, PostgreSQL·MongoDB·Cassandra에서는 두 번째 서버 기동을 막지 않는다. 그럼에도 각 인스턴스가 백그라운드 워커를 중복 실행하고 자격증명·정책 캐시를 인스턴스 내부에만 두어 키 폐기(Revoke)가 다른 인스턴스에 즉시 전파되지 않으므로 반드시 1:1 구성을 지켜야 한다.
  • 필수 TLS 및 /health 프로브의 의도된 경계: extenddb init 실행 시 ~/.extenddb/tls/cert.pem 자체 서명 인증서가 생성되며 TLS를 끄면 서버가 기동을 거부한다(클라이언트는 AWS_CA_BUNDLE 설정 필요). 컨테이너용 extenddb healthcheck가 호출하는 /health 엔드포인트는 기동 직후 백엔드 장애로 모든 레플리카가 연쇄 재시작되는 것을 막기 위해 스토리지 백엔드를 조회하지 않는 Liveness 전용으로 설계되어 있다(별도 Readiness 엔드포인트는 아직 없다).

1.2 개발자용 extenddb-dev vs 프로덕션 PostgreSQL

로컬 테스트나 CI 파이프라인에서는 평문 HTTP와 기본 관리자 키를 시드하는 extenddb/extenddb-dev(또는 @extenddb/dev) SQLite 이미지를 루프백(127.0.0.1)에서만 사용해야 한다. 반면 온프레미스·프라이빗 클라우드 프로덕션에서는 PostgreSQL 14+ 백엔드가 기본이자 레퍼런스 구현이며, 38자리 숫자 정밀도와 pgvector 확장 기반의 SearchVectors를 모두 지원한다.

2. 혼동하기 쉬운 6가지 동작 경계와 전체 백엔드 비교표

AWS SDK가 에러 없이 연결된다고 해서 모든 DynamoDB 애플리케이션 가정이 그대로 유지되지는 않는다. docs/differences-from-dynamodb.md에 기록된 핵심 동작 차이는 다음과 같다.

  • TransactGetItems·TransactWriteItems는 PostgreSQL/SQLite에서 TransactionConflict를 거의 내지 않는다: DynamoDB에서는 진행 중인 쓰기 트랜잭션과 겹치는 읽기/쓰기 트랜잭션이 TransactionCanceledException(TransactionConflict)로 취소될 수 있다. 그러나 PostgreSQL은 TransactGetItems를 REPEATABLE READ 단일 스냅샷으로 실행해 쓰기 이전 상태를 정상 반환하고, TransactWriteItems 경합은 테이블·키 순서로 행 잠금을 걸어 직렬 대기 후 커밋한다(SQLite는 WAL 단일 쓰기 직렬화). 따라서 TransactionConflict 예외를 신호로 삼아 최신 데이터를 다시 읽거나 백오프하는 클라이언트 로직은 PostgreSQL/SQLite에서 기대대로 동작하지 않는다. 또한 PostgreSQL에서 존재하지 않는 핫(Hot) 키를 조건 검사·삭제하는 트랜잭션이 몰리면 해당 키를 임시 삽입·삭제하며 WAL과 데드 튜플을 남기는 점도 유의해야 한다.
  • PartiQL 요청은 테이블별 스로틀링(throttling_enabled)을 우회한다: ExtendDB는 ExecuteStatement, BatchExecuteStatement, ExecuteTransaction을 지원하지만, 서버의 토큰 버킷 스로틀러는 요청 최상위의 TableName 필드를 키로 사용한다. PartiQL 요청은 SQL 문자열 안에 테이블명이 들어 있어 최상위 TableName이 없으므로 ConsumedCapacity는 보고하되 테이블별 토큰 버킷에서는 차감·제한되지 않는다.
  • SearchVectors는 별도 호스트가 아니라 단일 엔드포인트에서 처리된다: 실제 AWS DynamoDB는 SearchVectors를 search-dynamodb.<region>.amazonaws.com으로 분리하고 기본 엔드포인트에서는 UnknownOperationException을 반환하지만, ExtendDB는 모든 연산을 단일 엔드포인트에서 서빙한다. 또한 PostgreSQL pgvector는 단정밀도(f32)로 거리를 누적하므로 약 1.8e19 초과 시 1e308로 클램핑되고, 약 3.7e-23 미만의 극소 임베딩은 노름(Norm) 언더플로로 코사인 거리가 1.0으로 붕괴해 랭킹이 사라진다(SQLite는 자체 f64 연산 사용).
  • TTL 속성명 정규식 제한과 Cassandra 비동기 GSI 충돌: SQL 인젝션 방지를 위해 TTL 속성명은 [a-zA-Z0-9._-]+ (1~255바이트)만 허용되며 60초 주기로 백엔드별 고정 배치(PostgreSQL·SQLite·MongoDB는 분당 약 100개, Cassandra는 샤드 병렬 처리로 분당 약 1,000개)만 만료 삭제한다. 특히 Cassandra 백엔드는 비동기 전파 지연(propagation_delay_ms > 0)이 설정된 GSI가 있는 테이블에서 TTL 활성화를 ValidationException으로 거부한다.
  • PITR(연속 복구) 미지원과 백업 일관성 차이: 35일 시점 복구(UpdateContinuousBackups(true), RestoreTableToPointInTime)는 모든 백엔드에서 PointInTimeRecoveryUnavailableException을 반환하며 미지원이다. 대신 [backup.store](로컬 파일시스템 또는 S3)를 설정해 CreateBackup·RestoreTableFromBackup을 사용해야 한다. PostgreSQL·SQLite·스토어 기반 MongoDB는 일관된 스냅샷을 뜨지만, 스토어 미설정 MongoDB($out)와 Cassandra(라이브 테이블 페이징)는 백업 도중 쓰기가 섞이는 비일관(Non-point-in-time) 백업이 생성된다.
  • 아이템 크기 400KB(409,600바이트) 계산 규칙과 백엔드별 예외: 숫자(N)는 1 + ceil(정수부 유효자리/2) + ceil(소수부 유효자리/2)(음수는 +1)로 계산되며(1.5는 3바이트, 3.14159는 5바이트), 단독 UpdateItem은 완성된 아이템이 아닌 문장(Statement) 기준 크기도 함께 검사한다. 반면 트랜잭션 Update와 PartiQL UPDATE는 완성된 아이템 크기만 검사하며, Cassandra는 모든 업데이트를 완성 아이템 기준으로만 검사하고 MongoDB는 업데이트 시 아이템 크기 제한을 적용하지 않는다.
비교 항목
PostgreSQL (14+)
SQLite (내장형)
MongoDB (7.0+ 레플리카셋)
Cassandra (4.1+)
1.0 지원 등급
Stable (기본·프로덕션용)
Stable (single node) (로컬·CI용)
Beta (알려진 한계 내 프로덕션)
Experimental (평가 전용)
키 숫자(N) 정밀도
최대 38자리 (DynamoDB 동일)
표준 숫자 저장
최대 34자리 (BSON Decimal128, 초과 시 ValidationException)
표준 Decimal 컬럼
다중 RANGE GSI Query
모든 RANGE 속성 조건 지원
모든 RANGE 속성 조건 지원
첫 번째 RANGE 속성만 키 조건 가능
첫 번째만 조건 가능 + ExclusiveStartKey 페이징 거부
Vector Search (SearchVectors)
지원 (pgvector 확장 필수, f32 누적)
지원 (자체 f64 연산)
미지원 (요청 거부)
미지원 (요청 거부)
TTL 처리량 및 제약
분당 약 100개 (60초 배치)
분당 약 100개 (60초 배치)
분당 약 100개 (60초 배치)
분당 약 1,000개 (비동기 GSI와 동시 사용 불가)
백업 일관성 & 연결 조건
스냅샷 일관성 보장 ([backup.store] 권장)
단일 파일 스냅샷 (&lt;db&gt;.lock 강제)
스토어 시 스냅샷 보장 · readPreference=primary & w=majority 필수
항상 인카탈로그 · 스냅샷 비일관 · 단일 DC 쓰기 필수

3. 실전 운영 설정과 로컬 Python 사전 검증 스크립트

3.1 ExtendDB 초기화 및 AWS SDK 연결 흐름

프로덕션 호스트에서는 extenddb init으로 카탈로그·인증서(~/.extenddb/tls/cert.pem)·extenddb.toml을 생성하고, 컨테이너 환경에서는 PID 1 유지를 위해 --foreground 플래그로 기동한다. 클라이언트는 AWS_CA_BUNDLE과 ExtendDB가 발급한 AKIAEXTENDDB... 키를 지정해 기존 AWS SDK를 그대로 연결한다.

3.2 Python 표준 라이브러리 기반 ExtendDB 1.0 아키텍처·아이템 크기 사전 검증기

기존 DynamoDB 워크로드를 ExtendDB 1.0으로 이관하거나 CI 백엔드로 도입하기 전에, docs/differences-from-dynamodb.md의 400KB 아이템 바이트 계산식과 4대 백엔드별 지원 경계(TLS·단일 서버·미구현 API·MongoDB 34자리 키·Cassandra 비동기 GSI+TTL 충돌·PartiQL 스로틀링 등)를 로컬에서 정적으로 점검하는 Python 스크립트(verify_extenddb_1_0.py)다.

로컬 Python 3 실행 결과, 1.5(3바이트)·3.14159(5바이트) 숫자 크기 검증, 정확히 409,600바이트 경계 검증, 위험한 MongoDB 다중 인스턴스 설정의 9가지 경계 위반 탐지, 그리고 정상 PostgreSQL + pgvector + [backup.store] 구성의 무오류 통과(ALL CHECKS PASSED)를 모두 확인했다.

4. 실무 도입 및 운영 점검 체크리스트

목적에 맞는 백엔드 등급 선택: 프로덕션 온프레미스·멀티클라우드 배포는 PostgreSQL 14+(Stable)를 기본으로 선택하고, 로컬·CI 단위 테스트는 extenddb/extenddb-dev 또는 @extenddb/dev(SQLite)를 루프백 바인딩으로만 사용한다. MongoDB(Beta)와 Cassandra(Experimental)는 키 정밀도·다중 RANGE GSI·스냅샷 백업 제한을 먼저 검증한다.

카탈로그당 1개 서버 원칙 및 --foreground 운영 적용: PostgreSQL·MongoDB·Cassandra 백엔드는 파일 잠금으로 다중 기동을 막지 않으므로 오케스트레이터 레플리카 수를 반드시 1로 고정하고, 컨테이너에서는 --foreground와 extenddb healthcheck(Liveness 전용)를 조합한다.

자체 서명 TLS 신뢰 경로 및 AKIAEXTENDDB 자격증명 분리: 서비스 DNS에 맞춰 extenddb init --tls-san ...으로 인증서를 생성하고 클라이언트에 AWS_CA_BUNDLE을 주입한다(프로덕션은 CA 서명 인증서 교체 권장). 소스 빌드 시에는 Cargo.lock 고정을 위해 --locked 옵션을 사용한다.

미구현 연산 및 트랜잭션·스로틀링 가정 제거: CreateGlobalTable·DAX·PITR(RestoreTableToPointInTime) 호출을 코드에서 제거하고, TransactGetItems/TransactWriteItems가 TransactionConflict 재시도 루프에 의존하지 않는지 확인한다. PartiQL 위주 워크로드는 테이블별 토큰 버킷 스로틀링이 적용되지 않음을 인지한다.

[backup.store] 설정 및 벡터 인덱스·TTL 호환성 확보: 벡터 인덱스가 포함된 테이블을 백업하려면 반드시 로컬 FS 또는 S3 기반 [backup.store]를 구성해야 하며, TTL 속성명이 [a-zA-Z0-9._-]+ 규칙을 만족하는지 배포 전에 점검한다.

5. 참고 자료 및 공식 출처 (2026-11-20 확인)

확인 기준일: November 20, 2026

추천 글