> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

> ClickHouse를 CloudThinker에 연결하여 스키마 검사, 분석 쿼리 조사, 선택적 쓰기 접근을 수행합니다

ClickHouse 클러스터를 연결하면 [Tony](/ko/guide/agents/tony) (Database Engineer)가 스키마를 탐색하고, 테이블 상태를 점검하며, 분석 SQL로 질문에 답할 수 있습니다. 새로 만든 연결은 읽기 전용입니다. CloudThinker는 모든 쿼리를 ClickHouse의 `readonly` 설정이 활성화된 상태로 전송합니다. 에이전트가 데이터를 변경하도록 하려면 **Write access**를 켜고, 객체를 제거하도록 하려면 **Allow DROP and TRUNCATE**를 별도로 켜세요.

## 사전 요구사항

* **HTTP 인터페이스**를 통해 CloudThinker에서 접근 가능한 ClickHouse 서버 (TLS 사용 시 `8443`, 미사용 시 `8123`). ClickHouse Cloud, 자체 호스팅 클러스터, Kubernetes에서 오퍼레이터가 운영하는 클러스터, 다른 업체의 관리형 ClickHouse 모두 동작합니다. CloudThinker에 필요한 것은 그 포트 하나뿐입니다.
* 전용 사용자를 생성할 관리자 접근.
* 네이티브 TCP 포트(`9000`)는 사용하지 않으므로 노출할 필요가 없습니다.

## 설정

