> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Stockage Aurora DSQL

L’implémentation du stockage Aurora DSQL fournit un stockage basé sur Amazon Aurora DSQL avec authentification IAM.

Aurora DSQL ne prend pas en charge les extensions PostgreSQL (`CREATE EXTENSION`), notamment `pgvector`. Pour le stockage vectoriel, utilisez une base vectorielle distincte telle que `@mastra/s3vectors`.

## Installation

```bash
npm install @mastra/dsql@beta
```

## Prérequis

- Cluster Amazon Aurora DSQL
- Identifiants AWS donnant accès au cluster DSQL (authentification IAM)

## Utilisation

```typescript
import { DSQLStore } from '@mastra/dsql'

const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  // region is auto-detected from host, or specify explicitly:
  // region: 'us-east-1',
  // user: 'admin', // default
  // database: 'postgres', // default
})

// Initialize the store (creates tables if needed)
await storage.init()
```

## Paramètres

**id** (`string`): Identifiant unique de cette instance de stockage

**host** (`string`): Point de terminaison du cluster DSQL (par exemple, abc123.dsql.us-east-1.on.aws)

**pool** (`pg.Pool`): Instance pg.Pool préconfigurée. Utilisez-la pour contrôler directement le pool de connexions. Incompatible avec la configuration host.

**user** (`string`): Utilisateur de la base de données. Le rôle d’administration d’Aurora DSQL est 'admin'.

**database** (`string`): Nom de la base de données. Aurora DSQL expose une seule base nommée 'postgres' par cluster.

**region** (`string`): Région AWS. Extraite de host si elle n’est pas fournie.

**schemaName** (`string`): Nom du schéma PostgreSQL dans lequel les tables et index Mastra sont créés.

**customCredentialsProvider** (`AwsCredentialIdentityProvider`): Provider d’identifiants AWS personnalisé pour l’authentification IAM.

**max** (`number`): Nombre maximal de connexions dans le pool.

**min** (`number`): Nombre minimal de connexions dans le pool.

**idleTimeoutMillis** (`number`): Ferme les connexions inactives après ce nombre de millisecondes.

**maxLifetimeSeconds** (`number`): Durée de vie maximale d’une connexion, en secondes. Doit être inférieure à 3600 en raison de la limite de connexion de 60 minutes d’Aurora DSQL.

**connectionTimeoutMillis** (`number`): Délai d’expiration de l’acquisition d’une connexion, en millisecondes.

**allowExitOnIdle** (`boolean`): Autorise le processus à se terminer lorsque toutes les connexions sont inactives.

## Exemples de construction

Vous pouvez instancier `DSQLStore` de différentes manières :

```typescript
import { DSQLStore } from '@mastra/dsql'

// Basic configuration (region auto-detected from host)
const store1 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
})

// With explicit region and schema
const store2 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  region: 'us-east-1',
  schemaName: 'my_app',
})

// With custom credentials provider
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'

const store3 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  customCredentialsProvider: fromNodeProviderChain(),
})

// With connection pool settings
const store4 = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  max: 20,
  min: 2,
  idleTimeoutMillis: 300000,
  maxLifetimeSeconds: 3000,
  connectionTimeoutMillis: 10000,
})

// Using a pre-configured pg.Pool
import { Pool } from 'pg'
import { AuroraDSQLClient } from '@aws/aurora-dsql-node-postgres-connector'

const pool = new Pool({
  host: 'abc123.dsql.us-east-1.on.aws',
  Client: AuroraDSQLClient,
  region: 'us-east-1',
})

const store5 = new DSQLStore({
  id: 'my-dsql-store',
  pool,
})
```

## Remarques supplémentaires

### Gestion du schéma

L’implémentation du stockage gère automatiquement la création et la mise à jour du schéma. Elle crée les tables suivantes :

- `mastra_workflow_snapshot` : stocke l’état et les données d’exécution des Workflows
- `mastra_threads` : stocke les fils de conversation
- `mastra_messages` : stocke les messages individuels
- `mastra_ai_spans` : stocke les données de spans pour l’observabilité
- `mastra_scorers` : stocke les données de scoring et d’évaluation
- `mastra_resources` : stocke les données de mémoire de travail des ressources
- `mastra_agents` : stocke les données des Agents

### Initialisation

Lorsque vous transmettez le stockage à la classe Mastra, `init()` est appelée automatiquement avant toute opération de stockage :

```typescript
import { Mastra } from '@mastra/core'
import { DSQLStore } from '@mastra/dsql'

const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
})

const mastra = new Mastra({
  storage, // init() is called automatically
})
```

Si vous utilisez directement le stockage sans Mastra, vous devez appeler explicitement `init()` pour créer les tables :

