Storage DynamoDB

L'implémentation du Storage DynamoDB fournit à Mastra une solution de base de données NoSQL haute capacité et performante, fondée sur un modèle à table unique avec ElectroDB.

Observability non prise en charge

Le Storage DynamoDB ne prend pas en charge le domaine Observability. Les Traces de MastraStorageExporter ne peuvent pas être rendues persistantes dans DynamoDB, et les fonctionnalités Observability de Studio ne fonctionnent pas si DynamoDB est votre seul Provider de Storage. Pour activer Observability, utilisez le Storage composite afin d'acheminer ses données vers un Provider pris en charge tel que ClickHouse.

Limite de taille des éléments

DynamoDB impose une taille maximale de 400 Ko par élément. Cette limite peut être dépassée lors du stockage de messages contenant des pièces jointes encodées en base64, telles que des images. Consultez Gestion des pièces jointes volumineuses pour découvrir des solutions, notamment l'envoi des pièces jointes vers un Storage externe.

Fonctionnalités

• Architecture à table unique efficace pour tous les besoins de Storage de Mastra
• Repose sur ElectroDB pour un accès à DynamoDB avec typage sûr
• Prend en charge les identifiants, les régions et les endpoints AWS
• Compatible avec AWS DynamoDB Local pour le développement
• Stocke les données Thread, Message, Eval et Workflow
• Optimisée pour les environnements serverless
• TTL (Time To Live) configurable pour l'expiration automatique des données par type d'entité

Installation

npm

npm install @mastra/dynamodb@latest

pnpm

pnpm add @mastra/dynamodb@latest

Yarn

yarn add @mastra/dynamodb@latest

Bun

bun add @mastra/dynamodb@latest

Prérequis

Avant d'utiliser ce package, vous devez créer une table DynamoDB possédant une structure précise, notamment des clés primaires et des Global Secondary Indexes (GSI). Cet adaptateur exige que la table DynamoDB et ses GSI soient provisionnés en externe.

Des instructions détaillées pour configurer la table au moyen d'AWS CloudFormation ou d'AWS CDK sont disponibles dans TABLE_SETUP.md. Assurez-vous que votre table est configurée conformément à ces instructions avant de continuer.

Utilisation

Utilisation de base

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,
  },
})

Développement local avec DynamoDB Local

Pour le développement local, vous pouvez utiliser DynamoDB Local.

1. Exécutez DynamoDB Local (par exemple, au moyen de Docker) :

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

2. Configurez DynamoDBStore afin d'utiliser l'endpoint local :

   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" }
     },
   })

   Vous devez tout de même créer la table et les GSI dans votre instance DynamoDB locale, par exemple au moyen de la CLI AWS configurée pour votre endpoint local.

Paramètres

id:

string

Identifiant unique de cette instance de Storage.

config.tableName:

string

Nom de votre table DynamoDB.

config.region?:

string

Région AWS. Utilise par défaut 'us-east-1'. Pour le développement local, peut être définie sur 'localhost' ou une valeur similaire.

config.endpoint?:

string

Endpoint personnalisé de DynamoDB (par exemple, 'http://localhost:8000' pour le développement local).

config.credentials?:

object

Objet d'identifiants AWS contenant accessKeyId et secretAccessKey. S'il n'est pas fourni, le SDK AWS tente de récupérer les identifiants depuis les variables d'environnement, les rôles IAM (par exemple, pour EC2/Lambda) ou le fichier partagé d'identifiants AWS.

config.ttl?:

object

Configuration TTL (Time To Live) pour l'expiration automatique des données. À configurer par type d'entité : thread, message, trace, eval, workflow_snapshot, resource, score. Chaque configuration d'entité comprend : enabled (boolean), attributeName (string, valeur par défaut : 'ttl') et defaultTtlSeconds (number).

Configuration TTL (Time To Live)

Le TTL de DynamoDB permet de supprimer automatiquement des éléments après une durée déterminée dans les cas suivants :

• Optimisation des coûts : supprimer automatiquement les anciennes données afin de réduire les coûts de stockage
• Gestion du cycle de vie des données : implémenter des politiques de rétention à des fins de conformité
• Performances : empêcher la croissance indéfinie des tables
• Respect de la confidentialité : purger automatiquement les données personnelles après des périodes déterminées

Activation de TTL

Pour utiliser TTL, vous devez :

1. Configurer TTL dans DynamoDBStore (voir ci-dessous)
2. Activer TTL sur votre table DynamoDB au moyen de la console ou de la CLI AWS, en indiquant le nom de l'attribut (par défaut : 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,
      },
    },
  },
})

Types d'entités pris en charge

TTL peut être configuré pour les types d'entités suivants :

Entité	Description
thread	Fils de discussion
message	Messages des fils de discussion
trace	Traces Observability
eval	Résultats d'évaluation
workflow_snapshot	Snapshots de l'état des Workflows
resource	Données utilisateur/ressource
score	Résultats de scoring

Configuration TTL des entités

Chaque type d'entité accepte la configuration suivante :

enabled:

boolean

Indique si TTL est activé pour ce type d'entité.

attributeName?:

string

Nom de l'attribut DynamoDB à utiliser pour TTL. Doit correspondre à l'attribut TTL configuré sur votre table DynamoDB. Utilise par défaut 'ttl'.

defaultTtlSeconds?:

number

TTL par défaut, en secondes, à compter de la création de l’élément. DynamoDB supprime automatiquement les éléments après cette durée.

Activation de TTL sur votre table DynamoDB

