메인 콘텐츠로 건너뛰기
clickhousectl은 로컬과 클라우드용 ClickHouse CLI입니다. clickhousectl로 다음 작업을 수행할 수 있습니다:
  • 로컬 ClickHouse 버전 설치 및 관리
  • 로컬 ClickHouse 서버 실행 및 관리
  • ClickHouse 서버에서 쿼리 실행
  • ClickHouse Cloud를 설정하고 클라우드 관리형 ClickHouse 클러스터 생성
  • ClickHouse Cloud 리소스 관리
  • 지원되는 코딩 에이전트에 공식 ClickHouse agent 스킬 설치
  • 로컬 ClickHouse 개발 환경을 클라우드로 푸시
clickhousectl은 사람과 AI 에이전트가 ClickHouse로 개발할 수 있도록 지원합니다.

​
설치

​
빠른 설치

curl https://clickhouse.com/cli | sh
설치 스크립트는 사용 중인 OS에 맞는 버전을 다운로드한 뒤 ~/.local/bin/clickhousectl에 설치합니다. 편의를 위해 chctl alias도 자동으로 생성됩니다.

​
요구 사항

​
로컬

​
ClickHouse 버전 설치 및 관리

clickhousectl은 GitHub 릴리스에서 ClickHouse 바이너리를 다운로드합니다. 
# 버전 설치
clickhousectl local install stable          # 최신 안정 릴리스
clickhousectl local install lts             # 최신 LTS 릴리스
clickhousectl local install 26.3            # 최신 26.3.x.x
clickhousectl local install 26.3.4.3        # 특정 버전

# 버전 목록 조회
clickhousectl local list                    # 설치된 버전
clickhousectl local list --remote           # 다운로드 가능한 버전

# 기본 버전 관리
clickhousectl local use stable              # 최신 안정 버전 (필요 시 설치)
clickhousectl local use lts                 # 최신 LTS (필요 시 설치)
clickhousectl local use 26.3                # 최신 26.3.x.x (필요 시 설치)
clickhousectl local use 26.3.4.3            # 특정 버전
clickhousectl local which                   # 현재 기본 버전 표시

# 버전 제거
clickhousectl local remove 26.3.4.3

​
ClickHouse 실행 파일 저장소

ClickHouse 실행 파일은 저장 공간을 중복하지 않으면서 여러 프로젝트에서 사용할 수 있도록 전역 리포지토리에 저장됩니다. 실행 파일은 ~/.clickhousectl/에 저장됩니다: 
~/.clickhousectl/
├── versions/
│   └── 26.3.4.3/
│       └── clickhouse
└── default              # 현재 활성 버전을 추적

​
프로젝트 초기화

clickhousectl local init
init은 현재 작업 디렉터리에 ClickHouse 프로젝트 파일을 위한 표준 폴더 구조를 설정합니다. 이 작업은 선택 사항이므로, 필요하면 자체 폴더 구조를 사용해도 됩니다. 다음과 같은 구조가 생성됩니다: 
clickhouse/
├── tables/                 # 테이블 정의 (CREATE TABLE ...)
├── materialized_views/     # Materialized view 정의
├── queries/                # 저장된 쿼리
└── seed/                   # 시드 데이터 / INSERT 문

​
쿼리 실행

# clickhouse-client로 실행 중인 서버에 연결
clickhousectl local client                           # "default" 서버에 연결
clickhousectl local client --name dev                # "dev" 서버에 연결
clickhousectl local client --query "SHOW DATABASES"  # 쿼리 실행
clickhousectl local client --queries-file schema.sql # 파일에서 쿼리 실행
clickhousectl local client --host remote-host --port 9000  # 특정 호스트/포트에 연결

​
ClickHouse 서버 생성 및 관리

ClickHouse 서버 인스턴스를 시작하고 관리합니다. 각 서버에는 .clickhousectl/servers/<name>/data/ 아래에 서로 격리된 자체 데이터 디렉터리가 할당됩니다. 
# 서버 시작 (기본적으로 백그라운드에서 실행)
clickhousectl local server start                          # "default"로 명명
clickhousectl local server start --name dev               # "dev"로 명명
clickhousectl local server start --foreground             # 포그라운드에서 실행 (-F / --fg)
clickhousectl local server start --http-port 8124 --tcp-port 9001  # 포트 직접 지정
clickhousectl local server start -- --config-file=/path/to/config.xml

# 모든 서버 목록 조회 (실행 중 및 중지된 서버 포함)
clickhousectl local server list

# 서버 중지
clickhousectl local server stop default                   # 이름으로 중지
clickhousectl local server stop-all                       # 실행 중인 모든 서버 중지

