DynamoDB를 로컬에서 실행할 수 있나요?

예. AWS는 Docker 이미지, Java 실행 파일, 또는 Apache Maven 의존성으로 여러분의 컴퓨터에서 실행되는 무료 다운로드판 DynamoDB인 DynamoDB Local을 제공합니다. 웹 서비스와 동일한 API를 제공하므로 오프라인에서 개발하고 테스트한 다음, 코드를 그대로 AWS로 겨누면 됩니다.

실행하는 세 가지 방법

• Docker 이미지 — 가장 흔한 선택입니다. docker run 한 번이면 로컬 포트에 endpoint가 뜹니다.
• 다운로드 아카이브 — 직접 실행하는 Java 애플리케이션입니다(JRE 필요).
• Apache Maven 의존성 — JVM 테스트 스위트에 임베드합니다.

로컬에서 개발하는 이유

데이터베이스가 여러분의 컴퓨터 안에서 자족적으로 돌아가므로 처리량, 데이터 스토리지, 데이터 전송 요금을 아끼며, 개발하는 동안 인터넷 연결도 필요 없습니다. 배포할 준비가 되면 코드에서 로컬 endpoint를 지우면 DynamoDB 웹 서비스를 가리키게 됩니다.

차이에 주의하세요

DynamoDB Local은 API를 에뮬레이션하지만 프로덕션 엔진은 아닙니다. AWS는 사용 참고 사항에 동작상의 차이를 문서화해 두었습니다(예를 들어 처리량이 강제되지 않습니다). 성능 모델이 아니라 기능적인 개발/테스트 대역으로 다루세요.

저희가 측정한 세 가지 차이

저희는 오류 페이지에 인용하는 오류를 재현하려고 DynamoDB Local 컨테이너를 계속 띄워 두므로 그 경계에 자주 부딪힙니다. 초록불이 켜진 로컬 테스트를 믿기 전에 알아 둘 만한 것이 셋 있습니다.

프로비저닝된 처리량이 전혀 강제되지 않습니다. 1 RCU로 테이블을 만들고, 3.5 KB 항목 하나를 넣고, SDK 재시도를 끈 채(maxAttempts: 1) 강력한 일관성 읽기를 루프로 돌렸습니다:

reads=5000 ok=5000 errors=0 elapsed=2.5s rate=1997/s

읽기 5,000회, 스로틀링 0회, 하나를 위해 프로비저닝된 테이블에 대고 초당 대략 2,000 읽기 단위를 지속했습니다. 같은 루프를 실제 서비스에 대고 돌리면 49번째 읽기에서 ProvisionedThroughputExceededException이 발생합니다. 용량 버그는 로컬에서 실패할 수가 없습니다.

오류 하나는 이름이 달라집니다. 같은 PartiQL INSERT를 두 번 실행하면 DynamoDB Local은 Duplicate primary key exists in table 메시지와 함께 DuplicateItem을 답합니다. 서비스는 There was an attempt to insert an item with the same primary key as an item that already exists in the DynamoDB table와 함께 DuplicateItemException을 답합니다. 이름으로 분기하는 오류 처리는 로컬에서는 통과하고 프로덕션에서는 놓칩니다.

어떤 API는 아예 없습니다. ExportTableToPointInTime은 이렇게 답합니다:

UnknownOperationException: An unknown operation was requested.

이것은 같은 호출에 대한 서비스의 오류가 아니므로, PointInTimeRecoveryUnavailableException을 가드하는 코드 경로 역시 로컬에서는 시험해 볼 수 없습니다.

더 알아보기

DynamoDB Local 가이드가 설정을 단계별로 안내하고, 로컬 및 LocalStack 연결 가이드가 GUI를 거기에 겨누는 방법을 보여 줍니다 — DynoTable은 AWS에 연결하는 것과 똑같이 로컬 endpoint에 연결합니다. 첫 쿼리는 표현식 빌더로 시험해 보세요.

참고 자료

• Setting up DynamoDB local (downloadable version) — Amazon DynamoDB Developer Guide
• DynamoDB local usage notes — Amazon DynamoDB Developer Guide
• Deploying DynamoDB locally on your computer — Amazon DynamoDB Developer Guide

위에 링크된 공식 AWS 문서를 기준으로 2026-07-13에 마지막으로 검증했습니다.

세 가지 차이는 2026-07-28에 Node v24.18.0의 @aws-sdk/client-dynamodb 3.1095.0으로 DynamoDB Local 3.3.0(amazon/dynamodb-local, Corretto 17.0.17)을 상대로 재현했습니다. 위의 출력은 한 줄도 빠짐없이 엔진 자체의 것이며 손대지 않았습니다.