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

# OracleDB 儲存

OracleDB 儲存 Provider 會將 Mastra 應用程式狀態儲存在 Oracle Database。它實作了 Mastra 的複合儲存介面，因此一個 `OracleStore` 實例便可支援記憶體、Workflow 快照、可觀測性、分數、Scorer 定義、MCP Client 元資料及 Agent Registry 資料。

## 安裝

**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 共用同一個 Oracle 連線池。

**schemaName** (`string`): 用於限定儲存資料表的 Oracle schema 名稱。

**poolMin** (`number`): Oracle 連線池的最少連線數目。 (Default: `0`)

**poolMax** (`number`): Oracle 連線池的最多連線數目。 (Default: `4`)

**poolIncrement** (`number`): 連線池擴充時新增的連線數目。 (Default: `1`)

**configDir** (`string`): 包含 Oracle Network 設定檔（例如 tnsnames.ora）的目錄。

**walletLocation** (`string`): 用於 mTLS 連線（例如 Autonomous Database）的 Oracle wallet 目錄。

**walletPassword** (`string`): Oracle wallet 的密碼（如 wallet 設定需要）。

**externalAuth** (`boolean`): 使用 Oracle 外部驗證，而非使用者名稱／密碼驗證。

**disableInit** (`boolean`): 設為 true 時會停用自動 schema 初始化。若 schema 變更會在應用程式啟動前另行套用，請使用此選項。 (Default: `false`)

**messageBatchSize** (`number`): 儲存訊息時，每次 Oracle executeMany 呼叫傳送的訊息數目。操作仍只會在交易邊界提交一次。 (Default: `200`)

**skipDefaultIndexes** (`boolean`): 設為 true 時，初始化期間不會建立預設儲存索引。

**indexes** (`OracleCreateIndexOptions[]`): 初始化期間要建立的自訂 Oracle 索引定義。索引會路由至擁有目標資料表的儲存網域。

**migrationTableName** (`string`): 用於追蹤儲存 schema 遷移的 Oracle 資料表。 (Default: `'MASTRA_ORACLE_MIGRATIONS'`)

**vectorRegistryTableName** (`string`): 刪除 Thread 或訊息時，用於找出語義回憶向量資料表的 OracleVector Registry 資料表。若自訂了 OracleVector 的 registryTableName 選項，請將此值設為與其相同。

## 連線範例

上方展示了基本的使用者名稱／密碼 constructor。使用 Autonomous Database 時，請在同一個 constructor 加入 wallet 選項：

```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 快照、可觀測性、分數、Scorer 定義、MCP Client 元資料及 Agent Registry 資料。在 `Mastra` 實例以外使用 Store 時，請呼叫 `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()
```

可重複的遷移具備冪等性。它們會在啟動時協調各儲存網域擁有的資料表與索引，讓新增的網域索引或相容的 schema 增補項目毋須變更應用程式碼即可套用。

初始化亦會為常見的 Mastra 查詢路徑建立 Provider 的預設索引。若索引由其他方式管理，請使用 `skipDefaultIndexes`；如要使用自訂 Oracle 索引，請傳入 `indexes`。自訂定義支援 `bitmap`、`online`、`invisible`、`parallel`、`compress`、`noLogging` 及 `reverse` 等 Oracle 選項，以及 `JSON_VALUE(...)` 之類的函數式運算式。

如果應用程式經常按 JSON 元資料篩選，或資料庫管理員（DBA）希望在 optimizer 使用索引前先測試索引，自訂索引便十分有用：

```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` 作分階段推出，並在驗證查詢計劃後將其移除。只有在由 DBA 管理的索引策略取代預設索引時，才應使用 `skipDefaultIndexes: true`。

如果 schema 變更由獨立的部署步驟或資料庫管理員套用，請使用 `disableInit: true`。

## 匯出 schema

使用 `exportSchemas()`，毋須連線至資料庫即可產生 Oracle DDL。當 schema 變更會在應用程式啟動流程以外審核或套用時，這項功能十分有用。

```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` 應共用同一個 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 元資料、payload 及快照會儲存在原生 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 Vector Store](https://mastra.zisheng.pro/zh-HK/reference/vectors/oracledb)
- [儲存概覽](https://mastra.zisheng.pro/zh-HK/reference/storage/overview)
- [工作記憶體](https://mastra.zisheng.pro/zh-HK/docs/memory/working-memory)
- [Workflow 快照](https://mastra.zisheng.pro/zh-HK/docs/workflows/snapshots)