```typescript
import { DSQLStore } from '@mastra/dsql'

const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
})

// Required when using storage directly
await storage.init()

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory')
const thread = await memoryStore?.getThreadById({ threadId: '...' })
```

> **Attention:** Si `init()` n’est pas appelée, les tables ne seront pas créées et les opérations de stockage échoueront silencieusement ou déclencheront des erreurs.

### Accès direct à la base de données et au pool

`DSQLStore` expose le client de base de données sous-jacent et l’instance pg.Pool comme champs publics :

```typescript
storage.db // Database client for executing queries
storage.pool // Underlying pg.Pool instance
```

Il prend en charge les requêtes directes et la gestion personnalisée des transactions. Lorsque vous utilisez ces champs :

- Vous êtes responsable de la bonne gestion des connexions et des transactions.
- La fermeture du stockage (`storage.close()`) détruira le pool de connexions s’il a été créé par le stockage.
- L’accès direct contourne toute logique ou validation supplémentaire fournie par les méthodes de DSQLStore.

Cette approche est destinée aux scénarios avancés qui nécessitent un accès de bas niveau.

### Particularités d’Aurora DSQL

#### Authentification IAM uniquement

Les connexions sont authentifiées avec IAM. Aucun mot de passe de base de données n’est requis. `@mastra/dsql` utilise `@aws/aurora-dsql-node-postgres-connector` pour générer des tokens d’authentification de courte durée. Vous pouvez fournir un Provider d’identifiants personnalisé via `customCredentialsProvider`.

#### Base de données unique et isolation par schéma

Chaque cluster expose une seule base de données `postgres`. La séparation logique s’effectue au moyen de schémas. L’option `schemaName` détermine l’emplacement de création des tables Mastra.

#### Aucune extension PostgreSQL

`CREATE EXTENSION` n’est pas pris en charge. Cela inclut `pgvector`, `PostGIS` et d’autres extensions. Pour le stockage vectoriel, utilisez une base distincte telle que `@mastra/s3vectors` avec `DSQLStore`.

#### JSON stocké sous forme de texte

JSON/JSONB sont disponibles comme types de requête, mais pas comme types de colonne. `@mastra/dsql` stocke les champs structurés (métadonnées, contenu, etc.) dans des colonnes `TEXT` et les convertit en JSON lors des requêtes.

#### Contraintes de schéma et DDL

Certaines fonctionnalités PostgreSQL ne sont pas disponibles :

- Contraintes de clé étrangère
- `TRUNCATE`
- `CREATE INDEX` synchrone

Les index sont créés de manière asynchrone avec `CREATE INDEX ASYNC`. `init()` et les API auxiliaires d’index du stockage respectent ces contraintes.

#### Transactions et accès concurrent optimiste

Aurora DSQL utilise le contrôle de concurrence optimiste (OCC) et peut renvoyer des erreurs OCC réessayables en cas de contention. La durée et la taille des transactions sont limitées. Les opérations groupées volumineuses doivent être divisées en lots plus petits au niveau de l’application.

#### Durée de vie des connexions

Les connexions individuelles sont limitées à environ 60 minutes. La valeur par défaut `maxLifetimeSeconds: 3300` garantit leur renouvellement avant cette limite.

## Exemple d’utilisation

### Ajouter une Memory à un Agent

Pour ajouter une Memory Aurora DSQL à un Agent, utilisez la classe `Memory` et créez une nouvelle clé `storage` avec `DSQLStore`. `host` doit pointer vers le point de terminaison de votre cluster Aurora DSQL.

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { DSQLStore } from '@mastra/dsql'

export const dsqlAgent = new Agent({
  id: 'dsql-agent',
  name: 'DSQL Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new DSQLStore({
      id: 'dsql-agent-storage',
      host: process.env.DSQL_HOST!,
    }),
    options: {
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
})
```

### Utiliser l’Agent

Utilisez `memoryOptions` pour délimiter le rappel de cette requête. Définissez `lastMessages: 5` afin de limiter le rappel fondé sur la récence, puis utilisez `semanticRecall` pour récupérer les `topK: 3` messages les plus pertinents, ainsi que `messageRange: 2` messages voisins fournissant du contexte autour de chaque correspondance.

```typescript
import 'dotenv/config'

import { mastra } from './mastra'

const threadId = '123'
const resourceId = 'user-456'

const agent = mastra.getAgent('dsql-agent')

const message = await agent.stream('My name is Mastra', {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
})

await message.textStream.pipeTo(new WritableStream())

