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

# DuckDB 스토리지

[덕DB](https://duckdb.org/)내장된 프로세스 내 분석 데이터베이스입니다. 그만큼`@mastra/duckdb`패키지는 외부 서비스를 실행하지 않고도 추적, 로그, 메트릭, 점수 및 피드백에 적합한 로컬 개발을 위한 OLAP 지원 관찰 저장소를 제공합니다.

벡터 검색은 동일한 패키지의 별도 API인 [DuckDB 벡터 스토어 레퍼런스](https://mastra.zisheng.pro/ko/reference/vectors/duckdb)를 참조하세요.

## DuckDB를 사용하는 경우

Observability 기능의 로컬 개발. DuckDB는 내장형이며 파일 기반이므로 서버가 필요하지 않고 즉시 시작됩니다. ClickHouse와 동일한 Observability 신호를 지원하므로 프로덕션 백엔드에 배포하기 전에 대시보드를 테스트하고 탐색을 추적하는 데 유용합니다.

DuckDB는 현재 `observability` 도메인만 구현합니다. [복합 스토리지](https://mastra.zisheng.pro/ko/reference/storage/composite) 구성에서 `memory`와 `workflows`에는 다른 스토리지 어댑터(예: [LibSQL](https://mastra.zisheng.pro/ko/reference/storage/libsql))를 함께 사용하세요.

> **경고:** DuckDB는 개발용이므로 프로덕션용으로는 권장되지 않습니다. 프로세스 내에서 실행되고 단일 로컬 파일에 유지되며 임시 파일 시스템(예: Railway, Fly.io, Render, Heroku 또는 서버리스 컨테이너)이 있는 플랫폼에서는 작동하지 않습니다. 프로덕션 관찰성을 위해서는 다음을 사용하세요.[ClickHouse](https://mastra.zisheng.pro/ko/reference/storage/clickhouse).

## 설치

**npm**:

```bash
npm install @mastra/duckdb@latest
```

**pnpm**:

```bash
pnpm add @mastra/duckdb@latest
```

**Yarn**:

```bash
yarn add @mastra/duckdb@latest
```

**Bun**:

```bash
bun add @mastra/duckdb@latest
```

## 용법

### 복합 저장소의 Observability 도메인

이는 표준 로컬 개발 설정입니다. LibSQL은 다른 도메인을 처리하고 DuckDB는 Observability을 처리합니다.

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: new DuckDBStore().observability,
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})
```

`.observability` 접근자는 Observability 도메인 스토어를 직접 반환합니다. 이에 해당하는 일반 형식은 모든 복합 스타일 스토리지 어댑터에서 작동하는 `getStore()`를 사용합니다.

```typescript
const observability = await new DuckDBStore().getStore('observability')
```

### 독립형

`Mastra` 복합 스토리지 외부에서 Observability 스토어만 필요한 경우 `DuckDBStore`를 직접 인스턴스화하고 Observability 도메인에 액세스하세요.

```typescript
import { DuckDBStore } from '@mastra/duckdb'

const duckdb = new DuckDBStore({ path: './traces.duckdb' })
const observability = duckdb.observability

await observability.init()
```

### 인Memory 데이터베이스

일시적인 DuckDB 인스턴스를 사용하려면 `:memory:`를 전달하세요. 프로세스가 종료되면 데이터가 손실되므로 단위 테스트와 수명이 짧은 스크립트에 적합합니다.

```typescript
const duckdb = new DuckDBStore({ path: ':memory:' })
```

## 구성

### `DuckDBStore`옵션

**id** (`string`): 이 스토리지 인스턴스의 고유 식별자입니다. (Default: `'duckdb'`)

**path** (`string`): DuckDB 데이터베이스 파일의 경로입니다. 일시적인 인메모리 데이터베이스에는 :memory:를 사용하세요. (Default: `'mastra.duckdb'`)

**memoryLimit** (`string`): DuckDB가 사용할 수 있는 최대 메모리입니다(예: '2GB' 또는 '512MB'). 파일 기반 데이터베이스에서 메모리보다 큰 작업은 디스크를 사용합니다. 전용 분석 워크로드에서는 이 값을 높이세요. (Default: `'2GB'`)

**threads** (`number`): DuckDB가 사용할 수 있는 스레드 수입니다. 공유 애플리케이션 서버에서 쿼리가 모든 코어를 독점하지 않도록 하려면 이 값을 낮추세요. (Default: `CPU 코어당 하나`)

### 하위 수준 유형

`@mastra/duckdb`는 여러 Mastra 스토리지 인스턴스가 하나의 기반 데이터베이스를 공유할 수 있게 하는 `DuckDBConnection`과 이에 대응하는 `DuckDBStorageConfig` 유형도 내보냅니다. 대부분의 애플리케이션에서는 이를 직접 사용할 필요가 없습니다.

## 지원되는 도메인

DuckDB는 현재 하나의 스토리지 도메인을 구현합니다.

| 도메인             | 지원됨 |
| --------------- | --- |
| `observability` | Yes |
| `memory`        | No  |
| `workflows`     | No  |
| `scores`        | No  |
| `agents`        | No  |

완전한 스토리지 솔루션을 구성하려면 누락된 도메인을 지원하는 어댑터와 `DuckDBStore`를 함께 구성하세요. 로컬 개발에서는 보통 [LibSQL](https://mastra.zisheng.pro/ko/reference/storage/libsql)을 사용합니다.

## 초기화

`MastraCompositeStore`를 통해 `Mastra`에 전달하면 Observability 도메인이 처음 사용될 때 자체적으로 초기화됩니다. `Mastra` 외부에서 명시적으로 초기화하려면 Observability 스토어에서 `init()`을 호출하세요.

```typescript
import { DuckDBStore } from '@mastra/duckdb'

const duckdb = new DuckDBStore({ path: './traces.duckdb' })
await duckdb.observability.init()
```

## Observability 전략

DuckDB는 `MastraStorageExporter`가 사용하는 `event-sourced` 전략을 지원합니다. 이 전략은 스팬을 메모리에 버퍼링하고 완료된 이벤트를 배치 단위로 기록합니다. 개발 규모의 트래픽에 적합합니다. 트래픽이 많은 프로덕션 워크로드에 대해서는 [`MastraStorageExporter` 스토리지 Provider 지원](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage)을 참조하세요.

## 관련된

- [스토리지 개요](https://mastra.zisheng.pro/ko/reference/storage/overview)
- [복합 스토리지](https://mastra.zisheng.pro/ko/reference/storage/composite)
- [클릭하우스 스토리지](https://mastra.zisheng.pro/ko/reference/storage/clickhouse): 프로덕션 관측성 백엔드
- [DuckDB 벡터 저장소](https://mastra.zisheng.pro/ko/reference/vectors/duckdb): 동일한 패키지를 이용한 벡터 검색
- [Observability 개요](https://mastra.zisheng.pro/ko/docs/observability/overview)