DuckDB 스토리지

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

벡터 검색은 동일한 패키지의 별도 API인 DuckDB 벡터 스토어 레퍼런스를 참조하세요.

DuckDB를 사용하는 경우

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

DuckDB는 현재 observability 도메인만 구현합니다. 복합 스토리지 구성에서 memory와 workflows에는 다른 스토리지 어댑터(예: LibSQL)를 함께 사용하세요.

경고

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

설치

npm

npm install @mastra/duckdb@latest

pnpm

pnpm add @mastra/duckdb@latest

Yarn

yarn add @mastra/duckdb@latest

Bun

bun add @mastra/duckdb@latest

용법

복합 저장소의 Observability 도메인

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

src/mastra/index.ts

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()를 사용합니다.

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

독립형

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

import { DuckDBStore } from '@mastra/duckdb'

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

await observability.init()

인Memory 데이터베이스

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

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

구성

DuckDBStore옵션

id?:

string

= 'duckdb'

이 스토리지 인스턴스의 고유 식별자입니다.

path?:

string

= 'mastra.duckdb'

DuckDB 데이터베이스 파일의 경로입니다. 일시적인 인메모리 데이터베이스에는 :memory:를 사용하세요.

memoryLimit?:

string

= '2GB'

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

threads?:

number

= CPU 코어당 하나

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

하위 수준 유형

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

지원되는 도메인

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

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

완전한 스토리지 솔루션을 구성하려면 누락된 도메인을 지원하는 어댑터와 DuckDBStore를 함께 구성하세요. 로컬 개발에서는 보통 LibSQL을 사용합니다.

초기화

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

import { DuckDBStore } from '@mastra/duckdb'

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

Observability 전략

DuckDB는 MastraStorageExporter가 사용하는 event-sourced 전략을 지원합니다. 이 전략은 스팬을 메모리에 버퍼링하고 완료된 이벤트를 배치 단위로 기록합니다. 개발 규모의 트래픽에 적합합니다. 트래픽이 많은 프로덕션 워크로드에 대해서는 MastraStorageExporter 스토리지 Provider 지원을 참조하세요.

관련된

• 스토리지 개요
• 복합 스토리지
• 클릭하우스 스토리지: 프로덕션 관측성 백엔드
• DuckDB 벡터 저장소: 동일한 패키지를 이용한 벡터 검색
• Observability 개요