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

# Stockage OracleDB

Le Provider de stockage OracleDB stocke l'état de l'application Mastra dans Oracle Database. Il implémente l'interface de stockage composite de Mastra ; une seule instance `OracleStore` peut donc prendre en charge la Memory, les instantanés de workflows, l'observabilité, les scores, les définitions de Scorers, les métadonnées des clients MCP et les données du registre des agents.

## Installation

**npm**:

```bash
npm install @mastra/oracledb@latest
```

**pnpm**:

```bash
pnpm add @mastra/oracledb@latest
```

**Yarn**:

```bash
yarn add @mastra/oracledb@latest
```

**Bun**:

```bash
bun add @mastra/oracledb@latest
```

## Utilisation

```ts
import { OracleStore } from '@mastra/oracledb'

const storage = new OracleStore({
  id: 'oracle-storage',
  user: process.env.ORACLE_DATABASE_USER,
  password: process.env.ORACLE_DATABASE_PASSWORD,
  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
})
```

Utilisez-le avec Mastra :

```ts
import { Mastra } from '@mastra/core/mastra'

export const mastra = new Mastra({
  storage,
})
```

## Paramètres

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

**user** (`string`): Utilisateur Oracle Database. Requis sauf si pool ou externalAuth est utilisé.

**password** (`string`): Mot de passe de l’utilisateur Oracle Database. Requis sauf si pool ou externalAuth est utilisé.

**connectString** (`string`): Chaîne de connexion Oracle, nom de service, alias TNS ou descripteur de connexion Autonomous Database. Requis sauf si pool est utilisé.

**pool** (`oracledb.Pool`): Pool de connexions Oracle existant. Lorsqu’il est fourni, Mastra utilise le pool, mais ne le ferme pas lors de l’appel à store.close().

**poolManager** (`OraclePoolManager`): Gestionnaire de pool Oracle partagé. Utilisez-le pour partager un même pool Oracle entre OracleStore et OracleVector.

**schemaName** (`string`): Nom du schéma Oracle utilisé pour qualifier les tables de stockage.

**poolMin** (`number`): Nombre minimal de connexions dans le pool Oracle. (Default: `0`)

**poolMax** (`number`): Nombre maximal de connexions dans le pool Oracle. (Default: `4`)

**poolIncrement** (`number`): Nombre de connexions à ajouter lorsque le pool s’agrandit. (Default: `1`)

**configDir** (`string`): Répertoire contenant les fichiers de configuration Oracle Network, tels que tnsnames.ora.

**walletLocation** (`string`): Répertoire du wallet Oracle pour les connexions mTLS, comme Autonomous Database.

**walletPassword** (`string`): Mot de passe du wallet Oracle, lorsque la configuration du wallet l’exige.

**externalAuth** (`boolean`): Utilise l’authentification externe Oracle plutôt qu’une authentification par nom d’utilisateur et mot de passe.

**disableInit** (`boolean`): Lorsque cette valeur est true, l’initialisation automatique du schéma est désactivée. Utilisez cette option lorsque les modifications du schéma sont appliquées séparément avant le démarrage de l’application. (Default: `false`)

**messageBatchSize** (`number`): Nombre de messages envoyés par appel Oracle executeMany lors de l’enregistrement des messages. L’opération effectue toujours un seul commit à la limite de la transaction. (Default: `200`)

**skipDefaultIndexes** (`boolean`): Lorsque cette valeur est true, les index de stockage par défaut ne sont pas créés pendant l’initialisation.

**indexes** (`OracleCreateIndexOptions[]`): Définitions d’index Oracle personnalisés à créer pendant l’initialisation. Les index sont acheminés vers le domaine de stockage propriétaire de la table cible.

**migrationTableName** (`string`): Table Oracle utilisée pour suivre les migrations du schéma de stockage. (Default: `'MASTRA_ORACLE_MIGRATIONS'`)

**vectorRegistryTableName** (`string`): Table de registre OracleVector utilisée pour découvrir les tables vectorielles de rappel sémantique lors de la suppression de threads ou de messages. Définissez cette valeur pour qu’OracleVector utilise le même registryTableName lorsque cette option est personnalisée.

## Exemples de connexion

Le constructeur de base avec nom d'utilisateur et mot de passe est présenté ci-dessus. Pour Autonomous Database, ajoutez les options du wallet au même constructeur :

```ts
const storage = new OracleStore({
  id: 'oracle-storage',
  user: process.env.ORACLE_DATABASE_USER,
  password: process.env.ORACLE_DATABASE_PASSWORD,
  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
  walletLocation: process.env.ORACLE_DATABASE_WALLET_DIR,
  walletPassword: process.env.ORACLE_DATABASE_WALLET_PASSWORD,
  configDir: process.env.ORACLE_DATABASE_CONFIG_DIR,
})
```

Pour l'authentification externe, définissez `externalAuth: true` et omettez `password`. Pour réutiliser un `oracledb.Pool` existant, transmettez-le sous la forme `pool`. Mastra l'utilise, mais ne le ferme pas.

`OracleStore` prend en charge la Memory, les instantanés de workflows, l'observabilité, les scores, les définitions de Scorers, les métadonnées des clients MCP et les données du registre des agents. Lorsque vous utilisez le stockage en dehors d'une instance `Mastra`, appelez `await storage.init()` et accédez à un domaine avec `await storage.getStore('memory')`.

