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

# libSQL 스토리지

[libSQL](https://docs.turso.tech/libsql)로컬 및 원격 배포를 모두 지원하는 오픈 소스 SQLite 호환 데이터베이스입니다. 메시지 기록, Workflow 스냅샷, 추적 및 평가 점수를 저장하는 데 사용할 수 있습니다.

의미 기반 회상이나 기존 RAG와 같은 벡터 기능은 임베딩과 벡터 검색을 지원하는 [libSQL Vector](https://mastra.zisheng.pro/ko/reference/vectors/libsql)를 사용하세요.

## 설치

스토리지 공급자는 별도의 패키지로 설치해야 합니다.

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## 용법

```typescript
import { LibSQLStore } from '@mastra/libsql'
import { Mastra } from '@mastra/core'

const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'libsql-storage',
    url: 'file:./storage.db',
  }),
})
```

Agent 수준 파일 저장소:

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'

export const agent = new Agent({
  id: 'example-agent',
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'libsql-storage',
      url: 'file:./agent.db',
    }),
  }),
})
```

> **경고:** 파일 스토리지는 임시 파일 시스템을 사용하는 서버리스 플랫폼에서 작동하지 않습니다. 서버리스 배포에는 [Turso](https://turso.tech) 또는 다른 데이터베이스 엔진을 사용하세요.

원격 데이터베이스를 사용한 프로덕션:

```typescript
storage: new LibSQLStore({
  id: 'libsql-storage',
  url: 'libsql://your-db-name.aws-ap-northeast-1.turso.io',
  authToken: process.env.TURSO_AUTH_TOKEN,
})
```

로컬 개발 및 테스트를 위해 데이터를 Memory에 저장할 수 있습니다.

```typescript
storage: new LibSQLStore({
  id: 'libsql-storage',
  url: ':memory:',
})
```

> **경고:** 프로세스가 변경되면 Memory 내 저장소가 재설정됩니다. 개발에만 적합합니다.

## 옵션

**url** (`string`): 데이터베이스 URL입니다. 인메모리 데이터베이스에는 :memory:, 파일 데이터베이스에는 file:filename.db, 원격 스토리지에는 libSQL 연결 문자열(예: libsql://your-database.turso.io)을 사용하세요.

**authToken** (`string`): 원격 libSQL 데이터베이스의 인증 토큰입니다.

## 관리되는 테이블

스토리지 구현은 알림 수신함 레코드와 전달 메타데이터를 위한 `mastra_notifications`를 비롯하여 핵심 스토리지 테이블을 자동으로 생성합니다. `LibSQLStore`다음을 통해 알림 저장소를 노출합니다.`getStore('notifications')`.

## 초기화

스토리지를 Mastra 클래스에 전달하면 [핵심 스키마](https://mastra.zisheng.pro/ko/reference/storage/overview)를 생성하도록 `init()`이 자동으로 호출됩니다.

```typescript
import { Mastra } from '@mastra/core'
import { LibSQLStore } from '@mastra/libsql'

const storage = new LibSQLStore({
  id: 'libsql-storage',
  url: 'file:./storage.db',
})

const mastra = new Mastra({
  storage, // init() called automatically
})
```

Mastra 없이 직접 저장소를 사용하는 경우`init()` explicitly:

```typescript
import { LibSQLStore } from '@mastra/libsql'

const storage = new LibSQLStore({
  id: 'libsql-storage',
  url: 'file:./storage.db',
})

await storage.init()

// Access domain-specific stores via getStore()
const memoryStore = await storage.getStore('memory')
const thread = await memoryStore?.getThreadById({ threadId: '...' })
```

## Observability

libSQL은 Observability을 지원하며 로컬 개발에 적합합니다. 디버깅 중 즉시 확인하려면 `realtime` [Trace 전략](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage)을 사용하세요. Trace 양이 많은 프로덕션 환경에서는 [PostgreSQL](https://mastra.zisheng.pro/ko/reference/storage/postgresql) 또는 [복합 스토리지를 통한 ClickHouse](https://mastra.zisheng.pro/ko/reference/storage/composite)를 사용하는 것이 좋습니다.