DynoTable
중급5분 분량

DynamoDB Local 및 LocalStack에 연결하는 방법

로컬 DynamoDB가 실행 중이고 코드가 거기에 잘 통신하지만 — 매번 scan 스크립트를 작성하는 대신 테이블을 보고 싶습니다. 클라이언트를 로컬 endpoint에 연결하는 것은 두 가지 변경입니다. 올바른 URL을 가리키고, 일회용 자격 증명을 건네는 것. 아래 세부 사항은 사람들이 막히는 지점입니다 — 리전 네임스페이싱, 영숫자 키 규칙, 그리고 8000 대 4566 포트 구분.

DynamoDB Local vs LocalStack: 무엇에 연결하는가

둘 다 AWS 계정 없이 localhost에 DynamoDB API를 제공하지만, 서로 다른 것입니다.

따라서 연결에서 유일한 실용적 차이는 endpoint URL입니다. 독립 실행형 DynamoDB Local은 :8000, LocalStack을 통한 DynamoDB는 :4566. 그 외 모든 것 — API, 자격 증명 트릭, GUI 설정 — 은 동일합니다.

모두를 걸려 넘어지게 하는 endpoint + 더미 자격 증명 설정

AWS SDK와 CLI는 로컬 endpoint에 통신할 때조차 액세스 키와 리전을 요구하지만 — 그 값들이 실제일 필요는 없습니다. AWS 자체 문서는 이 값들이 "로컬에서 실행하기 위해 유효한 AWS 값일 필요가 없다"고 말합니다(AWS 문서).

명백하지 않은 두 가지 함정:

  • 리전/액세스 키가 데이터를 조용히 네임스페이싱합니다. -sharedDb 플래그가 없으면, DynamoDB Local은 액세스 키 ID + 리전 조합마다 별도의 myaccesskeyid_region.db 파일을 씁니다 — AWS의 정확한 명명. 앱이 사용한 것과 다른 키나 리전으로 연결하면 테이블이 사라진 것처럼 보입니다. 그저 다른 파일에 있을 뿐입니다. -sharedDb(모든 클라이언트에 대해 하나의 shared-local-instance.db)로 실행하거나, 앱이 사용하는 정확한 키 + 리전을 맞추세요.
  • 액세스 키 ID는 영숫자여야 합니다 — DynamoDB Local에서는 기호 불가. AWS 문서에 AWS_ACCESS_KEY_ID는 A–Z, a–z, 0–9만 포함할 수 있다고 명시되어 있습니다. AWS가 이것을 DynamoDB Local 2.0.0(및 1.23.0+)에서 도입했으므로, 이전 이미지에서 동작하던 특수 문자가 포함된 키가 이제 실패합니다(AWS re:Post). 아래 오류를 참조하세요.

LocalStack의 안전한 기본값은 test / test입니다. 비밀 키를 전혀 무시하며 비밀 값을 검증하지 않습니다. 실제처럼 보이는 AKIA…/ASIA… 키는 안전장치로 거부되어 더미 계정 000000000000으로 폴백됩니다 — test 같은 임의의 키가 해석되는 것과 동일한 계정입니다. test를 고수하세요.

AWS CLI로 연결(점검)

GUI를 가리키기 전에, CLI에서 endpoint가 살아 있는지 확인하세요. CLI는 로컬 endpoint를 기본값으로 할 수 없으므로, 모든 명령에 --endpoint-url을 전달합니다.

DynamoDB Local:

aws dynamodb list-tables --endpoint-url http://localhost:8000

LocalStack(동일한 명령, 다른 포트):

aws dynamodb list-tables --endpoint-url http://localhost:4566

자격 증명이 어떤 식으로든 구성되어 있으면(심지어 ~/.aws/credentials의 가짜 자격 증명이나 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY를 통한 것이라도), 이 명령은 테이블 목록을 반환합니다. 오류 없는 빈 목록은 endpoint는 동작하지만 다른 키/리전 네임스페이스를 보고 있다는 뜻입니다 — 위의 함정을 참조하세요.

DynamoDB Local GUI: DynoTable에서 로컬 테이블 탐색 및 쿼리

CLI가 동작하면, GUI에는 동일한 세 가지 값이 필요합니다. endpoint, 리전, 그리고 임의의 더미 자격 증명. CLI는 여러분이 눈으로 읽는 DynamoDB-JSON을 반환하고, GUI는 동일한 데이터를 정렬·필터링·편집할 수 있는 테이블로 렌더링합니다.

DynoTable에서, 연결을 추가하고 사용자 지정 endpoint를 설정하세요.

  • Endpoint: http://localhost:8000(DynamoDB Local) 또는 http://localhost:4566(LocalStack)
  • 리전: 앱이 사용하는 것 — 예: us-east-1. 여기서는 실제 AWS 리전이 아니라 라벨이지만, 동일한 데이터 네임스페이스에 도달하려면 일치해야 합니다.
  • 액세스 키 / 비밀 키: 아무것이나(test / test가 관례). DynamoDB Local의 액세스 키는 영숫자만 가능합니다.

거기서부터 항목을 탐색하고, Query나 Scan을 실행하며, CLI에서 손으로 JSON을 marshalling하는 대신 행을 시각적으로 편집합니다. 픽스처를 로드할 때, DynamoDB-JSON 변환기가 일반 JSON을 와이어 형식으로 바꿔주고, Query vs Scan에서 어떤 읽기를 선택할지 다룹니다. LocalStack DynamoDB 뷰어도 동일한 절차이며 — 포트만 4566으로 바뀝니다.