## Initialisation

Lorsque vous transmettez `OracleStore` à `Mastra`, `init()` est appelée automatiquement avant l'exécution des opérations de stockage. Si vous utilisez directement `OracleStore`, appelez `init()` avant toute lecture ou écriture :

```ts
await storage.init()
```

> **Attention:** Si l'initialisation est désactivée ou ignorée, les opérations de stockage nécessitent que les tables et index Oracle existent déjà.

`OracleStore.init()` exécute des migrations répétables et enregistre le résultat dans la table du registre des migrations. La table de registre par défaut est `MASTRA_ORACLE_MIGRATIONS`.

```ts
await storage.migrate()
const history = await storage.listMigrations()
```

Les migrations répétables sont idempotentes. Au démarrage, elles rapprochent les tables et index appartenant à chaque domaine de stockage, ce qui permet d'appliquer de nouveaux index de domaine ou des ajouts de schéma compatibles sans modifier le code de l'application.

L'initialisation crée également les index par défaut du Provider pour les chemins de requête Mastra courants. Utilisez `skipDefaultIndexes` lorsque les index sont gérés séparément, ou transmettez `indexes` pour créer des index Oracle personnalisés. Les définitions personnalisées prennent en charge des options Oracle comme `bitmap`, `online`, `invisible`, `parallel`, `compress`, `noLogging` et `reverse`, ainsi que des expressions fondées sur des fonctions comme `JSON_VALUE(...)`.

Les index personnalisés sont utiles lorsque votre application filtre fréquemment des métadonnées JSON ou lorsque les administrateurs de base de données (DBA) souhaitent tester un index avant que l'optimiseur ne l'utilise :

```ts
const storage = new OracleStore({
  id: 'oracle-storage',
  user,
  password,
  connectString,
  indexes: [
    {
      name: 'idx_messages_status',
      table: 'mastra_messages',
      columns: [
        "JSON_VALUE(metadata, '$.status' RETURNING VARCHAR2(32) NULL ON ERROR)",
        'thread_id',
      ],
      online: true,
      invisible: true,
    },
  ],
})
```

Utilisez `invisible` pour un déploiement progressif, puis supprimez cette option après avoir validé les plans de requête. Utilisez `skipDefaultIndexes: true` uniquement lorsqu'une stratégie d'indexation gérée par un DBA remplace les valeurs par défaut.

Utilisez `disableInit: true` lorsque les modifications du schéma sont appliquées par une étape de déploiement distincte ou par un administrateur de base de données.

## Exporter le schéma

Utilisez `exportSchemas()` pour générer les instructions DDL Oracle sans vous connecter à une base de données. Cette fonction est utile lorsque les modifications du schéma sont examinées ou appliquées en dehors du démarrage de l'application.

```ts
import { exportSchemas } from '@mastra/oracledb'

const ddl = exportSchemas({
  schemaName: 'MASTRA_APP',
  domains: [
    'memory',
    'workflows',
    'observability',
    'scores',
    'scorerDefinitions',
    'mcpClients',
    'agents',
  ],
})

console.log(ddl)
```

Lorsqu'il est omis, `domains` inclut par défaut tous les domaines pris en charge, y compris `vector`.

## Remarques opérationnelles

Utilisez le même `OraclePoolManager` lorsque `OracleStore` et `OracleVector` doivent partager un même cycle de vie de connexion Oracle :

```ts
import { OracleStore, OracleVector } from '@mastra/oracledb'

const storage = new OracleStore({ id: 'oracle-storage', user, password, connectString })
const vector = new OracleVector({
  id: 'oracle-vector',
  poolManager: storage.getPoolManager(),
})
```

`OracleStore` expose `storage.db` et `await storage.getPool()` pour les cas d'utilisation avancés. Lorsque vous utilisez directement ces API, vous êtes responsable des limites des transactions et du cycle de vie des connexions.

Les métadonnées JSON, les payloads et les instantanés sont stockés dans des colonnes JSON Oracle natives et encodés côté serveur. Les lignes sont donc directement lisibles avec des outils Oracle JDBC standard tels que DBeaver et SQL Developer.

## Exemple d'utilisation

### Ajouter la Memory OracleDB à un agent

```ts
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { OracleStore } from '@mastra/oracledb'

const storage = new OracleStore({
  id: 'oracle-storage',
  user: process.env.ORACLE_DATABASE_USER,
  password: process.env.ORACLE_DATABASE_PASSWORD,
  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
})

export const oracleAgent = new Agent({
  id: 'oracle-agent',
  name: 'Oracle Agent',
  instructions: 'You are an assistant with persistent OracleDB-backed memory.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({ storage }),
})
```

## Ressources associées

- [Stockage vectoriel OracleDB](https://mastra.zisheng.pro/fr/reference/vectors/oracledb)
- [Présentation du Storage](https://mastra.zisheng.pro/fr/reference/storage/overview)
- [Mémoire de travail](https://mastra.zisheng.pro/fr/docs/memory/working-memory)
- [Instantanés de workflows](https://mastra.zisheng.pro/fr/docs/workflows/snapshots)