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

# OracleDB ストレージ

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

## インストール

**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
```

## 使用方法

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

Mastra で使用します。

```ts
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`): Oracle プールの最小接続数。 (Default: `0`)

**poolMax** (`number`): Oracle プールの最大接続数。 (Default: `4`)

**poolIncrement** (`number`): プールの拡張時に追加する接続数。 (Default: `1`)

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

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

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

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

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

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

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

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

**migrationTableName** (`string`): ストレージスキーマのマイグレーション追跡に使用する Oracle テーブル。 (Default: `'MASTRA_ORACLE_MIGRATIONS'`)

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

## 接続例

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

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

外部認証では `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()` を呼び出してください。

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

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

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

```ts
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）がオプティマイザーで使用する前にインデックスをテストする場合に便利です。

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

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

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

## スキーマのエクスポート

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

```ts
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` を使用します。

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

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

## 使用例

### Agent に OracleDB メモリを追加する

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

## 関連項目

- [OracleDB ベクトルストア](https://mastra.zisheng.pro/ja/reference/vectors/oracledb)
- [ストレージの概要](https://mastra.zisheng.pro/ja/reference/storage/overview)
- [ワーキングメモリ](https://mastra.zisheng.pro/ja/docs/memory/working-memory)
- [Workflow スナップショット](https://mastra.zisheng.pro/ja/docs/workflows/snapshots)