<Steps>
  <Step title="전용 사용자 생성">
    관리자로 연결한 뒤 CloudThinker 사용자를 생성하세요:

    ```sql theme={null}
    CREATE USER cloudthinker IDENTIFIED BY 'your-secure-password';
    ```
  </Step>

  <Step title="읽기 권한 부여">
    에이전트가 볼 데이터베이스에 `SELECT` 권한과 함께 `SHOW` 권한을 부여하세요:

    ```sql theme={null}
    GRANT SELECT ON your_database.* TO cloudthinker;
    GRANT SHOW DATABASES, SHOW TABLES, SHOW COLUMNS ON *.* TO cloudthinker;
    ```
  </Step>

  <Step title="사용자를 읽기 전용으로 고정 (권장)">
    연결은 기본적으로 읽기 전용이지만, 설정 프로파일을 사용하면 클라이언트와 무관하게 서버 측에서 제한이 유지됩니다:

    ```sql theme={null}
    CREATE SETTINGS PROFILE cloudthinker_readonly SETTINGS readonly = 1 READONLY;
    ALTER USER cloudthinker SETTINGS PROFILE cloudthinker_readonly;
    ```

    **Write access**를 켤 계획이라면 이 단계를 건너뛰세요. 이 프로파일은 `READONLY`를 사용하므로 사용자가 해제할 수 없고, CloudThinker의 스위치로도 무효화할 수 없습니다.
  </Step>

  <Step title="시스템 테이블 접근 허용 (선택)">
    테이블 크기, 파트 수, 컬럼 메타데이터는 `system`에서 가져옵니다:

    ```sql theme={null}
    GRANT SELECT ON system.tables TO cloudthinker;
    GRANT SELECT ON system.columns TO cloudthinker;
    GRANT SELECT ON system.parts TO cloudthinker;
    ```
  </Step>

  <Step title="네트워크 접근 설정">
    CloudThinker에 HTTP 인터페이스를 개방하세요:

    * ClickHouse Cloud: 서비스의 **Settings → Security**에 있는 **IP 접근 목록**에 CloudThinker를 추가하세요.
    * 자체 호스팅: 방화벽 또는 보안 그룹에서 CloudThinker로부터의 인바운드 `8443`(또는 `8123`)을 허용하세요.
  </Step>

  <Step title="CloudThinker에 연결 추가">
    **Connections → ClickHouse**로 이동하여 다음을 입력하세요:

    * **Host**: 스킴과 포트를 제외한 호스트명만, 예: `abc123.ap-southeast-1.aws.clickhouse.cloud`
    * **Port**: TLS 사용 시 `8443`, 미사용 시 `8123`
    * **Username**: `cloudthinker`
    * **Password**: 위에서 설정한 비밀번호
    * **Use TLS**: ClickHouse Cloud 및 모든 공개 엔드포인트에서는 `Yes`
    * **Verify the TLS certificate**: `Yes`로 두세요. 자체 서명 인증서나 내부 CA 인증서일 때만 끄세요
    * **Default database**: 선택 사항. 비워 두면 서버 기본값을 사용합니다
    * **Write access**: 에이전트가 데이터를 변경해야 하는 경우가 아니면 `Read-only`로 두세요
    * **Allow DROP and TRUNCATE**: 쓰기 접근을 켠 뒤에만 표시됩니다. 에이전트가 객체를 제거하도록 하려는 경우가 아니면 `Blocked`로 두세요

    **Connect**를 클릭하세요. CloudThinker는 해당 사용자로 `SELECT version()`을 한 번 실행해 자격 증명을 확인하며, **Connected** 메시지에는 도달한 ClickHouse 버전, 사용한 사용자 이름, 그리고 기본 데이터베이스를 설정했다면 그 이름이 표시됩니다. 그 외의 경우에는 구체적인 이유가 반환됩니다. [문제 해결](#문제-해결)을 참고하세요.
  </Step>
</Steps>

## 연결 세부 정보

| 필드                             | 설명                                              | 기본값         |
| ------------------------------ | ----------------------------------------------- | ----------- |
| **Host**                       | 호스트명 또는 IP, 스킴과 포트 제외                           | —           |
| **Port**                       | HTTP 인터페이스 포트                                   | `8443`      |
| **Username**                   | 전용 사용자, 예: `cloudthinker`                       | —           |
| **Password**                   | 사용자 비밀번호                                        | —           |
| **Use TLS**                    | 일반 HTTP 대신 HTTPS 사용                             | `Yes`       |
| **Verify the TLS certificate** | 자체 서명 인증서나 내부 CA 인증서일 때만 끄세요. TLS가 꺼져 있으면 숨겨집니다 | `Yes`       |
| **Default database**           | 쿼리가 테이블을 한정하지 않을 때 사용할 데이터베이스                   | 서버 기본값      |
| **Write access**               | 에이전트가 데이터를 변경할 수 있는지 여부                         | `Read-only` |
| **Allow DROP and TRUNCATE**    | 에이전트가 객체를 제거할 수 있는지 여부. 읽기 전용인 동안에는 숨겨집니다       | `Blocked`   |

<Tip>
  `8443`과 TLS는 ClickHouse Cloud의 조합입니다. TLS가 꺼진 자체 호스팅 서버는 `8123`에서 응답하므로, **Use TLS**를 `No`로, 포트를 `8123`으로 함께 설정하세요. 둘이 일치하지 않으면 연결 시점에 실패합니다.
</Tip>

## 필요 권한

### 최소

```sql theme={null}
GRANT SELECT ON your_database.* TO cloudthinker;
GRANT SHOW DATABASES, SHOW TABLES, SHOW COLUMNS ON *.* TO cloudthinker;
```

### 권장 (전체 분석)

```sql theme={null}
-- 위의 모든 권한에 추가:
GRANT SELECT ON system.tables TO cloudthinker;
GRANT SELECT ON system.columns TO cloudthinker;
GRANT SELECT ON system.parts TO cloudthinker;
GRANT SELECT ON system.query_log TO cloudthinker;
```

`system.query_log`는 "이 대시보드가 느리다"를 원인이 되는 쿼리의 순위 목록으로 바꿔 주는 요소입니다.

### 쓰기 접근 (활성화하는 경우에만)

```sql theme={null}
GRANT INSERT, ALTER, CREATE TABLE, CREATE VIEW ON your_database.* TO cloudthinker;
-- 에이전트가 객체를 제거해야 하는 경우에만:
GRANT DROP TABLE, TRUNCATE ON your_database.* TO cloudthinker;
```

이 권한은 에이전트가 변경해야 하는 특정 데이터베이스에만 부여하고, 절대 `*.*`에는 부여하지 마세요. 사용자가 보유하지 않은 권한은 **Write access** 스위치가 넘을 수 없는 경계입니다.

## 에이전트 기능

연결이 완료되면 Tony가 할 수 있는 작업:

| 기능         | 설명                                          |
| ---------- | ------------------------------------------- |
| **스키마 탐색** | 엔진, 정렬 키, 행 수, 컬럼 타입과 함께 데이터베이스 및 테이블 목록 조회 |
| **분석 쿼리**  | 집계, 조인, 윈도우 함수를 포함한 SQL 실행                  |
| **테이블 상태** | 파트 수, 압축 및 비압축 크기, 인덱스 그래뉼래리티 점검            |
| **쿼리 조사**  | `system.query_log`에서 느리거나 비용이 큰 쿼리 순위 산출    |

### 연결 확인

```text theme={null}
@tony #report list the ClickHouse databases and the tables in each one
```

### 예시 프롬프트

```text theme={null}
@tony #report which ClickHouse tables grew the most in the last week
@tony #report show per-service p95 latency from the events table
@tony #recommend suggest a better sorting key for our largest MergeTree table
```

## 쓰기 접근

연결은 읽기 전용 상태로 제공되며, 두 개의 스위치가 한 단계씩 이를 개방합니다.

| Write access      | Allow DROP and TRUNCATE | 에이전트가 할 수 있는 작업                                                                     |
| ----------------- | ----------------------- | ----------------------------------------------------------------------------------- |
| `Read-only` (기본값) | 숨김                      | `SELECT`만 가능. 그 외 모든 작업은 ClickHouse가 `164 READONLY` 오류로 거부합니다.                      |
| `Full access`     | `Blocked` (기본값)         | `INSERT`, `ALTER`, `CREATE`, 머티리얼라이즈드 뷰. `DROP TABLE`과 `TRUNCATE`는 거부되므로 테이블은 남습니다. |
| `Full access`     | `Allowed`               | 위의 모든 작업에 더해 테이블과 데이터베이스의 삭제 및 truncate.                                            |

쓰기 접근을 켜기 전에 따져 볼 세 가지:

* **`Blocked`는 테이블을 보호할 뿐, 행을 보호하지 않습니다.** `DROP TABLE`과 `TRUNCATE` 문은 거부합니다. 그러나 `ALTER TABLE ... DELETE`, `DROP PARTITION`, `DROP COLUMN`은 거부하지 않으며, 이들은 테이블을 그대로 둔 채 데이터를 제거합니다. 두 번째 스위치와 관계없이 `Full access`는 "에이전트가 데이터를 파괴할 수 있다"로 간주하세요.
* **ClickHouse에는 트랜잭션이 없습니다.** `ALTER TABLE ... DELETE`는 비동기 뮤테이션이고 `DROP`은 즉시 적용됩니다. 둘 다 롤백할 수 없으므로 복구는 백업에서 복원하는 것을 의미합니다.
* **권한이 더 강력한 통제 수단입니다.** 이 스위치는 CloudThinker가 `readonly=1`을 보낼지 여부만 결정하며, ClickHouse 사용자가 이미 가지고 있지 않은 권한을 부여하지는 않습니다. CloudThinker 사용자에게 도달을 허용할 데이터베이스에만 정확히 쓰기 권한을 주면, 스위치는 그 범위를 넘을 수 없습니다.

기존 연결에서 쓰기 접근을 켜려면 **Connections → ClickHouse → Edit**를 열고 **Write access**를 변경한 뒤 다시 연결하세요.

<Warning>
  쓰기 접근을 가진 에이전트는 쿼리마다 확인을 요청하지 않고 작업을 실행합니다. 대시보드가 읽는 클러스터를 지정하기 전에 분석용 또는 스테이징 클러스터를 먼저 지정하세요.
</Warning>

## 문제 해결

<Accordion title="ClickHouse rejected the username or password">
  ClickHouse가 응답했고, 자격 증명을 거부했습니다.

  * 사용자가 존재하는지 확인하세요: `SHOW USERS;`
  * 비밀번호는 붙여넣지 말고 직접 입력하세요. 줄바꿈이 섞인 값은 CloudThinker가 서버에 연결하기도 전에 거부됩니다.
  * ClickHouse Cloud는 일부 SSO로 프로비저닝된 사용자에 대해 비밀번호 인증을 비활성화합니다. 콘솔 로그인을 재사용하지 말고 전용 데이터베이스 사용자를 생성하세요.
</Accordion>

<Accordion title="ClickHouse has no database named …">
  **Default database**에 입력한 이름을 ClickHouse가 찾지 못했습니다. 데이터베이스 이름은 대소문자를 구분하므로 철자를 확인하거나, 이 필드를 비워 서버 기본값을 사용하세요.
</Accordion>

<Accordion title="ClickHouse rejected the request path. Check the port.">
  무언가 응답했지만 ClickHouse의 HTTP 인터페이스가 아니었습니다.

  * **Port**와 **Use TLS**가 일치하는지 확인하세요: TLS 사용 시 `8443`, 미사용 시 `8123`.
  * 네이티브 TCP 포트 `9000`은 HTTP 인터페이스가 아닙니다. 연결을 이 포트로 지정하면 실패합니다.
</Accordion>

<Accordion title="ClickHouse is unreachable">
  해당 host와 port에서 아무 응답도 오지 않았습니다.

  * **Host**에 `https://` 접두사나 `:port` 접미사가 없는지 확인하세요. 둘 다 각자의 필드에 들어갑니다.
  * ClickHouse Cloud: 서비스 IP 접근 목록에 CloudThinker를 추가하세요.
  * 자체 호스팅: `<listen_host>`에 노출한 인터페이스가 포함되어 있는지, 방화벽이 `8443` 또는 `8123`을 허용하는지 확인하세요.
  * TLS 불일치도 똑같이 나타납니다. 평문 HTTP 포트에 **Use TLS**를 켜거나, HTTPS 전용 포트에 끈 경우입니다.
</Accordion>

<Accordion title="ClickHouse did not answer in time">
  주소에는 도달했지만 검사가 시간 초과될 때까지 응답이 오지 않았습니다. ClickHouse Cloud에서는 보통 자동 유휴 상태가 원인입니다. 사용되지 않는 서비스는 일시 중지되며, 다시 시작될 때까지 연결이 시간 초과됩니다. 서비스를 깨운 뒤 다시 연결하세요.
</Accordion>

<Accordion title="ClickHouse is temporarily unavailable">
  서버가 5xx 상태를 반환했습니다. 실행 중이지만 쿼리를 처리하지 못하는 상태입니다. 클러스터 자체의 상태를 확인한 뒤 다시 연결하세요.
</Accordion>

<Accordion title="readonly 모드에서 쿼리를 실행할 수 없음">
  연결이 읽기 전용이며, 이는 기본값입니다. 에이전트가 쓰기를 할 수 있어야 한다면 **Write access**를 `Full access`로 설정하고 다시 연결하세요.

  그 후에도 실패한다면 제한이 서버 측에 있습니다. 사용자가 `readonly` 설정 프로파일을 가지고 있는지(`SHOW CREATE USER cloudthinker;`), 그리고 해당 쿼리에 필요한 쓰기 권한을 보유하고 있는지 확인하세요.
</Accordion>

<Accordion title="쓰기 접근을 켰는데도 DROP이 거부됨">
  `DROP`과 `TRUNCATE`는 별도의 스위치 뒤에 있습니다. **Allow DROP and TRUNCATE**를 `Allowed`로 설정하세요. 이 항목은 **Write access**가 `Full access`일 때만 표시됩니다.
</Accordion>

<Accordion title="테이블 목록이 비어 있음">
  * 사용자에게는 개별 테이블뿐 아니라 데이터베이스에 대한 `SHOW TABLES`와 `SELECT` 권한이 필요합니다.
  * 메타데이터 쿼리가 행을 반환하도록 `SELECT ON system.tables` 권한을 부여하세요.
</Accordion>

## 보안

* **최소 권한** — 에이전트가 사용 사례에 필요한 권한만 부여하세요. 읽기 전용으로 시작한 후 필요에 따라 확장하세요.
* **기본 읽기 전용** — 에이전트가 이 연결을 통해 변경 작업을 수행하게 할 것이 아니라면 읽기 전용 자격증명을 사용하세요.
* **자격증명 교체** — 정기 일정에 따라 키와 토큰을 교체하세요. 연결을 업데이트하면 CloudThinker가 새 값을 자동으로 반영합니다.
* **오프보딩 시 취소** — 연결을 삭제하거나 팀원이 퇴사할 때 프로바이더에서 자격증명을 제거하세요.

- **공개 엔드포인트에서의 TLS** — ClickHouse Cloud 및 사설 네트워크 외부의 모든 엔드포인트에서는 **Use TLS**를 켠 상태로 유지하세요.
- **전용 사용자** — 관리자 계정을 절대 재사용하지 마세요. 별도의 사용자를 쓰면 감사 로그를 읽기 쉽게 유지할 수 있습니다.
- **스위치보다 권한** — ClickHouse 사용자에게 부여된 권한이 지속적인 경계입니다. **Write access** 스위치는 CloudThinker가 쓰기를 요청할지 여부를 결정하고, 권한은 ClickHouse가 그 쓰기를 허용할지 여부를 결정합니다.
- **서버 측 읽기 전용** — 절대 쓰기가 발생하면 안 되는 연결이라면 3단계의 설정 프로파일을 추가하세요. `READONLY`는 클라이언트 측에서 이를 해제할 수 없게 만듭니다.

## 관련 항목

<CardGroup cols={2}>
  <Card title="Tony 에이전트" icon="database" href="/ko/guide/agents/tony">
    데이터베이스 중심 최적화 에이전트
  </Card>

  <Card title="PostgreSQL 연결" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/postgresql.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=8bb2ac033d0a2ccbef51154a76e1e819" href="/ko/guide/connections/postgresql" width="24" height="24" data-path="images/icons/postgresql.svg">
    PostgreSQL 데이터베이스의 유사한 설정
  </Card>
</CardGroup>