跳到主要内容

OracleDB 存储

OracleDB 存储 Provider 将 Mastra 应用程序状态存储在 Oracle Database 中。它实现了 Mastra 的复合存储接口，因此一个 OracleStore 实例可为 Memory、Workflow 快照、Observability、分数、Scorer 定义、MCP client 元数据和 Agent registry 数据提供支持。

安装
安装的直接链接

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 之间共享一个 Oracle 连接池。

schemaName?:

string
用于限定存储表的 Oracle schema 名称。

poolMin?:

number
= 0
Oracle 连接池的最小连接数。

poolMax?:

number
= 4
Oracle 连接池的最大连接数。

poolIncrement?:

number
= 1
连接池扩容时要增加的连接数。

configDir?:

string
包含 tnsnames.ora 等 Oracle Network 配置文件的目录。

walletLocation?:

string
用于 Autonomous Database 等 mTLS 连接的 Oracle wallet 目录。

walletPassword?:

string
Oracle wallet 的密码，在 wallet 配置要求时使用。

externalAuth?:

boolean
使用 Oracle 外部身份验证，而非用户名/密码身份验证。

disableInit?:

boolean
= false
为 true 时，禁用自动 schema 初始化。请在应用启动前通过其他方式单独应用 schema 更改时使用。

messageBatchSize?:

number
= 200
保存消息时，每次 Oracle executeMany 调用发送的消息数量。操作仍会在事务边界处提交一次。

skipDefaultIndexes?:

boolean
为 true 时，初始化期间不会创建默认存储索引。

indexes?:

OracleCreateIndexOptions[]
初始化期间要创建的自定义 Oracle 索引定义。索引会路由到拥有目标表的存储域。

migrationTableName?:

string
= 'MASTRA_ORACLE_MIGRATIONS'
用于跟踪存储 schema 迁移的 Oracle 表。

vectorRegistryTableName?:

string
删除线程或消息时，用于发现语义召回向量表的 OracleVector registry 表。自定义该选项时，请将其设为与 OracleVector 的 registryTableName 相匹配的值。

连接示例
连接示例的直接链接

上方展示了基本的用户名/密码构造函数。对于 Autonomous Database，请向同一构造函数添加 wallet 选项：

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()：

await storage.init()
注意

如果禁用或跳过初始化，存储操作要求 Oracle 表和索引已存在。

OracleStore.init() 会运行可重复迁移，并将结果记录到迁移账本表中。默认账本表为 MASTRA_ORACLE_MIGRATIONS。

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）想在优化器使用索引前对其进行测试时，自定义索引会很有用：

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 导出
Schema 导出的直接链接

使用 exportSchemas() 可在不连接数据库的情况下生成 Oracle DDL。当在应用程序启动之外审查或应用 schema 更改时，这很有用。

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：

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
向 Agent 添加 OracleDB Memory的直接链接

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