DynamoDB 스토리지

DynamoDB 스토리지 구현은 다음과 같은 단일 테이블 설계 패턴을 사용하여 Mastra를 위한 고용량 및 고성능 NoSQL 데이터베이스 솔루션을 제공합니다.ElectroDB.

:::warning[관측성이 지원되지 않음]

DynamoDB 스토리지는 Observability 도메인을 지원하지 않습니다. MastraStorageExporter의 Trace를 DynamoDB에 유지할 수 없으며, DynamoDB를 유일한 스토리지 Provider로 사용하는 경우 Studio의 Observability 기능이 작동하지 않습니다. Observability을 활성화하려면 복합 스토리지를 사용하여 Observability 데이터를 ClickHouse와 같이 지원되는 Provider로 라우팅하세요. :::

:::warning[항목 크기 제한] DynamoDB의 최대 항목 크기는 400 KB입니다. 이미지와 같이 base64로 인코딩된 첨부 파일이 포함된 메시지를 저장하면 이 제한을 초과할 수 있습니다. 첨부 파일을 외부 스토리지에 업로드하는 방법을 비롯한 해결 방법은 대용량 첨부 파일 처리를 참조하세요. :::

특징
특징에 대한 직접 링크

모든 Mastra 스토리지 요구 사항을 충족하는 효율적인 단일 테이블 설계
타입 안전한 DynamoDB 액세스를 위한 ElectroDB 기반 구현
AWS 자격 증명, 리전 및 엔드포인트 지원
개발용 AWS DynamoDB Local과 호환
스레드, 메시지, 평가 및 Workflow 데이터 저장
서버리스 환경에 최적화
엔터티 유형별 자동 데이터 만료를 위한 구성 가능한 TTL(Time To Live)

설치
설치에 대한 직접 링크

npm
pnpm
Yarn
Bun

npm install @mastra/dynamodb@latest

pnpm add @mastra/dynamodb@latest

yarn add @mastra/dynamodb@latest

bun add @mastra/dynamodb@latest

전제조건
전제조건에 대한 직접 링크

이 패키지를 사용하기 전에 기본 키와 전역 보조 인덱스(GSI)를 비롯한 특정 구조의 DynamoDB 테이블을 반드시 생성해야 합니다. 이 어댑터는 DynamoDB 테이블과 GSI가 외부에서 프로비저닝되어 있어야 합니다. AWS CloudFormation 또는 AWS CDK를 사용하여 테이블을 설정하는 자세한 방법은 TABLE_SETUP.md에서 확인할 수 있습니다. 계속하기 전에 해당 지침에 따라 테이블을 구성하세요.

용법
용법에 대한 직접 링크

기본 사용법
기본 사용법에 대한 직접 링크

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을 사용한 로컬 개발에 대한 직접 링크

로컬 개발을 위해 다음을 사용할 수 있습니다.DynamoDB Local.

DynamoDB Local을 실행합니다(예: Docker 사용).
```
docker run -p 8000:8000 amazon/dynamodb-local
```

로컬 엔드포인트를 사용하도록 DynamoDBStore 구성:

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) 구성
TTL(Time to Live) 구성에 대한 직접 링크

DynamoDB TTL을 사용하면 다음 사용 사례에 대해 지정된 기간 이후 항목을 자동으로 삭제할 수 있습니다.

비용 최적화: 오래된 데이터를 자동으로 제거하여 보관 비용 절감
데이터 수명주기 관리: 규정 준수를 위한 보존 정책 구현
성능: 테이블이 무한정 커지는 것을 방지
개인정보 보호 규정 준수: 특정 기간이 지나면 개인정보를 자동으로 삭제합니다.

TTL 활성화
TTL 활성화에 대한 직접 링크

TTL을 사용하려면 다음을 수행해야 합니다.

DynamoDBStore에서 TTL 구성(아래 표시)
DynamoDB 테이블에서 TTL 활성화AWS 콘솔 또는 CLI를 통해 속성 이름 지정(기본값:ttl)

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 엔터티 구성
TTL 엔터티 구성에 대한 직접 링크

각 엔터티 유형은 다음 구성을 허용합니다.

enabled:

boolean

이 엔터티 유형에 TTL을 활성화할지 여부입니다.

attributeName?:

string

TTL에 사용할 DynamoDB 속성 이름입니다. DynamoDB 테이블에 구성된 TTL 속성과 일치해야 합니다. 기본값은 'ttl'입니다.

defaultTtlSeconds?:

number

항목 생성 시점부터 계산하는 기본 TTL(초)입니다. 이 시간이 지나면 DynamoDB가 항목을 자동으로 삭제합니다.

