跳至主要內容

OracleDB 儲存

OracleDB 儲存 Provider 會將 Mastra 應用程式狀態儲存在 Oracle Database。它實作了 Mastra 的複合儲存介面，因此一個 OracleStore 實例便可支援記憶體、Workflow 快照、可觀測性、分數、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
包含 Oracle Network 設定檔（例如 tnsnames.ora）的目錄。

walletLocation?:

string
用於 mTLS 連線（例如 Autonomous Database）的 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
刪除 Thread 或訊息時，用於找出語義回憶向量資料表的 OracleVector Registry 資料表。若自訂了 OracleVector 的 registryTableName 選項，請將此值設為與其相同。

連線範例
連線範例 的直接連結

上方展示了基本的使用者名稱／密碼 constructor。使用 Autonomous Database 時，請在同一個 constructor 加入 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 快照、可觀測性、分數、Scorer 定義、MCP Client 元資料及 Agent Registry 資料。在 Mastra 實例以外使用 Store 時，請呼叫 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；如要使用自訂 Oracle 索引，請傳入 indexes。自訂定義支援 bitmap、online、invisible、parallel、compress、noLogging 及 reverse 等 Oracle 選項，以及 JSON_VALUE(...) 之類的函數式運算式。

如果應用程式經常按 JSON 元資料篩選，或資料庫管理員（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 作分階段推出，並在驗證查詢計劃後將其移除。只有在由 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 記憶體
為 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