DynoTable은 로컬 전용 데스크톱 소프트웨어이므로, localhost를 가리키면 픽스처가 여러분의 컴퓨터에 머뭅니다. GUI 환경을 더 폭넓게 살펴보려면 DynamoDB GUI 비교를 참조하세요.

흔한 오류(리전 불일치, 포트, 자격 증명)

  • Connection refused. 잘못된 포트 — 8000은 DynamoDB Local, 4566은 LocalStack. 또한 컨테이너가 실제로 포트를 게시했는지 확인하세요(docker run -p 8000:8000 amazon/dynamodb-local). LocalStack의 경우, 서비스가 http://localhost:4566/_localstack/health에서 동작 중인지 확인하세요.
  • **DynamoDB Local에서 The Access Key ID or Security Token is Invalid. 2.0.0(및 1.23.0+) 이미지 이후로, 액세스 키 ID는 영숫자만**이어야 합니다. 이전 이미지에서 동작하던 기호가 포함된 키가 이제 실패합니다 — 문자/숫자(예: test)로 바꾸고 모든 도구를 맞추세요.
  • LocalStack에 대한 The security token included in the request is invalid. 이것은 거의 항상 자격 증명이 아니라 endpoint 문제입니다 — SDK 클라이언트가 --endpoint-url / endpoint_url을 빠뜨리고 실제 AWS endpoint에 도달했고, 그것이 여러분의 더미 키를 거부한 것입니다. 클라이언트가 실제로 http://localhost:4566을 가리키고 있는지 확인하세요.
  • SDK/CLI의 자격 증명 오류. 로컬 endpoint조차 어떤 자격 증명이 존재해야 합니다. SDK의 자격 증명 체인이 해석되도록 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY(또는 가짜 프로필)를 설정하세요.
  • http vs https. 로컬 endpoint는 일반 http입니다. https:// URL은 TLS 핸드셰이크에 실패합니다.

DynamoDB Local은 내 실제 AWS 테이블과 같은 데이터인가요?

아니요 — 로컬과 클라우드는 완전히 별개의 저장소입니다. DynamoDB Local(과 LocalStack의 DynamoDB)은 데이터를 로컬 파일이나 메모리에 보관하며, 여러분의 AWS 계정을 절대 건드리지 않고, 로컬에서는 AWS 리전/계정이 클라이언트 수준에서 지원되지 않습니다. 그것이 핵심입니다. 개발 및 테스트를 위한 것입니다. 나중에 동일한 픽스처를 클라우드에서 원한다면, AWS는 로컬에서 유효해 보이는 키/리전 값을 사용해 옮길 때 endpoint만 바꾸도록 권장합니다. 출시 전에 그 schema를 모델링하려면, 단일 테이블 설계와 GSI vs LSI에서 로컬과 prod 사이에서 바뀌지 않는 결정들을 다룹니다.

FAQ

실제 AWS 자격 증명이 필요한가요? 아니요. DynamoDB Local과 LocalStack 모두 더미 값을 받습니다. 그저 존재하고, (DynamoDB Local의 경우) 영숫자이며, 도구 전반에서 일관되기만 하면 됩니다.

도구를 바꿀 때 왜 테이블이 사라지나요? -sharedDb 없이는, DynamoDB Local이 데이터를 액세스 키 + 리전별로 별도의 myaccesskeyid_region.db 파일로 분할합니다. -sharedDb를 쓰거나 어디서나 그 값들을 동일하게 유지하세요.

포트 8000과 4566의 차이는 무엇인가요? 8000은 독립 실행형 DynamoDB Local의 기본값이고, 4566은 DynamoDB를 포함한 모든 에뮬레이트 서비스 앞에 있는 LocalStack의 단일 엣지 포트입니다.

하나의 GUI가 둘 다에 연결할 수 있나요? 예 — 둘은 동일한 DynamoDB API를 사용합니다. endpoint URL만 바뀝니다(:8000 vs :4566).

DynamoDB Local은 무료인가요? 예. AWS는 DynamoDB Local을 JAR과 Docker 이미지로 무료 배포합니다 — "프로비저닝된 처리량, 데이터 저장, 데이터 전송 비용이 없"으며, 개발 및 테스트 전용이지 프로덕션용이 아닙니다.

로컬 테이블에 대해 SQL을 실행할 수 있나요? 로컬 DynamoDB는 클라우드와 동일한 API를 사용하므로, 동일한 액세스 패턴 규칙이 적용됩니다 — 그리고 동일한 한계도. DynamoDB의 PartiQL SELECT 문법은 SELECT … FROM … WHERE … ORDER BY뿐이며 — JOIN도, GROUP BY도, COUNT/SUM/AVG 같은 그룹화 집계 함수도 없습니다(PartiQL vs SQL 참조). DynoTable의 SQL 워크벤치는 로컬을 포함한 모든 연결에 대해 그러한 분석 쿼리를 실행합니다.

DynoTable을 사용해보세요 — localhost:8000이나 localhost:4566에 곧장 연결하고 GUI로 로컬 테이블을 탐색·쿼리·편집하세요.

업데이트됨