Après avoir configuré TTL dans votre code, vous devez l'activer sur la table DynamoDB elle-même :

Avec la CLI AWS :

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

Avec la console AWS :

1. Accédez à la console DynamoDB
2. Sélectionnez votre table
3. Ouvrez l'onglet « Additional settings »
4. Sous « Time to Live (TTL) », sélectionnez « Manage TTL »
5. Activez TTL et indiquez le nom de l'attribut (par défaut : ttl)

remarque

DynamoDB supprime les éléments expirés dans les 48 heures suivant leur expiration. Ils restent interrogeables jusqu'à leur suppression effective.

Autorisations AWS IAM

Le rôle ou l'utilisateur IAM qui exécute le code doit disposer des autorisations nécessaires pour interagir avec la table DynamoDB indiquée et ses index. Vous trouverez ci-dessous un exemple de politique. Remplacez ${YOUR_TABLE_NAME} par le nom réel de votre table, et ${YOUR_AWS_REGION} et ${YOUR_AWS_ACCOUNT_ID} par les valeurs appropriées.

{
  "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/*"
      ]
    }
  ]
}

Points essentiels

Avant d'aborder les détails de l'architecture, gardez les points suivants à l'esprit lorsque vous utilisez l'adaptateur de Storage DynamoDB :

• Provisionnement externe de la table : cet adaptateur exige que vous créiez et configuriez vous-même la table DynamoDB et ses Global Secondary Indexes (GSI) avant de l'utiliser. Suivez le guide de TABLE_SETUP.md.
• Architecture à table unique : toutes les données Mastra (fils de discussion, messages, etc.) sont stockées dans une seule table DynamoDB. Ce choix délibéré est optimisé pour DynamoDB et diffère des approches des bases de données relationnelles.
• Compréhension des GSI : connaître la structure des GSI (décrite dans TABLE_SETUP.md) est important pour comprendre la récupération des données et les modèles de requêtes possibles.
• ElectroDB : l'adaptateur utilise ElectroDB pour gérer les interactions avec DynamoDB et fournir une couche d'abstraction et de typage sûr au-dessus des opérations DynamoDB brutes.

Approche architecturale

Cet adaptateur de Storage utilise un modèle à table unique avec ElectroDB, une approche courante et recommandée pour DynamoDB. Son architecture diffère de celle des adaptateurs de bases de données relationnelles (tels que @mastra/pg ou @mastra/libsql), qui utilisent généralement plusieurs tables, chacune dédiée à une entité précise (fils de discussion, messages, etc.).

Principaux aspects de cette approche :

• Natif DynamoDB : l'architecture à table unique est optimisée pour les fonctionnalités clé-valeur et de requête de DynamoDB, ce qui offre souvent de meilleures performances et une meilleure capacité que l'imitation de modèles relationnels.
• Gestion externe des tables : contrairement à certains adaptateurs susceptibles de proposer des fonctions utilitaires pour créer des tables au moyen de code, cet adaptateur exige que la table DynamoDB et ses Global Secondary Indexes (GSI) associés soient provisionnés en externe avant son utilisation. Consultez TABLE_SETUP.md pour obtenir des instructions détaillées utilisant des Tools tels qu'AWS CloudFormation ou CDK. L'adaptateur se concentre uniquement sur les interactions avec la structure de table préexistante.
• Cohérence grâce à l'interface : bien que le modèle de Storage sous-jacent diffère, cet adaptateur respecte la même interface MastraStorage que les autres adaptateurs, ce qui garantit son interchangeabilité dans le composant Memory de Mastra.

Données Mastra dans la table unique

Dans la table DynamoDB unique, les différentes entités de données Mastra (telles que Threads, Messages, Traces, Evals et Workflows) sont gérées et distinguées au moyen d'ElectroDB. ElectroDB définit des modèles propres à chaque type d'entité, qui comprennent des structures de clés et des attributs uniques. L'adaptateur peut ainsi stocker et récupérer efficacement divers types de données dans une même table.

Par exemple, un élément Thread peut posséder une clé primaire telle que THREAD#<threadId>, tandis qu'un élément Message appartenant à ce fil peut utiliser THREAD#<threadId> comme clé de partition et MESSAGE#<messageId> comme clé de tri. Les Global Secondary Indexes (GSI), détaillés dans TABLE_SETUP.md, sont conçus de manière stratégique pour prendre en charge les modèles d'accès courants entre ces différentes entités, tels que la récupération de tous les messages d'un fil ou l'interrogation des Traces associées à un Workflow.

Avantages de l'architecture à table unique

Cette implémentation utilise un modèle à table unique avec ElectroDB, qui offre plusieurs avantages dans le contexte de DynamoDB :

1. Coûts potentiellement inférieurs : un nombre réduit de tables peut simplifier le provisionnement et la gestion des Read/Write Capacity Units (RCU/WCU), en particulier avec la capacité à la demande.
2. Meilleures performances : les données associées peuvent être colocalisées ou consultées efficacement au moyen des GSI, ce qui permet des recherches rapides pour les modèles d'accès courants.
3. Administration simplifiée : moins de tables distinctes à surveiller et à sauvegarder, donc moins d'éléments à gérer.
4. Complexité réduite des modèles d'accès : ElectroDB aide à gérer la complexité des types d'éléments et des modèles d'accès dans une table unique.
5. Prise en charge des transactions : les transactions DynamoDB peuvent, si nécessaire, être utilisées entre différents types d'« entités » stockés dans la même table.