# 중지된 서버 및 해당 데이터 삭제
clickhousectl local server remove test
서버 이름 지정: --name을 지정하지 않으면 첫 번째 server의 이름은 “default”입니다. “default”가 이미 실행 중이면 임의의 이름이 생성됩니다(예: “bold-crane”). 반복해서 시작하거나 중지할 수 있는 안정적인 식별자가 필요하면 --name을 사용하세요. 포트: 기본 포트는 HTTP 8123과 TCP 9000입니다. 이 포트들이 이미 사용 중이면 사용 가능한 포트가 자동으로 할당되고 출력에 표시됩니다. 포트를 명시적으로 지정하려면 --http-port와 --tcp-port를 사용하세요.

​
프로젝트 로컬 데이터 디렉터리

모든 서버 데이터는 프로젝트 디렉터리 내 .clickhousectl/에 저장됩니다: 
.clickhousectl/
├── .gitignore              # 자동 생성됨, 모든 항목 무시
├── credentials.json        # Cloud API 자격 증명 (설정된 경우)
└── servers/
    ├── default/
    │   └── data/           # "default" 서버의 ClickHouse 데이터 파일
    └── dev/
        └── data/           # "dev" 서버의 ClickHouse 데이터 파일
이름이 지정된 각 서버는 자체 데이터 디렉터리를 사용하므로 서버끼리는 완전히 격리됩니다. 데이터는 재시작 후에도 유지됩니다 — 서버 이름으로 서버를 중지했다가 다시 시작하면 중단한 지점부터 작업을 이어갈 수 있습니다. 서버 데이터를 영구적으로 삭제하려면 clickhousectl local server remove <name>를 사용하십시오.

​
인증

OAuth(브라우저 기반) 또는 API Key를 사용하여 ClickHouse Cloud에 인증합니다.

​
OAuth 로그인(권장)

clickhousectl cloud auth login
브라우저가 열리고 OAuth 디바이스 흐름을 통해 인증이 진행됩니다. 토큰은 .clickhousectl/tokens.json에 저장됩니다(프로젝트 로컬).

​
API Key/Secret

# 비대화형 (CI 환경에 적합)
clickhousectl cloud auth login --api-key YOUR_KEY --api-secret YOUR_SECRET

# 대화형 프롬프트
clickhousectl cloud auth login --interactive
자격 증명은 .clickhousectl/credentials.json(프로젝트 로컬)에 저장됩니다. 환경 변수도 사용할 수 있습니다: 
export CLICKHOUSE_CLOUD_API_KEY=your-key
export CLICKHOUSE_CLOUD_API_SECRET=your-secret
또는 어떤 명령에서든 플래그로 자격 증명을 직접 전달할 수 있습니다: 
clickhousectl cloud --api-key KEY --api-secret SECRET ...

​
인증 상태 및 로그아웃

clickhousectl cloud auth status    # 현재 인증 상태 표시
clickhousectl cloud auth logout    # 저장된 모든 자격 증명 삭제 (credentials.json & tokens.json)
자격 증명 확인 우선순위: CLI 플래그 > OAuth 토큰 > .clickhousectl/credentials.json > 환경 변수.

​
Cloud

API를 사용해 ClickHouse Cloud 서비스를 관리합니다.

​
조직

clickhousectl cloud org list              # 조직 목록 조회
clickhousectl cloud org get <org-id>      # 조직 상세 정보 조회
clickhousectl cloud org update <org-id> --name "Renamed Org"
clickhousectl cloud org update <org-id> \
  --remove-private-endpoint pe-1,cloud-provider=aws,region=us-east-1 \
  --enable-core-dumps false
clickhousectl cloud org prometheus <org-id> --filtered-metrics true
clickhousectl cloud org usage <org-id> \
  --from-date 2024-01-01 \
  --to-date 2024-01-31

​
서비스

# 서비스 목록 조회
clickhousectl cloud service list

# 서비스 상세 정보 조회
clickhousectl cloud service get <service-id>

# 서비스 생성 (최소 옵션)
clickhousectl cloud service create --name my-service

# 스케일링 옵션을 지정하여 생성
clickhousectl cloud service create --name my-service \
  --provider aws \
  --region us-east-1 \
  --min-replica-memory-gb 8 \
  --max-replica-memory-gb 32 \
  --num-replicas 2

# 특정 IP 허용 목록을 지정하여 생성
clickhousectl cloud service create --name my-service \
  --ip-allow 10.0.0.0/8 \
  --ip-allow 192.168.1.0/24

# Backup에서 생성
clickhousectl cloud service create --name restored-service --backup-id <backup-uuid>

# release channel을 지정하여 생성
clickhousectl cloud service create --name my-service --release-channel fast

# 서비스 시작/중지
clickhousectl cloud service start <service-id>
clickhousectl cloud service stop <service-id>

# clickhouse-client로 Cloud 서비스에 연결
clickhousectl cloud service client --name my-service --password secret
clickhousectl cloud service client --id <service-id> -q "SELECT 1" --password secret

# CLICKHOUSE_PASSWORD 환경 변수 사용 (스크립트/에이전트 환경에 권장)
CLICKHOUSE_PASSWORD=secret clickhousectl cloud service client \
  --name my-service -q "SELECT count() FROM system.tables"

