メインコンテンツへ移動

OracleDB ストレージ

OracleDB ストレージ Provider は、Mastra アプリケーションの状態を Oracle Database に保存します。Mastra の複合ストレージインターフェースを実装しているため、1つの OracleStore インスタンスで、メモリ、Workflow スナップショット、Observability、スコア、Scorer 定義、MCP クライアントのメタデータ、Agent レジストリデータを管理できます。

インストール
インストールへの直接リンク

npm install @mastra/oracledb@latest

使用方法
使用方法への直接リンク

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

Mastra で使用します。

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

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

パラメーター
パラメーターへの直接リンク

id:

string
このストレージインスタンスの一意な識別子。

user?:

string
Oracle Database ユーザー。pool または externalAuth を使用しない場合は必須です。

password?:

string
Oracle Database ユーザーのパスワード。pool または externalAuth を使用しない場合は必須です。

connectString?:

string
Oracle 接続文字列、サービス名、TNS エイリアス、または Autonomous Database 接続記述子。pool を使用しない場合は必須です。

pool?:

oracledb.Pool
既存の Oracle 接続プール。指定すると Mastra はそのプールを使用しますが、store.close() の呼び出し時には閉じません。

poolManager?:

OraclePoolManager
共有 Oracle プールマネージャー。OracleStore と OracleVector で1つの Oracle プールを共有する場合に使用します。

schemaName?:

string
ストレージテーブルの修飾に使用する Oracle スキーマ名。

poolMin?:

number
= 0
Oracle プールの最小接続数。

poolMax?:

number
= 4
Oracle プールの最大接続数。

poolIncrement?:

number
= 1
プールの拡張時に追加する接続数。

configDir?:

string
tnsnames.ora などの Oracle Network 設定ファイルを格納するディレクトリ。

walletLocation?:

string
Autonomous Database などの mTLS 接続に使用する Oracle ウォレットディレクトリ。

walletPassword?:

string
ウォレット設定で必要な場合に使用する Oracle ウォレットのパスワード。

externalAuth?:

boolean
ユーザー名とパスワードによる認証の代わりに Oracle 外部認証を使用します。

disableInit?:

boolean
= false
true の場合、スキーマの自動初期化を無効にします。アプリの起動前にスキーマ変更を個別に適用する場合に使用します。

messageBatchSize?:

number
= 200
メッセージ保存時に Oracle の executeMany 呼び出し1回あたりで送信するメッセージ数。処理のコミットは、引き続きトランザクション境界で1回だけ行われます。

skipDefaultIndexes?:

boolean
true の場合、初期化時にデフォルトのストレージインデックスを作成しません。

indexes?:

OracleCreateIndexOptions[]
初期化時に作成するカスタム Oracle インデックス定義。インデックスは、対象テーブルを所有するストレージドメインに振り分けられます。

migrationTableName?:

string
= 'MASTRA_ORACLE_MIGRATIONS'
ストレージスキーマのマイグレーション追跡に使用する Oracle テーブル。

vectorRegistryTableName?:

string
スレッドやメッセージの削除時にセマンティックリコール用ベクトルテーブルを検出するための OracleVector レジストリテーブル。このオプションをカスタマイズする場合は、OracleVector の registryTableName と同じ値を設定してください。

接続例
接続例への直接リンク

基本的なユーザー名とパスワードを使うコンストラクターは前述のとおりです。Autonomous Database の場合は、同じコンストラクターにウォレットオプションを追加します。

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

外部認証では externalAuth: true を設定し、password を省略します。既存の oracledb.Pool を再利用するには、pool として渡します。Mastra はそのプールを使用しますが、閉じません。

OracleStore は、メモリ、Workflow スナップショット、Observability、スコア、Scorer 定義、MCP クライアントのメタデータ、Agent レジストリデータを管理します。Mastra インスタンスの外部でストアを使用する場合は、await storage.init() を呼び出し、await storage.getStore('memory') でドメインにアクセスします。

初期化
初期化への直接リンク

OracleStore を Mastra に渡すと、ストレージ操作の実行前に init() が自動的に呼び出されます。OracleStore を直接使用する場合は、読み書きの前に init() を呼び出してください。

await storage.init()
警告

初期化を無効にした場合や省略した場合、ストレージ操作を行うには Oracle のテーブルとインデックスがすでに存在している必要があります。

OracleStore.init() は反復可能なマイグレーションを実行し、その結果をマイグレーション台帳テーブルに記録します。デフォルトの台帳テーブルは MASTRA_ORACLE_MIGRATIONS です。

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

反復可能なマイグレーションは冪等です。起動時に各ストレージドメインが所有するテーブルとインデックスを調整するため、アプリケーションコードを変更せずに、新しいドメインインデックスや互換性のあるスキーマ追加を適用できます。

初期化では、一般的な Mastra のクエリ経路に対応する Provider のデフォルトインデックスも作成されます。インデックスを個別に管理する場合は skipDefaultIndexes を使用し、カスタム Oracle インデックスには indexes を渡します。カスタム定義は bitmap、online、invisible、parallel、compress、noLogging、reverse などの Oracle オプションに加え、JSON_VALUE(...) のような関数ベースの式にも対応しています。

カスタムインデックスは、アプリが JSON メタデータを繰り返しフィルタリングする場合や、データベース管理者（DBA）がオプティマイザーで使用する前にインデックスをテストする場合に便利です。

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

段階的に導入する場合は invisible を使用し、クエリプランの検証後に削除します。skipDefaultIndexes: true は、DBA が管理するインデックス戦略でデフォルトを置き換える場合にのみ使用してください。

スキーマ変更を別のデプロイ手順またはデータベース管理者が適用する場合は、disableInit: true を使用します。

スキーマのエクスポート
スキーマのエクスポートへの直接リンク

データベースに接続せずに Oracle DDL を生成するには、exportSchemas() を使用します。アプリケーション起動時以外にスキーマ変更をレビューまたは適用する場合に便利です。

import { exportSchemas } from '@mastra/oracledb'

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

console.log(ddl)

domains を省略すると、vector を含む、サポートされているすべてのドメインがデフォルトになります。

運用上の注意
運用上の注意への直接リンク

OracleStore と OracleVector で1つの Oracle 接続ライフサイクルを共有する場合は、同じ OraclePoolManager を使用します。

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 は、高度なユースケース向けに storage.db と await storage.getPool() を提供します。これらの API を直接使用する場合、トランザクション境界と接続ライフサイクルを管理する責任があります。

JSON メタデータ、ペイロード、スナップショットは Oracle ネイティブの JSON 列に保存され、サーバー側でエンコードされます。そのため、DBeaver や SQL Developer などの標準的な Oracle JDBC ツールで行を直接読み取れます。

使用例
使用例への直接リンク

Agent に OracleDB メモリを追加する
Agent に OracleDB メモリを追加するへの直接リンク

src/mastra/agents/oracle-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 }),
})
On this page