const stream = await agent.stream("What's my name?", {
  memory: {
    thread: threadId,
    resource: resourceId,
  },
  memoryOptions: {
    lastMessages: 5,
    semanticRecall: {
      topK: 3,
      messageRange: 2,
    },
  },
})

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}
```

## Gestion des index

Le stockage Aurora DSQL fournit des fonctionnalités de gestion des index pour optimiser les performances des requêtes.

### Index de performance automatiques

Lors de l’initialisation, le stockage Aurora DSQL crée automatiquement des index composites pour les modèles de requête courants :

- `mastra_threads_resourceid_createdat_idx`: (resourceId, createdAt)
- `mastra_messages_thread_id_createdat_idx`: (thread\_id, createdAt)
- `mastra_ai_spans_traceid_startedat_idx`: (traceId, startedAt)
- `mastra_ai_spans_parentspanid_startedat_idx`: (parentSpanId, startedAt)
- `mastra_ai_spans_name_idx`: (name)
- `mastra_ai_spans_spantype_startedat_idx`: (spanType, startedAt)
- `mastra_scores_trace_id_span_id_created_at_idx`: (traceId, spanId, createdAt)

Aurora DSQL crée ces index de manière asynchrone avec `CREATE INDEX ASYNC`. Leur création étant asynchrone, les nouveaux index peuvent ne pas être immédiatement disponibles après `init()`. Le stockage continuera de fonctionner sans eux, mais les requêtes pourront être plus lentes jusqu’à la fin de leur création.

### Créer des index personnalisés

Créez des index supplémentaires afin d’optimiser certains modèles de requête :

```typescript
await storage.createIndex({
  name: 'idx_threads_resource',
  table: 'mastra_threads',
  columns: ['resourceId'],
})

await storage.createIndex({
  name: 'idx_messages_composite',
  table: 'mastra_messages',
  columns: ['thread_id', 'createdAt'],
})
```

Aurora DSQL n’autorise pas `ASC`/`DESC` dans `CREATE INDEX ASYNC`. Si vous les incluez, ils seront automatiquement supprimés.

### Options des index

**name** (`string`): Nom unique de l’index

**table** (`string`): Nom de la table (par exemple, 'mastra\_threads')

**columns** (`string[]`): Tableau de noms de colonnes. Les modificateurs ASC/DESC sont automatiquement supprimés pour assurer la compatibilité avec Aurora DSQL.

**unique** (`boolean`): Crée un index unique.

**concurrent** (`boolean`): Ignoré dans Aurora DSQL. Les index sont toujours créés de manière asynchrone.

**where** (`string`): Condition d’index partiel.

**method** (`string`): Ignoré dans Aurora DSQL. Seuls les index btree sont pris en charge.

**opclass** (`string`): Ignoré dans Aurora DSQL.

**storage** (`Record<string, any>`): Ignoré dans Aurora DSQL.

**tablespace** (`string`): Ignoré dans Aurora DSQL. Les tablespaces ne sont pas pris en charge.

### Gérer les index

Répertoriez et surveillez les index existants :

```typescript
// List all indexes
const allIndexes = await storage.listIndexes()
console.log(allIndexes)
// [
//   {
//     name: 'mastra_threads_pkey',
//     table: 'mastra_threads',
//     columns: ['id'],
//     unique: true,
//     size: '16 KB',
//     definition: 'CREATE UNIQUE INDEX...'
//   },
//   ...
// ]

// List indexes for a specific table
const threadIndexes = await storage.listIndexes('mastra_threads')

// Get detailed statistics for an index
const stats = await storage.describeIndex('idx_threads_resource')
console.log(stats)
// {
//   name: 'idx_threads_resource',
//   table: 'mastra_threads',
//   columns: ['resourceId'],
//   unique: false,
//   size: '128 KB',
//   definition: 'CREATE INDEX idx_threads_resource...',
//   method: 'btree',
//   scans: 1542,
//   tuples_read: 45230,
//   tuples_fetched: 12050
// }

// Drop an index
await storage.dropIndex('idx_threads_status')
```

### Index propres au schéma

Lorsque vous utilisez des schémas personnalisés, les index sont créés avec des préfixes de schéma :

```typescript
const storage = new DSQLStore({
  id: 'my-dsql-store',
  host: 'abc123.dsql.us-east-1.on.aws',
  schemaName: 'custom_schema',
})

// Creates index as: custom_schema_idx_threads_status
await storage.createIndex({
  name: 'idx_threads_status',
  table: 'mastra_threads',
  columns: ['status'],
})
```

## Ressources associées

- [Documentation Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/)
- [Référence SQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-aurora-dsql-sql.html)
- [Fonctionnalités SQL prises en charge](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-sql-features.html)
- [Fonctionnalités PostgreSQL non prises en charge](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-unsupported-features.html)
- [Types de données pris en charge](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-postgresql-compatibility-supported-data-types.html)
- [Index asynchrones](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-create-index-async.html)