OracleDB 스토리지
OracleDB 스토리지 제공자는 Oracle Database에 Mastra 애플리케이션 상태를 저장합니다. Mastra의 복합 스토리지 인터페이스를 구현하므로OracleStore인스턴스는 Memory, Workflow 스냅샷, Observability, 점수, 채점자 정의, MCP 클라이언트 메타데이터 및 Agent 레지스트리 데이터를 지원할 수 있습니다.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/oracledb@latest
pnpm add @mastra/oracledb@latest
yarn add @mastra/oracledb@latest
bun add @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:
user?:
pool 또는 externalAuth를 사용하지 않는 경우 필수입니다.password?:
pool 또는 externalAuth를 사용하지 않는 경우 필수입니다.connectString?:
pool을 사용하지 않는 경우 필수입니다.pool?:
store.close()가 호출되어도 풀을 닫지 않습니다.poolManager?:
OracleStore와 OracleVector가 하나의 Oracle 풀을 공유하도록 하는 공유 Oracle 풀 관리자입니다.schemaName?:
poolMin?:
poolMax?:
poolIncrement?:
configDir?:
tnsnames.ora와 같은 Oracle Network 구성 파일이 포함된 디렉터리입니다.walletLocation?:
walletPassword?:
externalAuth?:
disableInit?:
messageBatchSize?:
executeMany 호출당 전송되는 메시지 수입니다. 작업은 여전히 트랜잭션 경계에서 한 번만 커밋됩니다.skipDefaultIndexes?:
indexes?:
migrationTableName?:
vectorRegistryTableName?:
OracleVector의 registryTableName과 일치하도록 설정하세요.연결 예연결 예에 대한 직접 링크
기본 사용자 이름/비밀번호 생성자는 위에 나와 있습니다. 자율 데이터베이스의 경우 동일한 생성자에 지갑 옵션을 추가합니다.
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, 점수, 채점자 정의, MCP 클라이언트 메타데이터 및 Agent 레지스트리 데이터를 지원합니다. 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()
반복 가능한 마이그레이션은 멱등성을 갖습니다. 시작 시 각 스토리지 도메인이 소유한 테이블과 인덱스를 조정하므로 애플리케이션 코드를 변경하지 않고도 새 도메인 인덱스나 호환 가능한 스키마 추가 사항을 적용할 수 있습니다.
초기화 과정에서는 일반적인 Mastra 쿼리 경로를 위한 Provider의 기본 인덱스도 생성됩니다. 인덱스를 별도로 관리하는 경우 skipDefaultIndexes를 사용하고, 사용자 정의 Oracle 인덱스에는 indexes를 전달합니다. 사용자 정의 정의는 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를 사용하세요.
별도의 배포 단계나 데이터베이스 관리자가 스키마 변경 사항을 적용하는 경우 disableInit: true를 사용하세요.
스키마 내보내기스키마 내보내기에 대한 직접 링크
데이터베이스에 연결하지 않고 Oracle DDL을 생성하려면 exportSchemas()를 사용하세요. 애플리케이션 시작 외부에서 스키마 변경 사항을 검토하거나 적용할 때 유용합니다.
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 메타데이터, 페이로드 및 스냅샷은 기본 Oracle JSON 열에 저장되고 서버 측에 인코딩되므로 DBeaver 및 SQL Developer와 같은 표준 Oracle JDBC Tool을 사용하여 행을 직접 읽을 수 있습니다.
사용예사용예에 대한 직접 링크
Agent에 OracleDB Memory 추가Agent에 OracleDB Memory 추가에 대한 직접 링크
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 }),
})