跳至主要內容

OracleDB 儲存空間

OracleDB 儲存 Provider 會將 Mastra 應用程式狀態儲存在 Oracle Database 中。它實作 Mastra 的複合儲存介面，因此單一 OracleStore 執行個體即可支援記憶體、Workflow snapshot、可觀測性、分數、scorer 定義、MCP client metadata 與 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
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
= 0
Oracle 連線池的最小連線數。

poolMax?:

number
= 4
Oracle 連線池的最大連線數。

poolIncrement?:

number
= 1
連線池增長時要新增的連線數。

configDir?:

string
包含 tnsnames.ora 等 Oracle Network 設定檔的目錄。

walletLocation?:

string
Autonomous Database 等 mTLS 連線使用的 Oracle wallet 目錄。

walletPassword?:

string
Wallet 設定要求時使用的 Oracle wallet 密碼。

externalAuth?:

boolean
使用 Oracle 外部驗證，不使用使用者名稱／密碼驗證。

disableInit?:

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

messageBatchSize?:

number
= 200
儲存訊息時，每次 Oracle executeMany 呼叫傳送的訊息數量。操作仍會在交易邊界一次 commit。

skipDefaultIndexes?:

boolean
設為 true 時，初始化期間不會建立預設儲存索引。

indexes?:

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

migrationTableName?:

string
= 'MASTRA_ORACLE_MIGRATIONS'
用於追蹤儲存 schema migration 的 Oracle 資料表。

vectorRegistryTableName?:

string
刪除 thread 或訊息時，用於探索語意回憶向量資料表的 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 支援記憶體、Workflow snapshot、可觀測性、分數、scorer 定義、MCP client metadata 與 Agent registry 資料。在 Mastra 執行個體外使用此 store 時，請呼叫 await storage.init()，並以 await storage.getStore('memory') 存取 domain。

初始化
「初始化」的直接連結

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

await storage.init()
警告

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

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

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 使用索引前進行測試時，自訂索引很有用：

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
「匯出 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 時，預設為所有受支援的 domain，包括 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 metadata、payload 與 snapshot 會儲存在原生 Oracle JSON 欄位中，並在 server 端編碼，因此可使用 DBeaver 與 SQL Developer 等標準 Oracle JDBC 工具直接讀取資料列。

使用範例
「使用範例」的直接連結

為 Agent 新增 OracleDB 記憶體
「為 Agent 新增 OracleDB 記憶體」的直接連結

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