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

# OracleDB 스토리지

OracleDB 스토리지 제공자는 Oracle Database에 Mastra 애플리케이션 상태를 저장합니다. Mastra의 복합 스토리지 인터페이스를 구현하므로`OracleStore`인스턴스는 Memory, Workflow 스냅샷, Observability, 점수, 채점자 정의, MCP 클라이언트 메타데이터 및 Agent 레지스트리 데이터를 지원할 수 있습니다.

## 설치

**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`): OracleStore와 OracleVector가 하나의 Oracle 풀을 공유하도록 하는 공유 Oracle 풀 관리자입니다.

**schemaName** (`string`): 저장소 테이블을 정규화하는 데 사용되는 Oracle 스키마 이름입니다.

**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`): Wallet 구성에서 요구하는 경우 사용하는 Oracle Wallet 비밀번호입니다.

**externalAuth** (`boolean`): 사용자 이름/비밀번호 인증 대신 Oracle 외부 인증을 사용합니다.

**disableInit** (`boolean`): true이면 자동 스키마 초기화가 비활성화됩니다. 앱이 시작되기 전에 스키마 변경 사항을 별도로 적용하는 경우 사용합니다. (Default: `false`)

**messageBatchSize** (`number`): 메시지를 저장할 때 Oracle executeMany 호출당 전송되는 메시지 수입니다. 작업은 여전히 트랜잭션 경계에서 한 번만 커밋됩니다. (Default: `200`)

**skipDefaultIndexes** (`boolean`): true이면 초기화 중에 기본 저장소 인덱스가 생성되지 않습니다.

**indexes** (`OracleCreateIndexOptions[]`): 초기화 중에 생성할 사용자 정의 Oracle 인덱스 정의입니다. 인덱스는 대상 테이블을 소유한 저장소 도메인으로 라우팅됩니다.

**migrationTableName** (`string`): 저장소 스키마 마이그레이션을 추적하는 데 사용되는 Oracle 테이블입니다. (Default: `'MASTRA_ORACLE_MIGRATIONS'`)

**vectorRegistryTableName** (`string`): 스레드 또는 메시지가 삭제될 때 의미론적 회상 벡터 테이블을 검색하는 데 사용되는 OracleVector 레지스트리 테이블입니다. 해당 옵션을 사용자 정의한 경우 OracleVector의 registryTableName과 일치하도록 설정하세요.

## 연결 예

기본 사용자 이름/비밀번호 생성자는 위에 나와 있습니다. 자율 데이터베이스의 경우 동일한 생성자에 지갑 옵션을 추가합니다.

```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, 점수, 채점자 정의, MCP 클라이언트 메타데이터 및 Agent 레지스트리 데이터를 지원합니다. `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()
```

반복 가능한 마이그레이션은 멱등성을 갖습니다. 시작 시 각 스토리지 도메인이 소유한 테이블과 인덱스를 조정하므로 애플리케이션 코드를 변경하지 않고도 새 도메인 인덱스나 호환 가능한 스키마 추가 사항을 적용할 수 있습니다.

초기화 과정에서는 일반적인 Mastra 쿼리 경로를 위한 Provider의 기본 인덱스도 생성됩니다. 인덱스를 별도로 관리하는 경우 `skipDefaultIndexes`를 사용하고, 사용자 정의 Oracle 인덱스에는 `indexes`를 전달합니다. 사용자 정의 정의는 `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`를 사용하세요. 별도의 배포 단계나 데이터베이스 관리자가 스키마 변경 사항을 적용하는 경우 `disableInit: true`를 사용하세요.

## 스키마 내보내기

데이터베이스에 연결하지 않고 Oracle DDL을 생성하려면 `exportSchemas()`를 사용하세요. 애플리케이션 시작 외부에서 스키마 변경 사항을 검토하거나 적용할 때 유용합니다.

```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 메타데이터, 페이로드 및 스냅샷은 기본 Oracle JSON 열에 저장되고 서버 측에 인코딩되므로 DBeaver 및 SQL Developer와 같은 표준 Oracle JDBC Tool을 사용하여 행을 직접 읽을 수 있습니다.

## 사용예

### 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/ko/reference/vectors/oracledb)
- [스토리지 개요](https://mastra.zisheng.pro/ko/reference/storage/overview)
- [작업기억](https://mastra.zisheng.pro/ko/docs/memory/working-memory)
- [Workflow 스냅샷](https://mastra.zisheng.pro/ko/docs/workflows/snapshots)