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

# OracleDB 儲存空間

OracleDB 儲存 Provider 會將 Mastra 應用程式狀態儲存在 Oracle Database 中。它實作 Mastra 的複合儲存介面，因此單一 `OracleStore` 執行個體即可支援記憶體、Workflow snapshot、可觀測性、分數、scorer 定義、MCP client metadata 與 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`): Password for the Oracle Database 使用者。除非使用 pool 或 externalAuth，否則為必填。

**connectString** (`string`): Oracle connect string、service name、TNS alias 或 Autonomous Database connect descriptor。除非使用 pool，否則為必填。

**pool** (`oracledb.Pool`): 現有 Oracle 連線池。提供後，Mastra 會使用該連線池，但呼叫 store.close() 時不會將它關閉。

**poolManager** (`OraclePoolManager`): 共用 Oracle pool manager。使用此選項可讓 OracleStore 與 OracleVector 共用一個 Oracle 連線池。

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

**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 wallet 目錄。

**walletPassword** (`string`): Wallet 設定要求時使用的 Oracle wallet 密碼。

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

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

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

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

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

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

**vectorRegistryTableName** (`string`): 刪除 thread 或訊息時，用於探索語意回憶向量資料表的 OracleVector registry 資料表。自訂 OracleVector 的 registryTableName 選項時，請將此值設為相符。

## 連線範例

上方顯示基本的使用者名稱／密碼建構函式。對於 Autonomous Database，請在相同建構函式中新增 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 snapshot、可觀測性、分數、scorer 定義、MCP client metadata 與 Agent registry 資料。在 `Mastra` 執行個體外使用此 store 時，請呼叫 `await storage.init()`，並以 `await storage.getStore('memory')` 存取 domain。

## 初始化

將 `OracleStore` 傳入 `Mastra` 時，系統會在執行儲存操作前自動呼叫 `init()`。若直接使用 `OracleStore`，請在讀寫前呼叫 `init()`：

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

> **警告:** 若停用或略過初始化，進行儲存操作前 Oracle 資料表與索引必須已存在。

`OracleStore.init()` 會執行 repeatable migration，並將結果記錄在 migration ledger 資料表中。預設 ledger 資料表為 `MASTRA_ORACLE_MIGRATIONS`。

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

Repeatable migration 具有 idempotent 特性。它們會在啟動時協調各儲存 domain 擁有的資料表與索引，讓新的 domain 索引或相容 schema 新增項目無需變更應用程式的程式碼即可套用。

初始化也會針對常見 Mastra 查詢路徑建立 Provider 的預設索引。另行管理索引時請使用 `skipDefaultIndexes`，自訂 Oracle 索引則傳入 `indexes`。自訂定義支援 `bitmap`、`online`、`invisible`、`parallel`、`compress`、`noLogging` 與 `reverse` 等 Oracle 選項，以及 `JSON_VALUE(...)` 等以函式為基礎的運算式。

應用程式重複篩選 JSON metadata，或資料庫管理員（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`，驗證 query plan 後再移除。只有由 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` 時，預設為所有受支援的 domain，包括 `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 metadata、payload 與 snapshot 會儲存在原生 Oracle JSON 欄位中，並在 server 端編碼，因此可使用 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/zh-TW/reference/vectors/oracledb)
- [儲存空間概觀](https://mastra.zisheng.pro/zh-TW/reference/storage/overview)
- [Working memory](https://mastra.zisheng.pro/zh-TW/docs/memory/working-memory)
- [Workflow snapshot](https://mastra.zisheng.pro/zh-TW/docs/workflows/snapshots)