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.
InstallationLien direct vers Installation
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/oracledb@latest
pnpm add @mastra/oracledb@latest
yarn add @mastra/oracledb@latest
bun add @mastra/oracledb@latest
UtilisationLien direct vers Utilisation
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 :
import { Mastra } from '@mastra/core/mastra'
export const mastra = new Mastra({
storage,
})
ParamètresLien direct vers Paramètres
id:
user?:
pool ou externalAuth est utilisé.password?:
pool ou externalAuth est utilisé.connectString?:
pool est utilisé.pool?:
store.close().poolManager?:
OracleStore et OracleVector.schemaName?:
poolMin?:
poolMax?:
poolIncrement?:
configDir?:
tnsnames.ora.walletLocation?:
walletPassword?:
externalAuth?:
disableInit?:
messageBatchSize?:
executeMany lors de l’enregistrement des messages. L’opération effectue toujours un seul commit à la limite de la transaction.skipDefaultIndexes?:
indexes?:
migrationTableName?:
vectorRegistryTableName?:
OracleVector utilise le même registryTableName lorsque cette option est personnalisée.Exemples de connexionLien direct vers 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 :
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').
InitialisationLien direct vers 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 :
await storage.init()
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.
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 :
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émaLien direct vers 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.
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érationnellesLien direct vers Remarques opérationnelles
Utilisez le même OraclePoolManager lorsque OracleStore et OracleVector doivent partager un même cycle de vie de connexion Oracle :
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'utilisationLien direct vers Exemple d'utilisation
Ajouter la Memory OracleDB à un agentLien direct vers Ajouter la Memory OracleDB à un agent
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 }),
})