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

# 클릭하우스 스토리지

[클릭하우스](https://clickhouse.com/)분석 워크로드를 위해 설계된 컬럼형 데이터베이스입니다. 그만큼`@mastra/clickhouse`패키지는 여러 Mastra 스토리지 도메인에 대한 스토리지 어댑터를 제공하며 프로덕션 관찰성을 위해 권장되는 백엔드입니다.

ClickHouse는 일반적으로 [복합 저장소](https://mastra.zisheng.pro/ko/reference/storage/composite) 구성에서 전용 Observability 백엔드로 사용하며, 나머지 도메인은 다른 데이터베이스에서 처리합니다.

## ClickHouse를 사용하는 경우

추적, 로그, 지표, 점수 및 피드백에 대한 프로덕션 Observability.

로컬 개발에는 [LibSQL](https://mastra.zisheng.pro/ko/reference/storage/libsql)(Memory 및 Workflow용)과 `@mastra/duckdb`(Observability용)를 결합한 복합 저장소를 사용하세요. 어느 하나만으로는 개발 환경을 완전히 지원하지 못합니다. LibSQL은 Observability 도메인을 구현하지 않고 DuckDB는 다른 도메인을 구현하지 않습니다. 예시는 [Observability 개요](https://mastra.zisheng.pro/ko/docs/observability/overview)를 참조하세요.

## 설치

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

실행 중인 ClickHouse 서버도 필요합니다. 관리형 및 자체 호스팅 옵션은 [호스팅 옵션](#hosting-options)을 참조하세요.

## 용법

### vNext를 통한 Observability(권장)

`ObservabilityStorageClickhouseVNext`는 현재 Observability 도메인 구현입니다. `ReplacingMergeTree`가 지원하는 삽입 전용 스키마를 사용하며 Trace, 로그, 메트릭, 점수 및 피드백에서 생성되는 데이터 양에 최적화되어 있습니다. Observability 쓰기가 애플리케이션 데이터와 경합하지 않도록 다른 스토리지 어댑터와 함께 구성하십시오.

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { PostgresStore } from '@mastra/pg'
import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
import { Observability, MastraStorageExporter } from '@mastra/observability'

const observabilityStore = new ObservabilityStorageClickhouseVNext({
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD!,
})

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new PostgresStore({
      id: 'pg',
      connectionString: process.env.DATABASE_URL!,
    }),
    domains: {
      observability: observabilityStore,
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})
```

ClickHouse가 Observability 백엔드인 경우 `MastraStorageExporter`는 쓰기 처리량이 가장 높은 `insert-only` 전략을 자동으로 선택합니다. 자세한 내용은 [추적 전략](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage)을 참조하세요.

### 레거시 도메인에 대한 Observability

`ObservabilityStorageClickhouse`원래 관찰성 어댑터이며 vNext 스키마로 마이그레이션되지 않은 프로젝트에 대해 계속 지원됩니다. 구성 형태는 vNext 클래스와 동일합니다.

```typescript
import { ObservabilityStorageClickhouse } from '@mastra/clickhouse'

const observabilityStore = new ObservabilityStorageClickhouse({
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD!,
})
```

새 프로젝트에서는 다음을 사용해야 합니다.`ObservabilityStorageClickhouseVNext` instead.

### 레거시에서 vNext로 마이그레이션

레거시 `mastra_ai_spans` 테이블에서 vNext 스키마로 스팬을 마이그레이션하려면 다음을 실행하세요.

**npm**:

```bash
npx mastra migrate
```

**pnpm**:

```bash
pnpm dlx mastra migrate
```

**Yarn**:

```bash
yarn dlx mastra migrate
```

**Bun**:

```bash
bun x mastra migrate
```

마이그레이션은 `mastra_ai_spans`의 스팬 데이터를 하루 단위 배치로 `mastra_span_events`에 복사합니다. 열 매핑을 처리하고 레거시 행의 중복을 제거합니다. 원본 테이블은 백업으로 유지됩니다. 마이그레이션 후에는 vNext 어댑터를 통해 Studio에 Trace가 표시됩니다. :::참고 레거시 테이블은 삭제되지 않습니다. 마이그레이션을 확인한 후 수동으로 삭제하세요. :::

### 모든 도메인에 대한 ClickHouse

`ClickhouseStoreVNext`는 ClickHouse로 `memory`, `workflows`, `observability` 도메인을 지원하고 vNext Observability 어댑터를 자동으로 사용합니다. 복합 저장소를 수동으로 연결하지 않고 전체 애플리케이션을 ClickHouse로 지원하려는 경우 사용하세요.

```typescript
import { Mastra } from '@mastra/core'
import { ClickhouseStoreVNext } from '@mastra/clickhouse'

export const mastra = new Mastra({
  storage: new ClickhouseStoreVNext({
    id: 'clickhouse-storage',
    url: process.env.CLICKHOUSE_URL!,
    username: process.env.CLICKHOUSE_USERNAME!,
    password: process.env.CLICKHOUSE_PASSWORD!,
  }),
})
```

`ClickhouseStoreVNext`는 `ClickhouseStore`와 동일한 구성을 허용하고 모든 도메인에서 동일한 ClickHouse 클라이언트를 재사용합니다.

#### 매뉴얼 구성

`ClickhouseStore`는 레거시 Observability 어댑터를 사용하여 모든 도메인을 지원해 온 기존 클래스입니다. 새 프로젝트에서는 `ClickhouseStoreVNext`를 사용하는 것이 좋습니다. 복합 저장소를 사용자 지정해야 한다면(예: 한 도메인을 다른 백엔드로 재정의) 수동으로 구성하세요.

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { ClickhouseStore, ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'

const credentials = {
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD!,
}

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new ClickhouseStore({ id: 'clickhouse-storage', ...credentials }),
    domains: {
      observability: new ObservabilityStorageClickhouseVNext(credentials),
    },
  }),
})
```

### 나만의 ClickHouse 클라이언트 가져오기

요청 시간 초과, 압축 또는 인터셉터와 같은 사용자 정의 연결 설정이 필요한 경우 사전 구성된 클라이언트를 전달하십시오.

```typescript
import { createClient } from '@clickhouse/client'
import { ClickhouseStore } from '@mastra/clickhouse'

const client = createClient({
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD!,
  request_timeout: 60_000,
  compression: { request: true, response: true },
})

const storage = new ClickhouseStore({ id: 'clickhouse-storage', client })
```

동일한 `client` 형식을 `ObservabilityStorageClickhouse`와 `ObservabilityStorageClickhouseVNext`에서 사용할 수 있습니다.

## 구성

### `ClickhouseStore`옵션

**id** (`string`): 이 저장소 인스턴스의 고유 식별자입니다.

**url** (`string`): ClickHouse 서버 URL입니다(예: https\://your-instance.clickhouse.cloud:8443 또는 http\://localhost:8123). 미리 구성된 client를 전달하지 않는 경우 필수입니다.

**username** (`string`): ClickHouse 사용자 이름입니다. 미리 구성된 client를 전달하지 않는 경우 필수입니다.

**password** (`string`): ClickHouse 비밀번호입니다. 미리 구성된 client를 전달하지 않는 경우 필수입니다. 로컬 인스턴스의 기본 사용자는 빈 문자열을 사용할 수 있습니다.

**client** (`ClickHouseClient`): @clickhouse/client에서 미리 구성한 ClickHouse 클라이언트입니다. 사용자 지정 요청 설정이 필요할 때 사용하세요. 위의 자격 증명 필드와 함께 사용할 수 없습니다.

**ttl** (`object`): 테이블 생성 시 적용되는 테이블별 TTL 구성입니다. NANOSECOND부터 YEAR까지의 간격 단위로 행 수준 및 열 수준 TTL을 허용합니다.

**replication** (`{ cluster?: string; zookeeperPath?: string; replicaName?: string }`): 다중 복제본 ClickHouse 클러스터를 위한 선택적 복제 테이블 구성입니다. 설정하면 Mastra가 복제된 MergeTree 테이블을 생성합니다. cluster가 설정된 경우 Mastra가 소유한 데이터 정의 언어(DDL)에 ON CLUSTER도 추가합니다.

**disableInit** (`boolean`): true이면 저장소가 처음 사용될 때 테이블 생성이나 마이그레이션을 실행하지 않습니다. 배포 스크립트에서 storage.init()을 명시적으로 호출하세요. (Default: `false`)

`ClickhouseStore`는 `ClickHouseClientConfigOptions`의 모든 옵션(예: `database`, `request_timeout`, `compression`, `keep_alive`, `max_open_connections`)도 허용합니다.

### 복제된 클러스터

Mastra가 로드 밸런서를 통해 다중 복제본 ClickHouse 클러스터에 쓸 때 `replication`을 사용하세요.

```typescript
const storage = new ClickhouseStoreVNext({
  id: 'clickhouse-storage',
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD!,
  replication: {
    cluster: 'company_cluster',
  },
})
```

`replication`이 설정되면 Mastra는 `MergeTree`와 `ReplacingMergeTree` 테이블 엔진을 `ReplicatedMergeTree`와 `ReplicatedReplacingMergeTree`로 변경합니다. 기본 엔진 인수는 다음과 같습니다.

- `zookeeperPath`: `'/clickhouse/tables/{shard}/{database}/{table}'`
- `replicaName`: `'{replica}'`

기본값은 가장 일반적인 자체 관리 규칙과 일치합니다. 클러스터의 기존 테이블이 다른 레이아웃을 사용하는 경우(예: `{database}` 세그먼트가 없는 `/clickhouse/tables/{shard}/{table}`) 이에 맞게 `zookeeperPath`를 명시적으로 설정하세요. Mastra는 Keeper에서 클러스터 규칙을 읽지 않으므로 기본값이 일치하지 않으면 Mastra의 메타데이터가 클러스터의 나머지 부분과 별도 분기에 기록됩니다.

```typescript
new ClickhouseStoreVNext({
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD!,
  replication: {
    cluster: 'company_cluster',
    zookeeperPath: '/clickhouse/tables/{shard}/{table}',
  },
})
```

테이블 생성, 구체화된 뷰 생성, 열 마이그레이션, TTL 변경 및 테이블 삭제와 같이 Mastra가 소유한 DDL에 `ON CLUSTER`를 추가하려면 `cluster`를 설정하세요. `cluster`가 설정되면 `optimizeTable()` 및 `materializeTtl()`과 같은 수동 유지 관리가 모든 복제본에서 실행됩니다. 이러한 작업은 대규모 클러스터에서 비용이 많이 들 수 있습니다. 사용량이 적은 시간대에 실행하고, 재시작할 때마다 트리거하기보다는 일상적인 병합이 백그라운드 병합 대기열에서 처리되도록 하세요. 기존 Mastra 테이블이 로컬 `MergeTree` 또는 `ReplacingMergeTree` 엔진을 사용하는 경우 `replication`이 활성화된 상태에서는 초기화에 실패합니다. 복제본 간 복사 및 교체는 안전하지 않으므로 Mastra는 로컬 테이블을 자동으로 변환하지 않습니다. 마이그레이션하려면 복제를 활성화하기 전에 영향을 받는 테이블을 `Replicated*`로 다시 생성하세요. 안전하게 마이그레이션하려면 로컬 테이블의 이름을 변경하고 `CREATE TABLE ... ENGINE = ReplicatedMergeTree(...) ON CLUSTER ...`를 실행한 다음 `INSERT INTO ... SELECT * FROM <renamed_local>`을 실행하고 `<renamed_local>`을 삭제하세요. ClickHouse Cloud에서는 `replication`을 설정하지 마세요. Cloud는 서버 측에서 `MergeTree`를 `SharedMergeTree`로 변경하며, 명시적인 `ReplicatedMergeTree` 엔진은 잘못된 DDL을 생성합니다. `replication`은 자체 관리형 다중 복제본 클러스터에만 사용합니다.

### Observability 도메인 옵션

`ObservabilityStorageClickhouse`와 `ObservabilityStorageClickhouseVNext`는 `ClickhouseStore`와 동일한 연결 옵션(`url`, `username`, `password` 또는 미리 구성된 `client`)을 허용합니다.

## 호스팅 옵션

ClickHouse는 HTTP를 통해 연결할 수 있는 모든 곳에서 실행됩니다. 일반적인 선택 사항은 다음과 같습니다.

- **[ClickHouse Cloud](https://clickhouse.com/cloud)**: 무료 평가판을 제공하는 관리형 서비스입니다. `url`, `username`, `password`와 직접 호환되는 연결 정보를 제공합니다.
- **자체 호스팅**: 공식 [`clickhouse/clickhouse-server`](https://hub.docker.com/r/clickhouse/clickhouse-server) 컨테이너를 실행하거나 [공식 패키지](https://clickhouse.com/docs/en/install)로 설치합니다. VPS, 전용 하드웨어 또는 Kubernetes에 적합합니다. 지역 개발을 위해:

```bash
docker run -d --name mastra-clickhouse \
  -p 8123:8123 -p 9000:9000 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=password \
  clickhouse/clickhouse-server
```

```typescript
new ObservabilityStorageClickhouseVNext({
  url: 'http://localhost:8123',
  username: 'default',
  password: 'password',
})
```

## 철도 및 유사한 플랫폼으로 배포

[Railway](https://railway.com), [Fly.io](https://fly.io), [Render](https://render.com), Heroku와 같은 플랫폼은 임시 파일 시스템에서 애플리케이션 컨테이너를 실행합니다. DuckDB와 같은 임베디드 Observability 백엔드에는 쓰기 가능한 영구 로컬 파일이 필요하므로 이러한 플랫폼에서는 재시작 시 데이터가 손실되거나 아예 배포되지 않을 수 있습니다. 대신 ClickHouse를 사용하세요. ClickHouse는 HTTP를 통해 연결되므로 모든 호스트에서 동일한 연결이 작동합니다.

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { PostgresStore } from '@mastra/pg'
import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new PostgresStore({
      id: 'pg',
      connectionString: process.env.DATABASE_URL!,
    }),
    domains: {
      observability: new ObservabilityStorageClickhouseVNext({
        url: process.env.CLICKHOUSE_URL!,
        username: process.env.CLICKHOUSE_USERNAME!,
        password: process.env.CLICKHOUSE_PASSWORD!,
      }),
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})
```

다음 옵션 중 하나로 데이터베이스를 프로비저닝합니다.

- **관리형**: ClickHouse Cloud를 사용하세요. 호스팅 플랫폼에서 `CLICKHOUSE_URL`, `CLICKHOUSE_USERNAME`, `CLICKHOUSE_PASSWORD`를 환경 변수로 설정합니다.
- **Railway에서 자체 호스팅**: 공식 Docker 이미지로 Railway 프로젝트에 ClickHouse 서비스를 추가한 다음 Railway의 비공개 네트워킹을 통해 애플리케이션 서비스에서 참조합니다. 임시 파일 시스템을 사용하는 다른 호스트에도 동일한 접근 방식이 적용됩니다. 호스트 외부에도 존재해야 하는 애플리케이션 데이터의 경우 이 설정을 관리형 PostgreSQL 또는 LibSQL/Turso 인스턴스와 페어링하세요.`default` storage.

> **경고:** 임시 컨테이너 파일 시스템 내부 경로에서 DuckDB와 같은 임베디드 백엔드를 가리키지 마세요. 거기에 기록된 데이터는 컨테이너가 다시 시작되면 손실되며 일부 플랫폼에서는 경로가 읽기 전용입니다.

## 초기화

`Mastra` 클래스에 전달하면 `ClickhouseStore`가 `init()`을 자동으로 호출하여 스키마를 생성하고 대기 중인 마이그레이션을 실행합니다. `MastraCompositeStore`를 통해 사용하는 `ObservabilityStorageClickhouseVNext`에도 동일하게 적용됩니다. 외부에서 스토리지를 관리하는 경우`Mastra`, call `init()` explicitly:

```typescript
import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'

const observability = new ObservabilityStorageClickhouseVNext({
  url: process.env.CLICKHOUSE_URL!,
  username: process.env.CLICKHOUSE_USERNAME!,
  password: process.env.CLICKHOUSE_PASSWORD!,
})

await observability.init()
```

CI/CD 파이프라인에서는 `ClickhouseStore`에 `disableInit: true`를 설정하고 높은 권한의 자격 증명을 사용하는 배포 단계에서 `init()`을 실행하세요. 그러면 런타임 애플리케이션 자격 증명의 권한을 읽기와 삽입으로 제한할 수 있습니다.

## Observability

ClickHouse는 프로덕션 Observability을 위해 권장되는 백엔드입니다.

- **삽입 전용 전략**: `MastraStorageExporter`는 스팬별 업데이트 없이 완료된 스팬을 배치로 기록합니다. 이는 사용 가능한 전략 중 처리량이 가장 높습니다.
- **열 기반 압축**: 스팬 속성과 로그 페이로드는 행 기반 데이터베이스의 동일한 데이터보다 효율적으로 압축됩니다. 전체 전략 매트릭스 및 생산 지침은 다음을 참조하세요.[`MastraStorageExporter` reference](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)
- [`MastraStorageExporter`](https://mastra.zisheng.pro/ko/docs/observability/integrations/exporters/mastra-storage)
- [Observability 개요](https://mastra.zisheng.pro/ko/docs/observability/overview)