DynamoDB 테이블에서 TTL 활성화
DynamoDB 테이블에서 TTL 활성화에 대한 직접 링크

코드에서 TTL을 구성한 후에는 DynamoDB 테이블 자체에서 TTL을 활성화해야 합니다.

AWS CLI 사용:

aws dynamodb update-time-to-live \
  --table-name mastra-single-table \
  --time-to-live-specification "Enabled=true, AttributeName=ttl"

AWS 콘솔 사용:

DynamoDB 콘솔로 이동합니다.
테이블을 선택합니다.
"추가 설정" 탭으로 이동합니다.
"TTL(Time to Live)"에서 "TTL 관리"를 선택합니다.
TTL을 활성화하고 속성 이름을 지정합니다(기본값: ttl).

노트

DynamoDB는 만료 후 48시간 이내에 만료된 항목을 삭제합니다. 항목은 실제로 삭제될 때까지 쿼리 가능한 상태로 유지됩니다.

AWS IAM 권한
AWS IAM 권한에 대한 직접 링크

코드를 실행하는 IAM 역할 또는 사용자에게는 지정된 DynamoDB 테이블 및 해당 인덱스와 상호 작용할 수 있는 적절한 권한이 필요합니다. 다음은 샘플 정책입니다. ${YOUR_TABLE_NAME}을 실제 테이블 이름으로 바꾸고 ${YOUR_AWS_REGION}과 ${YOUR_AWS_ACCOUNT_ID}를 적절한 값으로 바꾸세요.

