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

# OracleDB 存储

OracleDB 存储 Provider 将 Mastra 应用程序状态存储在 Oracle Database 中。它实现了 Mastra 的复合存储接口，因此一个 `OracleStore` 实例可为 Memory、Workflow 快照、Observability、分数、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`): 包含 tnsnames.ora 等 Oracle Network 配置文件的目录。

**walletLocation** (`string`): 用于 Autonomous Database 等 mTLS 连接的 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`): 删除线程或消息时，用于发现语义召回向量表的 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` 为 Memory、Workflow 快照、Observability、分数、Scorer 定义、MCP client 元数据和 Agent registry 数据提供支持。在 `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()
```

可重复迁移是幂等的。它们会在启动时协调各存储域拥有的表和索引，从而无需更改应用程序代码即可应用新的域索引或兼容的 schema 添加项。

初始化还会为常见的 Mastra 查询路径创建 Provider 的默认索引。在单独管理索引时使用 `skipDefaultIndexes`，或传入 `indexes` 来创建自定义 Oracle 索引。自定义定义支持 `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` 进行分阶段发布，在验证查询计划后再移除它。仅当 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 Memory

```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/reference/vectors/oracledb)
- [存储概览](https://mastra.zisheng.pro/reference/storage/overview)
- [工作记忆](https://mastra.zisheng.pro/docs/memory/working-memory)
- [Workflow 快照](https://mastra.zisheng.pro/docs/workflows/snapshots)