DynamoDB 儲存

DynamoDB 儲存實作採用 ElectroDB 的單一資料表設計模式，為 Mastra 提供高容量且高效能的 NoSQL 資料庫方案。

不支援可觀測性

DynamoDB 儲存不支援可觀測性領域。來自 MastraStorageExporter 的 Trace 無法持久化至 DynamoDB，而當 DynamoDB 是唯一的儲存 Provider 時，Studio 的可觀測性功能亦無法運作。如要啟用可觀測性，請使用複合儲存，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

項目大小限制

DynamoDB 強制執行 400 KB 的項目大小上限。儲存包含圖片等 base64 編碼附件的訊息時，可能會超出此限制。請參閱處理大型附件，了解包括將附件上載至外部儲存空間在內的解決方法。

功能

• 高效的單一資料表設計，滿足 Mastra 的所有儲存需要
• 以 ElectroDB 為基礎，提供型別安全的 DynamoDB 存取
• 支援 AWS 憑證、區域及端點
• 與供開發使用的 AWS DynamoDB Local 相容
• 儲存 Thread、Message、Eval 及 Workflow 資料
• 針對無伺服器環境最佳化
• 可按實體類型設定 TTL（存留時間），讓資料自動過期

安裝

npm

npm install @mastra/dynamodb@latest

pnpm

pnpm add @mastra/dynamodb@latest

Yarn

yarn add @mastra/dynamodb@latest

Bun

bun add @mastra/dynamodb@latest

先決條件

使用此套件前，你必須建立具有特定結構的 DynamoDB 資料表，包括主索引鍵及全域次要索引（GSI）。此配接器要求 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。

1. 執行 DynamoDB Local（例如使用 Docker）：

   docker run -p 8000:8000 amazon/dynamodb-local

2. 設定 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" }
     },
   })

   你仍須在本機 DynamoDB 執行個體中建立資料表及 GSI，例如使用指向本機端點的 AWS CLI。

參數

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（存留時間）設定。可按實體類型設定：thread、message、trace、eval、workflow_snapshot、resource、score。每個實體設定包括：enabled（boolean）、attributeName（string，預設：'ttl'）、defaultTtlSeconds（number）。

TTL（存留時間）設定

DynamoDB TTL 可讓你在指定時限後自動刪除項目，適用於以下使用情境：

• 成本最佳化：自動移除舊資料，以降低儲存成本
• 資料生命週期管理：實施保留政策以符合法規要求
• 效能：防止資料表無限增長
• 私隱合規：在指定時限後自動清除個人資料

啟用 TTL

如要使用 TTL，你必須：

1. 在 DynamoDBStore 中設定 TTL（如下所示）
2. 透過 AWS Console 或 CLI 在 DynamoDB 資料表上啟用 TTL，並指定屬性名稱（預設：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	對話 Thread
message	Thread 內的訊息
trace	可觀測性 Trace
eval	評估結果
workflow_snapshot	Workflow 狀態快照
resource	使用者／資源資料
score	評分結果

TTL 實體設定

每種實體類型均接受以下設定：

enabled:

boolean

是否為此實體類型啟用 TTL。

attributeName?:

string

用於 TTL 的 DynamoDB 屬性名稱。必須與 DynamoDB 資料表上設定的 TTL 屬性相符。預設為 'ttl'。

defaultTtlSeconds?:

number

從項目建立時間起計、以秒為單位的預設 TTL。經過此時限後，DynamoDB 會自動刪除項目。

在 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 Console：

1. 前往 DynamoDB 主控台
2. 選取你的資料表
3. 前往「Additional settings」分頁
4. 在「Time to Live (TTL)」下選取「Manage TTL」
5. 啟用 TTL 並指定屬性名稱（預設：ttl）

備註

DynamoDB 會在項目過期後 48 小時內將其刪除。在實際刪除前，項目仍可供查詢。

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 資料（Thread、Message 等）均儲存於一個 DynamoDB 資料表中。這是針對 DynamoDB 最佳化的刻意設計選擇，與關聯式資料庫的方式不同。
• 了解 GSI： 熟悉 GSI 的結構（如 TABLE_SETUP.md 所述），對了解資料擷取及潛在查詢模式非常重要。
• ElectroDB： 此配接器使用 ElectroDB 管理與 DynamoDB 的互動，在原始 DynamoDB 操作之上提供抽象層及型別安全保障。

架構方式

此儲存配接器配合 ElectroDB 採用單一資料表設計模式，這是 DynamoDB 常見且建議使用的方式。其架構有別於關聯式資料庫配接器（例如 @mastra/pg 或 @mastra/libsql）；後者通常使用多個資料表，每個資料表專門供特定實體（Thread、Message 等）使用。

此方式的主要特點包括：

• DynamoDB 原生設計： 單一資料表設計針對 DynamoDB 的鍵值及查詢能力最佳化；與模擬關聯式模型相比，通常能帶來更佳效能及容量。
• 外部資料表管理： 部分配接器可能會提供輔助函式，以透過程式碼建立資料表，但此配接器要求在使用前於外部佈建 DynamoDB 資料表及其相關全域次要索引（GSI）。如需使用 AWS CloudFormation 或 CDK 等工具的詳細指示，請參閱 TABLE_SETUP.md。此配接器只負責與預先存在的資料表結構互動。
• 透過介面保持一致： 儘管底層儲存模型不同，此配接器仍遵循與其他配接器相同的 MastraStorage 介面，確保它可在 Mastra Memory 元件中互換使用。

單一資料表中的 Mastra 資料

在單一 DynamoDB 資料表中，不同 Mastra 資料實體（例如 Thread、Message、Trace、Eval 及 Workflow）會使用 ElectroDB 管理及區分。ElectroDB 為每種實體類型定義特定模型，包括獨特的索引鍵結構及屬性。這讓配接器可在同一資料表中高效儲存及擷取不同資料類型。

例如，Thread 項目的主索引鍵可能類似 THREAD#<threadId>，而屬於該 Thread 的 Message 項目可能會使用 THREAD#<threadId> 作為分割區索引鍵，並使用 MESSAGE#<messageId> 作為排序索引鍵。TABLE_SETUP.md 詳述的全域次要索引（GSI）經過策略性設計，可支援這些不同實體的常見存取模式，例如擷取某個 Thread 的所有訊息，或查詢與某個 Workflow 相關的 Trace。

單一資料表設計的優點

此實作配合 ElectroDB 採用單一資料表設計模式，在 DynamoDB 的使用情境中具備多項優點：

1. 成本可能較低： 較少的資料表可簡化讀取／寫入容量單位（RCU/WCU）的佈建及管理，使用隨需容量時尤其如此。
2. 效能更佳： 相關資料可放置在一起，或透過 GSI 高效存取，讓常見存取模式能夠快速查找。
3. 簡化管理： 需要監察及備份的獨立資料表較少，管理工作亦相應減少。
4. 降低存取模式的複雜程度： ElectroDB 有助管理單一資料表上的項目類型及存取模式所帶來的複雜性。
5. 支援交易： 如有需要，DynamoDB 交易可跨同一資料表內儲存的不同「實體」類型使用。