> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # DynamoDB 스토리지 DynamoDB 스토리지 구현은 다음과 같은 단일 테이블 설계 패턴을 사용하여 Mastra를 위한 고용량 및 고성능 NoSQL 데이터베이스 솔루션을 제공합니다.[ElectroDB](https://electrodb.dev/). :::warning\[관측성이 지원되지 않음] DynamoDB 스토리지는 **Observability 도메인을 지원하지 않습니다**. `MastraStorageExporter`의 Trace를 DynamoDB에 유지할 수 없으며, DynamoDB를 유일한 스토리지 Provider로 사용하는 경우 [Studio의](https://mastra.zisheng.pro/ko/docs/studio/overview) Observability 기능이 작동하지 않습니다. Observability을 활성화하려면 [복합 스토리지](https://mastra.zisheng.pro/ko/reference/storage/composite)를 사용하여 Observability 데이터를 ClickHouse와 같이 지원되는 Provider로 라우팅하세요. ::: :::warning\[항목 크기 제한] DynamoDB의 **최대 항목 크기는 400 KB입니다**. 이미지와 같이 base64로 인코딩된 첨부 파일이 포함된 메시지를 저장하면 이 제한을 초과할 수 있습니다. 첨부 파일을 외부 스토리지에 업로드하는 방법을 비롯한 해결 방법은 [대용량 첨부 파일 처리](https://mastra.zisheng.pro/ko/docs/memory/memory-processors)를 참조하세요. ::: ## 특징 - 모든 Mastra 스토리지 요구 사항을 충족하는 효율적인 단일 테이블 설계 - 타입 안전한 DynamoDB 액세스를 위한 ElectroDB 기반 구현 - AWS 자격 증명, 리전 및 엔드포인트 지원 - 개발용 AWS DynamoDB Local과 호환 - 스레드, 메시지, 평가 및 Workflow 데이터 저장 - 서버리스 환경에 최적화 - 엔터티 유형별 자동 데이터 만료를 위한 구성 가능한 TTL(Time To Live) ## 설치 **npm**: ```bash npm install @mastra/dynamodb@latest ``` **pnpm**: ```bash pnpm add @mastra/dynamodb@latest ``` **Yarn**: ```bash yarn add @mastra/dynamodb@latest ``` **Bun**: ```bash bun add @mastra/dynamodb@latest ``` ## 전제조건 이 패키지를 사용하기 전에 기본 키와 전역 보조 인덱스(GSI)를 비롯한 특정 구조의 DynamoDB 테이블을 **반드시** 생성해야 합니다. 이 어댑터는 DynamoDB 테이블과 GSI가 외부에서 프로비저닝되어 있어야 합니다. AWS CloudFormation 또는 AWS CDK를 사용하여 테이블을 설정하는 자세한 방법은 [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md)에서 확인할 수 있습니다. 계속하기 전에 해당 지침에 따라 테이블을 구성하세요. ## 용법 ### 기본 사용법 ```typescript import { Memory } from '@mastra/memory' import { DynamoDBStore } from '@mastra/dynamodb' // Initialize the DynamoDB storage const storage = new DynamoDBStore({ id: 'dynamodb', // Unique identifier for this storage instance config: { tableName: 'mastra-single-table', // Name of your DynamoDB table region: 'us-east-1', // Optional: AWS region, defaults to 'us-east-1' // endpoint: "http://localhost:8000", // Optional: For local DynamoDB // credentials: { accessKeyId: "YOUR_ACCESS_KEY", secretAccessKey: "YOUR_SECRET_KEY" } // Optional }, }) // Example: Initialize Memory with DynamoDB storage const memory = new Memory({ storage, options: { lastMessages: 10, }, }) ``` ### DynamoDB Local을 사용한 로컬 개발 로컬 개발을 위해 다음을 사용할 수 있습니다.[DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html). 1. **DynamoDB Local을 실행합니다(예: Docker 사용).** ```bash docker run -p 8000:8000 amazon/dynamodb-local ``` 2. **로컬 엔드포인트를 사용하도록 `DynamoDBStore` 구성:** ```typescript import { DynamoDBStore } from '@mastra/dynamodb' const storage = new DynamoDBStore({ id: 'dynamodb-local', config: { tableName: 'mastra-single-table', // Ensure this table is created in your local DynamoDB region: 'localhost', // Can be any string for local, 'localhost' is common endpoint: 'http://localhost:8000', // For DynamoDB Local, credentials are not typically required unless configured. // If you've configured local credentials: // credentials: { accessKeyId: "fakeMyKeyId", secretAccessKey: "fakeSecretAccessKey" } }, }) ``` 예를 들어 로컬 엔드포인트를 가리키는 AWS CLI를 사용하여 로컬 DynamoDB 인스턴스에 테이블과 GSI를 생성해야 합니다. ## 매개변수 **id** (`string`): 이 스토리지 인스턴스의 고유 식별자입니다. **config.tableName** (`string`): DynamoDB 테이블의 이름입니다. **config.region** (`string`): AWS 리전입니다. 기본값은 'us-east-1'입니다. 로컬 개발에서는 'localhost' 또는 이와 유사한 값으로 설정할 수 있습니다. **config.endpoint** (`string`): DynamoDB의 사용자 지정 엔드포인트입니다(예: 로컬 개발용 'http\://localhost:8000'). **config.credentials** (`object`): accessKeyId와 secretAccessKey가 포함된 AWS 자격 증명 객체입니다. 제공하지 않으면 AWS SDK가 환경 변수, IAM 역할(예: EC2/Lambda용) 또는 공유 AWS 자격 증명 파일에서 자격 증명을 가져옵니다. **config.ttl** (`object`): 자동 데이터 만료를 위한 TTL(Time To Live) 구성입니다. 엔터티 유형별로 구성하세요: thread, message, trace, eval, workflow\_snapshot, resource, score. 각 엔터티 구성에는 enabled(boolean), attributeName(string, 기본값: 'ttl'), defaultTtlSeconds(number)가 포함됩니다. ## TTL(Time to Live) 구성 DynamoDB TTL을 사용하면 다음 사용 사례에 대해 지정된 기간 이후 항목을 자동으로 삭제할 수 있습니다. - **비용 최적화**: 오래된 데이터를 자동으로 제거하여 보관 비용 절감 - **데이터 수명주기 관리**: 규정 준수를 위한 보존 정책 구현 - **성능**: 테이블이 무한정 커지는 것을 방지 - **개인정보 보호 규정 준수**: 특정 기간이 지나면 개인정보를 자동으로 삭제합니다. ### TTL 활성화 TTL을 사용하려면 다음을 수행해야 합니다. 1. **DynamoDBStore에서 TTL 구성**(아래 표시) 2. **DynamoDB 테이블에서 TTL 활성화**AWS 콘솔 또는 CLI를 통해 속성 이름 지정(기본값:`ttl`) ```typescript import { DynamoDBStore } from '@mastra/dynamodb' const storage = new DynamoDBStore({ name: 'dynamodb', config: { tableName: 'mastra-single-table', region: 'us-east-1', ttl: { // Messages expire after 30 days message: { enabled: true, defaultTtlSeconds: 30 * 24 * 60 * 60, // 30 days }, // Threads expire after 90 days thread: { enabled: true, defaultTtlSeconds: 90 * 24 * 60 * 60, // 90 days }, // Traces expire after 7 days with custom attribute name trace: { enabled: true, attributeName: 'expiresAt', // Custom TTL attribute defaultTtlSeconds: 7 * 24 * 60 * 60, // 7 days }, // Workflow snapshots don't expire workflow_snapshot: { enabled: false, }, }, }, }) ``` ### 지원되는 엔터티 유형 다음 엔터티 유형에 대해 TTL을 구성할 수 있습니다. | 엔터티 | 설명 | | ------------------- | ------------------------ | | `thread` | Conversation threads | | `message` | Messages within threads | | `trace` | Observability traces | | `eval` | Evaluation results | | `workflow_snapshot` | Workflow state snapshots | | `resource` | User/resource data | | `score` | Scoring results | ### TTL 엔터티 구성 각 엔터티 유형은 다음 구성을 허용합니다. **enabled** (`boolean`): 이 엔터티 유형에 TTL을 활성화할지 여부입니다. **attributeName** (`string`): TTL에 사용할 DynamoDB 속성 이름입니다. DynamoDB 테이블에 구성된 TTL 속성과 일치해야 합니다. 기본값은 'ttl'입니다. **defaultTtlSeconds** (`number`): 항목 생성 시점부터 계산하는 기본 TTL(초)입니다. 이 시간이 지나면 DynamoDB가 항목을 자동으로 삭제합니다. ### DynamoDB 테이블에서 TTL 활성화 코드에서 TTL을 구성한 후에는 DynamoDB 테이블 자체에서 TTL을 활성화해야 합니다. **AWS CLI 사용:** ```bash aws dynamodb update-time-to-live \ --table-name mastra-single-table \ --time-to-live-specification "Enabled=true, AttributeName=ttl" ``` **AWS 콘솔 사용:** 1. DynamoDB 콘솔로 이동합니다. 2. 테이블을 선택합니다. 3. "추가 설정" 탭으로 이동합니다. 4. "TTL(Time to Live)"에서 "TTL 관리"를 선택합니다. 5. TTL을 활성화하고 속성 이름을 지정합니다(기본값: `ttl`). > **노트:** DynamoDB는 만료 후 48시간 이내에 만료된 항목을 삭제합니다. 항목은 실제로 삭제될 때까지 쿼리 가능한 상태로 유지됩니다. ## AWS IAM 권한 코드를 실행하는 IAM 역할 또는 사용자에게는 지정된 DynamoDB 테이블 및 해당 인덱스와 상호 작용할 수 있는 적절한 권한이 필요합니다. 다음은 샘플 정책입니다. `${YOUR_TABLE_NAME}`을 실제 테이블 이름으로 바꾸고 `${YOUR_AWS_REGION}`과 `${YOUR_AWS_ACCOUNT_ID}`를 적절한 값으로 바꾸세요. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "dynamodb:DescribeTable", "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan", "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem" ], "Resource": [ "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}", "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}/index/*" ] } ] } ``` ## 주요 고려사항 아키텍처 세부 사항을 자세히 알아보기 전에 DynamoDB 스토리지 어댑터 작업 시 다음 주요 사항을 염두에 두십시오. - **외부 테이블 프로비저닝:** 이 어댑터를 사용하기 전에 DynamoDB 테이블과 전역 보조 인덱스(GSI)를 직접 생성하고 구성해야 합니다. [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md)의 가이드를 따르세요. - **단일 테이블 설계:** 모든 Mastra 데이터(스레드, 메시지 등)는 하나의 DynamoDB 테이블에 저장됩니다. 이는 관계형 데이터베이스 접근 방식과 달리 DynamoDB에 최적화된 의도적인 설계 선택입니다. - **GSI 이해:** 데이터 조회와 가능한 쿼리 패턴을 이해하려면 GSI가 어떻게 구성되어 있는지(`TABLE_SETUP.md`) 숙지하는 것이 중요합니다. - **ElectroDB:** 어댑터는 ElectroDB를 사용하여 DynamoDB와의 상호 작용을 관리하고 원시 DynamoDB 작업에 대한 추상화 계층과 유형 안전성을 제공합니다. ## 아키텍처 접근 방식 이 스토리지 어댑터는 DynamoDB에서 일반적으로 사용되고 권장되는 접근 방식인 [ElectroDB](https://electrodb.dev/) 기반의 **단일 테이블 설계 패턴**을 사용합니다. 이는 일반적으로 스레드, 메시지 등 특정 엔터티 전용 테이블을 여러 개 사용하는 관계형 데이터베이스 어댑터(예: `@mastra/pg` 또는 `@mastra/libsql`)와 구조적으로 다릅니다. 이 접근 방식의 주요 측면: - **DynamoDB 네이티브:** 단일 테이블 설계는 DynamoDB의 키-값 및 쿼리 기능에 최적화되어 있어 관계형 Model을 모방하는 방식보다 성능과 확장성이 우수한 경우가 많습니다. - **외부 테이블 관리:** 코드를 통해 테이블을 생성하는 도우미 기능을 제공하는 일부 어댑터와 달리, 이 어댑터는 사용 전에 **DynamoDB 테이블과 관련 전역 보조 인덱스(GSI)가 외부에서 프로비저닝되어 있어야 합니다**. AWS CloudFormation 또는 CDK 같은 Tool을 사용하는 자세한 방법은 [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md)를 참조하세요. 어댑터는 기존 테이블 구조와의 상호 작용만 담당합니다. - **인터페이스를 통한 일관성:** 기반 스토리지 Model은 다르지만 이 어댑터는 다른 어댑터와 동일한 `MastraStorage` 인터페이스를 준수하므로 Mastra `Memory` 컴포넌트 내에서 상호 교환하여 사용할 수 있습니다. ### 단일 테이블의 마스트라 데이터 단일 DynamoDB 테이블 내에서 다양한 Mastra 데이터 엔터티(예: 스레드, 메시지, 추적, 평가 및 Workflow)가 ElectroDB를 사용하여 관리되고 구별됩니다. ElectroDB는 고유한 키 구조와 속성을 포함하는 각 엔터티 유형에 대한 특정 Model을 정의합니다. 이를 통해 어댑터는 동일한 테이블 내에서 다양한 데이터 유형을 효율적으로 저장하고 검색할 수 있습니다. 예를 들어 `Thread` 항목의 기본 키는 `THREAD#`와 같을 수 있고, 해당 스레드에 속한 `Message` 항목은 `THREAD#`를 파티션 키로, `MESSAGE#`를 정렬 키로 사용할 수 있습니다. `TABLE_SETUP.md`에 자세히 설명된 전역 보조 인덱스(GSI)는 스레드의 모든 메시지를 가져오거나 Workflow와 연관된 Trace를 쿼리하는 등 서로 다른 엔터티 전반에서 일반적인 액세스 패턴을 지원하도록 전략적으로 설계되었습니다. ### 단일 테이블 디자인의 장점 이 구현에서는 ElectroDB와 함께 단일 테이블 설계 패턴을 사용하며, 이는 DynamoDB 컨텍스트 내에서 여러 가지 이점을 제공합니다. 1. **비용 절감(잠재적으로):**특히 온디맨드 용량의 경우 테이블 수가 적으면 RCU/WCU(읽기/쓰기 용량 단위) 프로비저닝 및 관리가 단순화됩니다. 2. **더 나은 성능:**관련 데이터는 GSI를 통해 효율적으로 같은 위치에 배치되거나 액세스될 수 있으므로 일반적인 액세스 패턴을 빠르게 조회할 수 있습니다. 3. **단순화된 관리:**모니터링하고 백업해야 할 개별 테이블이 줄어들고 관리할 항목도 줄어듭니다. 4. **액세스 패턴의 복잡성 감소:**ElectroDB는 단일 테이블에서 항목 유형 및 액세스 패턴의 복잡성을 관리하는 데 도움이 됩니다. 5. **거래 지원:**DynamoDB 트랜잭션은 필요한 경우 동일한 테이블 내에 저장된 다양한 "엔티티" 유형에서 사용할 수 있습니다.