# 서비스 메타데이터 및 패치 업데이트
clickhousectl cloud service update <service-id> \
  --name my-renamed-service \
  --add-ip-allow 10.0.0.0/8 \
  --remove-ip-allow 0.0.0.0/0 \
  --release-channel fast

# 레플리카 스케일링 업데이트
clickhousectl cloud service scale <service-id> \
  --min-replica-memory-gb 24 \
  --max-replica-memory-gb 48 \
  --num-replicas 3 \
  --idle-scaling true \
  --idle-timeout-minutes 10

# 자동 생성된 자격 증명으로 비밀번호 재설정
clickhousectl cloud service reset-password <service-id>

# 서비스 삭제 (사전에 중지 필요)
clickhousectl cloud service delete <service-id>

# 강제 삭제: 실행 중인 서비스를 중지한 후 삭제
clickhousectl cloud service delete <service-id> --force

​
서비스 생성 옵션

옵션설명
--name서비스 이름 (필수)
--provider클라우드 제공업체: aws, gcp, azure (기본값: aws)
--region리전 (기본값: us-east-1)
--min-replica-memory-gb레플리카당 최소 메모리(GB) (8-356, 4의 배수)
--max-replica-memory-gb레플리카당 최대 메모리(GB) (8-356, 4의 배수)
--num-replicas레플리카 수 (1-20)
--idle-scaling0까지 스케일링 허용 (기본값: true)
--idle-timeout-minutes최소 유휴 timeout(분) (>= 5)
--ip-allow허용할 IP CIDR (반복 지정 가능, 기본값: 0.0.0.0/0)
--backup-id복원할 Backup ID
--release-channel릴리스 채널: slow, default, fast

​
쿼리 엔드포인트 관리

clickhousectl cloud service query-endpoint get <service-id>
clickhousectl cloud service query-endpoint create <service-id> \
  --role admin \
  --open-api-key key-1 \
  --allowed-origins https://app.example.com
clickhousectl cloud service query-endpoint delete <service-id>

​
Private Endpoint 관리

clickhousectl cloud service private-endpoint create <service-id> --endpoint-id vpce-123
clickhousectl cloud service private-endpoint get-config <service-id>

​
Backup 구성

clickhousectl cloud service backup-config get <service-id>
clickhousectl cloud service backup-config update <service-id> \
  --backup-period-hours 24 \
  --backup-retention-period-hours 720 \
  --backup-start-time 02:00

​
백업

clickhousectl cloud backup list <service-id>
clickhousectl cloud backup get <service-id> <backup-id>

​
구성원

clickhousectl cloud member list
clickhousectl cloud member get <user-id>
clickhousectl cloud member update <user-id> --role-id <role-id>
clickhousectl cloud member remove <user-id>

​
초대

clickhousectl cloud invitation list
clickhousectl cloud invitation create --email dev@example.com --role-id <role-id>
clickhousectl cloud invitation get <invitation-id>
clickhousectl cloud invitation delete <invitation-id>

​
키

clickhousectl cloud key list
clickhousectl cloud key get <key-id>
clickhousectl cloud key create --name ci-key --role-id <role-id> --ip-allow 10.0.0.0/8
clickhousectl cloud key update <key-id> \
  --name renamed-key \
  --expires-at 2025-12-31T00:00:00Z \
  --state disabled \
  --ip-allow 0.0.0.0/0
clickhousectl cloud key delete <key-id>

​
활동

clickhousectl cloud activity list --from-date 2024-01-01 --to-date 2024-12-31
clickhousectl cloud activity get <activity-id>

​
JSON 출력

JSON 형식으로 응답을 출력하려면 --json 플래그를 사용하세요. 
clickhousectl cloud --json service list
clickhousectl cloud --json service get <service-id>

​
Skills

ClickHouse/agent-skills에서 공식 ClickHouse Agent Skills를 설치하세요. 
# 기본값: 사람을 위한 대화형 모드, 범위 선택 후 에이전트 선택
clickhousectl skills

# 비대화형: 지원되는 모든 프로젝트 로컬 에이전트 폴더에 설치
clickhousectl skills --all

# 비대화형: 감지된 에이전트에만 설치
clickhousectl skills --detected-only

# 비대화형: 지원되는 모든 전역 에이전트 폴더에 설치
clickhousectl skills --global --all

# 비대화형: 특정 프로젝트 로컬 에이전트에 설치
clickhousectl skills --agent claude --agent codex

​
비대화형 플래그

플래그설명
--agent <name>특정 에이전트용 Skills를 설치합니다(여러 번 지정 가능)
--global전역 범위를 사용합니다. 생략하면 프로젝트 범위를 사용합니다
--all지원되는 모든 에이전트용 Skills를 설치합니다
--detected-only시스템에서 감지된 지원 에이전트용 Skills를 설치합니다
마지막 수정일 2026년 6월 10일