{
  "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의 가이드를 따르세요.
단일 테이블 설계: 모든 Mastra 데이터(스레드, 메시지 등)는 하나의 DynamoDB 테이블에 저장됩니다. 이는 관계형 데이터베이스 접근 방식과 달리 DynamoDB에 최적화된 의도적인 설계 선택입니다.
GSI 이해: 데이터 조회와 가능한 쿼리 패턴을 이해하려면 GSI가 어떻게 구성되어 있는지(TABLE_SETUP.md) 숙지하는 것이 중요합니다.
ElectroDB: 어댑터는 ElectroDB를 사용하여 DynamoDB와의 상호 작용을 관리하고 원시 DynamoDB 작업에 대한 추상화 계층과 유형 안전성을 제공합니다.

아키텍처 접근 방식
아키텍처 접근 방식에 대한 직접 링크

이 스토리지 어댑터는 DynamoDB에서 일반적으로 사용되고 권장되는 접근 방식인 ElectroDB 기반의 단일 테이블 설계 패턴을 사용합니다. 이는 일반적으로 스레드, 메시지 등 특정 엔터티 전용 테이블을 여러 개 사용하는 관계형 데이터베이스 어댑터(예: @mastra/pg 또는 @mastra/libsql)와 구조적으로 다릅니다. 이 접근 방식의 주요 측면:

DynamoDB 네이티브: 단일 테이블 설계는 DynamoDB의 키-값 및 쿼리 기능에 최적화되어 있어 관계형 Model을 모방하는 방식보다 성능과 확장성이 우수한 경우가 많습니다.
외부 테이블 관리: 코드를 통해 테이블을 생성하는 도우미 기능을 제공하는 일부 어댑터와 달리, 이 어댑터는 사용 전에 DynamoDB 테이블과 관련 전역 보조 인덱스(GSI)가 외부에서 프로비저닝되어 있어야 합니다. AWS CloudFormation 또는 CDK 같은 Tool을 사용하는 자세한 방법은 TABLE_SETUP.md를 참조하세요. 어댑터는 기존 테이블 구조와의 상호 작용만 담당합니다.
인터페이스를 통한 일관성: 기반 스토리지 Model은 다르지만 이 어댑터는 다른 어댑터와 동일한 MastraStorage 인터페이스를 준수하므로 Mastra Memory 컴포넌트 내에서 상호 교환하여 사용할 수 있습니다.

단일 테이블의 마스트라 데이터
단일 테이블의 마스트라 데이터에 대한 직접 링크

단일 DynamoDB 테이블 내에서 다양한 Mastra 데이터 엔터티(예: 스레드, 메시지, 추적, 평가 및 Workflow)가 ElectroDB를 사용하여 관리되고 구별됩니다. ElectroDB는 고유한 키 구조와 속성을 포함하는 각 엔터티 유형에 대한 특정 Model을 정의합니다. 이를 통해 어댑터는 동일한 테이블 내에서 다양한 데이터 유형을 효율적으로 저장하고 검색할 수 있습니다.

예를 들어 Thread 항목의 기본 키는 THREAD#<threadId>와 같을 수 있고, 해당 스레드에 속한 Message 항목은 THREAD#<threadId>를 파티션 키로, MESSAGE#<messageId>를 정렬 키로 사용할 수 있습니다. TABLE_SETUP.md에 자세히 설명된 전역 보조 인덱스(GSI)는 스레드의 모든 메시지를 가져오거나 Workflow와 연관된 Trace를 쿼리하는 등 서로 다른 엔터티 전반에서 일반적인 액세스 패턴을 지원하도록 전략적으로 설계되었습니다.

단일 테이블 디자인의 장점
단일 테이블 디자인의 장점에 대한 직접 링크

이 구현에서는 ElectroDB와 함께 단일 테이블 설계 패턴을 사용하며, 이는 DynamoDB 컨텍스트 내에서 여러 가지 이점을 제공합니다.

비용 절감(잠재적으로):특히 온디맨드 용량의 경우 테이블 수가 적으면 RCU/WCU(읽기/쓰기 용량 단위) 프로비저닝 및 관리가 단순화됩니다.
더 나은 성능:관련 데이터는 GSI를 통해 효율적으로 같은 위치에 배치되거나 액세스될 수 있으므로 일반적인 액세스 패턴을 빠르게 조회할 수 있습니다.
단순화된 관리:모니터링하고 백업해야 할 개별 테이블이 줄어들고 관리할 항목도 줄어듭니다.
액세스 패턴의 복잡성 감소:ElectroDB는 단일 테이블에서 항목 유형 및 액세스 패턴의 복잡성을 관리하는 데 도움이 됩니다.
거래 지원:DynamoDB 트랜잭션은 필요한 경우 동일한 테이블 내에 저장된 다양한 "엔티티" 유형에서 사용할 수 있습니다.

특징특징에 대한 직접 링크

설치설치에 대한 직접 링크

전제조건전제조건에 대한 직접 링크

용법용법에 대한 직접 링크

기본 사용법기본 사용법에 대한 직접 링크

DynamoDB Local을 사용한 로컬 개발DynamoDB Local을 사용한 로컬 개발에 대한 직접 링크

매개변수매개변수에 대한 직접 링크

id:

config.tableName:

config.region?:

config.endpoint?:

config.credentials?:

config.ttl?:

TTL(Time to Live) 구성TTL(Time to Live) 구성에 대한 직접 링크

TTL 활성화TTL 활성화에 대한 직접 링크

지원되는 엔터티 유형지원되는 엔터티 유형에 대한 직접 링크

TTL 엔터티 구성TTL 엔터티 구성에 대한 직접 링크

enabled:

attributeName?:

defaultTtlSeconds?:

DynamoDB 테이블에서 TTL 활성화DynamoDB 테이블에서 TTL 활성화에 대한 직접 링크

AWS IAM 권한AWS IAM 권한에 대한 직접 링크

주요 고려사항주요 고려사항에 대한 직접 링크

아키텍처 접근 방식아키텍처 접근 방식에 대한 직접 링크

단일 테이블의 마스트라 데이터단일 테이블의 마스트라 데이터에 대한 직접 링크

단일 테이블 디자인의 장점단일 테이블 디자인의 장점에 대한 직접 링크

특징
특징에 대한 직접 링크

설치
설치에 대한 직접 링크

전제조건
전제조건에 대한 직접 링크

용법
용법에 대한 직접 링크

기본 사용법
기본 사용법에 대한 직접 링크

DynamoDB Local을 사용한 로컬 개발
DynamoDB Local을 사용한 로컬 개발에 대한 직접 링크

매개변수
매개변수에 대한 직접 링크

TTL(Time to Live) 구성
TTL(Time to Live) 구성에 대한 직접 링크

TTL 활성화
TTL 활성화에 대한 직접 링크

지원되는 엔터티 유형
지원되는 엔터티 유형에 대한 직접 링크

TTL 엔터티 구성
TTL 엔터티 구성에 대한 직접 링크

DynamoDB 테이블에서 TTL 활성화
DynamoDB 테이블에서 TTL 활성화에 대한 직접 링크

AWS IAM 권한
AWS IAM 권한에 대한 직접 링크

주요 고려사항
주요 고려사항에 대한 직접 링크

아키텍처 접근 방식
아키텍처 접근 방식에 대한 직접 링크

단일 테이블의 마스트라 데이터
단일 테이블의 마스트라 데이터에 대한 직접 링크

단일 테이블 디자인의 장점
단일 테이블 디자인의 장점에 대한 직접 링크