clickhousectl(별칭 chctl)은 로컬 개발부터 ClickHouse Cloud까지 아우르는 ClickHouse 공식 CLI입니다. 터미널에서 직접 사용할 수 있을 뿐 아니라 스크립트와 코딩 에이전트에서도 활용할 수 있습니다.
clickhousectl로 다음 작업을 수행할 수 있습니다.
- 로컬 ClickHouse 버전 설치 및 전환, 격리된 로컬 서버 실행, SQL 실행
- Docker 기반 Postgres를 로컬에서 실행
- ClickHouse Cloud 서비스 생성, 구성, 확장, 백업 및 쿼리
- ClickHouse Managed Postgres 서비스 생성, 모니터링, 구성 및 복원
- 객체 스토리지, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB, BigQuery를 소스로 하는 ClickPipes 생성 및 운영
- Managed ClickStack 서비스의 소스, 대시보드, 알림, 웹훅, 저장된 검색 및 역할 관리
- 실행 가능한 사용자 정의 함수(Executable UDFs)를 로컬에서 개발하여 ClickHouse Cloud에 배포
- 조직 구성원, 초대, API 키 및 역할 관리
- 공식 ClickHouse agent skills를 코딩 에이전트에 설치
clickhousectl <command> --help에서 확인하십시오. 대부분의 명령 도움말은 끝부분에 CONTEXT FOR AGENTS 블록이 있으며, Cloud 명령은 여기에 필요한 API Key 권한도 함께 표시합니다. 작업별 안내는 각 섹션의 가이드 링크를 참고하십시오. Cloud 중심의 개요는 ClickHouse CLI를 참조하십시오.
설치
clickhousectl은 ARM64 및 x86_64 아키텍처의 macOS와 Linux에서 실행됩니다.
~/.local/bin/clickhousectl을 설치하고 chctl 별칭을 생성합니다. ~/.local/bin이 PATH에 포함되어 있는지 확인하십시오.
패키지 매니저를 사용하여 설치할 수도 있습니다.
chctl 별칭은 설치 스크립트와 npm으로 설치한 경우에만 생성됩니다. 기존 설치를 업데이트하려면 clickhousectl update를 실행하십시오(자체 업데이트 참조).
요구 사항
- Docker(로컬 Postgres를 사용하는 경우에만 필요)
- Cloud 명령어를 사용하려면 ClickHouse Cloud 계정이 필요합니다. 읽기 명령어는 브라우저 OAuth(
cloud auth login)만으로 사용할 수 있습니다. 리소스를 생성하거나 변경하려면 API Key가 필요합니다. 자세한 내용은 인증을 참조하십시오.
로컬
로컬 명령어는 현재 디렉터리를 기준으로 동작합니다. 각 프로젝트의 서버 데이터는.clickhouse/에 저장되며, ClickHouse 바이너리는 ~/.clickhouse/에 두고 전역으로 공유합니다. CLI는 상위 디렉터리를 탐색하지 않으므로 로컬 명령어는 반드시 프로젝트 루트에서 실행하십시오. 전체 워크플로는 로컬 개발 가이드를 참고하십시오.
설치 및 버전 선택
local use는 필요하면 해당 버전을 설치하고, 이후 서버를 시작할 때 사용할 기본 버전으로 설정한 뒤 ~/.local/bin/clickhouse에 심볼릭 링크를 생성합니다. 따라서 clickhouse client와 clickhouse local을 PATH에서 바로 사용할 수 있습니다. 심볼릭 링크를 생성하지 않으려면 --no-global을 지정하세요. 해당 경로에 일반 파일이 이미 있으면 그대로 둡니다.
local remove는 기본 버전이나, 어느 프로젝트에서든 실행 중인 서버가 사용하는 버전은 제거하지 않습니다. --force를 지정하면 해당 서버를 중지하고 버전을 제거하며, 기본 버전 설정과 심볼릭 링크도 함께 삭제합니다.
프로젝트 초기화
init은 선택 사항입니다. 이 명령은 런타임 데이터용으로 git에서 무시되는 .clickhouse/ 디렉터리를 생성하고, 커밋할 수 있는 SQL 스캐폴드인 clickhouse/(tables/, materialized_views/, queries/, seed/, udfs/)와 postgres/(tables/, views/, functions/, queries/, seed/)도 함께 생성합니다. 다시 실행하면 없는 항목만 생성합니다.
로컬 서버 실행
.clickhouse/servers/<name>/data/에 자체 데이터를 보관하며, 서버를 중지해도 데이터는 다음 시작을 위해 그대로 유지됩니다. 이름을 지정하지 않으면 첫 번째 서버의 이름은 default가 되며, default가 이미 실행 중이면 새 이름이 자동으로 생성됩니다. 기본 포트는 HTTP 8123과 TCP 9000이며, 해당 포트가 이미 사용 중이면 비어 있는 포트가 할당됩니다.
--version을 사용하면 기본 버전을 변경하지 않고 해당 시작에만 적용할 버전을 선택할 수 있습니다. 버전을 지정하지 않고 기본 버전도 설정되지 않은 상태에서 시작하면 latest가 설치되지만 기본 버전으로 지정되지는 않습니다. 이를 기본 버전으로 지정하려면 먼저 local use latest를 실행하십시오.
로컬 클라이언트로 SQL 실행하기
local client는 서버를 실행하는 것과 동일한 ClickHouse 바이너리로 지정한 이름의 서버에 연결합니다(기본 이름: default). -- 뒤에 오는 인수는 그대로 clickhouse client에 전달됩니다. JSON 모드에서도 출력과 종료 상태는 clickhouse client가 반환하므로, 스크립트에서 사용할 때는 SQL 출력 형식을 직접 지정하십시오.
사용자 정의 서버 구성
일부 설정만 담은 XML 또는 YAML 구성 파일을~/.clickhouse/configs/에 넣고, 서버를 시작할 때 이름으로 해당 구성을 지정하십시오:
--config 없이 시작하면 오버레이가 제거됩니다. 관리형 데이터 경로와 포트는 항상 구성 설정값보다 우선합니다.
연결 정보를 dotenv 파일에 저장하기
dotenv는 실행 중인 서버의 실제 포트를 읽어 CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_HTTP_PORT를 기록하며, 사용자, 비밀번호, 데이터베이스를 함께 지정하면 이 값들도 기록합니다. 기존 파일에 있던 다른 줄은 그대로 유지됩니다. 이 파일은 애플리케이션의 dotenv 로더로 불러오십시오. 출력된 프리뷰를 eval로 실행해서는 안 됩니다.
로컬 Postgres
로컬 Postgres는 Docker에서 실행되므로 Docker가 실행 중이어야 합니다. Postgres 17과 18을 지원하며,18-alpine과 같은 이미지 태그도 사용할 수 있습니다. 새 인스턴스는 기본적으로 18 버전을 사용합니다.
.env.local에는 비밀번호가 포함되어 있으므로 버전 관리 대상에서 제외하십시오.
로컬 사용자 정의 함수(UDFs)
local udf는 clickhouse/udfs/<name>/에 있는 실행 가능한 사용자 정의 함수(Executable UDFs)를 로컬 서버에 배포합니다. cloud udf는 같은 디렉터리를 Cloud에 업로드합니다(Cloud의 UDFs 참조).
init을 제외한 모든 명령은 --server <name> 옵션을 받습니다(기본값: default). deploy는 Cloud와 동일한 방식으로 udf.json을 검사합니다. 서버가 실행 중이면 함수를 다시 로드한 뒤 함수가 정상적으로 로드되었는지 확인합니다. native 런타임은 Linux amd64 또는 arm64 호스트에서만 로컬 배포가 가능합니다. 자세한 내용은 사용자 정의 함수 가이드를 참조하십시오.
인증
Cloud 명령어는 다음 두 가지 인증 정보 유형 중 하나를 사용합니다.
아직 ClickHouse Cloud 계정이 없다면,
clickhousectl cloud auth signup를 실행하면 브라우저에서 가입 페이지가 열립니다.
OAuth 로그인
~/.clickhouse/tokens.json에 전역으로 저장되며 자동으로 갱신됩니다.
OAuth는 읽기 전용입니다. 리소스를 생성하거나 변경하려면 API Key로 로그인하세요.
API Key
명령어 실행에 필요한 역할을 부여하여 API Key를 생성한 후 저장하십시오. 대화형 프롬프트로 입력하면 시크릿이 셸 이력에 남지 않습니다:.env 파일에서도 이 변수들을 읽습니다. .env 파일은 버전 관리 대상에서 제외하십시오.
자격 증명 확인 및 삭제
whoami는 두 가지 인증 정보 유형 모두에서 작동하며, 자격 증명이 거부되면 종료 코드 4를 반환합니다. status는 유효한 자격 증명이 하나도 없어도 종료 코드 0을 반환할 수 있으므로, 액세스 가능 여부를 확인하려면 whoami를 사용하십시오. 로그아웃해도 환경 변수가 해제되거나 .env 파일이 수정되지는 않습니다.
인증 정보 우선순위
다음 중 먼저 확인되는 소스가 사용됩니다.--api-key및--api-secret플래그.clickhouse/credentials.json- 내보낸(export) 환경 변수
- 현재 디렉터리의
.env에 정의된 변수 - 전역 OAuth 토큰
cloud 명령이든 --debug를 지정하면 선택된 인증 정보 소스와 API URL이 stderr로 출력됩니다.
조직 선택
조직 범위의 명령어는 자격 증명으로 접근할 수 있는 조직이 정확히 하나인 경우에만 해당 조직을 자동으로 선택합니다. 그렇지 않으면--org-id를 지정하거나, --org-name에 정확한 조직 이름을 지정하십시오.
--name 값을 받습니다. 권한, 제한된 키, 로그아웃 시 정리 작업에 대한 자세한 내용은 인증 및 액세스를 참조하십시오.
Cloud
Cloud 명령은 ClickHouse Cloud API를 호출합니다. 생성 및 UPDATE 요청은 API가 요청을 수락하는 즉시 반환되므로, 리소스가 필요한 상태에 도달할 때까지get을 폴링하십시오.
서비스
running이 될 때까지 get을 반복해서 실행하십시오. --ip-allow를 생략하면 모든 IP(0.0.0.0/0)가 허용됩니다. 엔트리는 IP_OR_CIDR=DESCRIPTION 형식으로 지정합니다. --backup-id를 사용하면 백업(backup)을 새 서비스로 복원할 수 있으며, --byoc-id를 사용하면 서비스를 BYOC 인프라에 배치할 수 있습니다.
서비스 업데이트, 확장 및 구성:
update는 지정한 플래그만 변경합니다.
그 밖의 서비스 명령 그룹으로는 settings (list, get, schema, set, unset), scaling-schedule, upgrade-window, replica-aware-routing (베타), snapshot (베타), private-endpoint, backup-config, prometheus가 있습니다. 자세한 내용은 Cloud 서비스 생성 및 운영을 참조하십시오.
쿼리 API
cloud service query는 로컬 clickhouse 바이너리나 서비스 비밀번호 없이 HTTP를 통해 SQL 문(SQL statement) 하나를 실행합니다.
- OAuth는 사용자의 아이덴티티로 쿼리를 실행하며, 읽기 전용 SQL 액세스 권한만 가집니다. 서비스에는 아무것도 바인딩되지 않습니다.
- API Key: 첫 호출 시 clickhousectl은 사용자의 API Key를 서비스의 Query API 엔드포인트에 추가하며, 엔드포인트가 없으면
sql_console_admin역할로 생성합니다. 기존 역할, 오리진(origin) 및 기타 키 바인딩은 그대로 유지되며, 새 키는 생성되지 않습니다. CLI가 엔드포인트를 변경하면 stderr에Binding the authenticated API key to the Query API endpoint for service '<name>'...를 출력합니다. 이 동작 대신 실패 처리하려면--no-auto-enable을 지정하십시오.
cloud service repair-query-key <service-id>를 실행하여 명시적으로 대체할 수 있습니다.
쿼리 API는 요청당 하나의 SQL 문만 허용합니다. 약 30초가 지나면 SQL이 계속 실행 중이더라도 요청이 시간 초과될 수 있으므로, 쓰기 작업을 재시도하기 전에 결과를 확인하십시오. 여러 SQL 문으로 구성된 스크립트, 대량 적재(bulk loads), 장시간 실행되는 쿼리에는 clickhouse client를 사용하십시오. 서비스 IP 허용 목록은 직접 연결에만 적용되며, 프록시를 거치는 쿼리 API 경로는 제한하지 않습니다. 유휴 상태의 서비스에 쿼리를 실행하면 서비스가 자동으로 깨어나지만, 중지된 서비스는 cloud service start로 시작해야 합니다.
서비스의 Query API 엔드포인트, 이름이 지정된 SQL 엔드포인트 및 저장된 쿼리(saved queries)를 관리합니다:
query-endpoint create는 해당 엔드포인트에 연결된 모든 키의 역할을 교체합니다. 자세한 내용은 SQL 및 쿼리 API 동작을 참조하십시오.
Managed Postgres
cloud postgres는 ClickHouse Managed Postgres를 관리합니다. 이 명령어는 베타 단계이며, GCP는 비공개 프리뷰로 제공됩니다.
m6gd.large, c6gd.xlarge, r6gd.xlarge 등이 있습니다. GCP에서는 --provider gcp와 함께 GCP 리전 및 c4-standard-lssd-4와 같은 크기를 지정하십시오.
create 실행 시 반환되는 비밀번호와 연결 문자열(Connection String)을 반드시 저장하십시오. 이후 get 응답에는 자격 증명이 포함되지 않으며, 새 자격 증명은 reset-password로만 발급받을 수 있습니다. psql로 연결할 때는 sslmode=verify-full과 CA 파일을 사용하십시오.
create 시 액세스 플래그를 생략하면 Postgres(5432)와 PgBouncer(6432)에 모든 IPv4 및 IPv6 주소의 접근이 허용됩니다. 규칙마다 --ip-allow IP_OR_CIDR:PORTS[=DESCRIPTION]을 하나씩 지정하거나, 규칙을 하나도 두지 않으려면 --block-public-access를 지정하십시오. 규칙을 하나라도 지정하면 나열된 규칙만 적용됩니다.
모니터링 및 복구:
cloud postgres query는 OAuth만 지원하므로, 우선순위가 더 높은 API Key 소스가 활성 상태이면 실패합니다. 모니터링에는 metrics, slow-queries, prometheus를 사용합니다. restore는 --ip-allow 또는 --block-public-access를 지정하지 않으면 원본 서비스의 현재 IPv4 액세스 규칙을 복원된 서비스에 그대로 복사합니다. 복원 및 레플리카 생성 시에는 비밀번호가 반환되지 않습니다. promote와 switchover는 요청이 수락되는 즉시 반환됩니다. promote 후에는 레플리카가 isPrimary: true를 보고할 때까지 postgres get --json을 폴링하십시오. 자세한 내용은 Managed Postgres 가이드를 참조하십시오.
ClickPipes
cloud clickpipe는 객체 스토리지, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB, BigQuery에서 데이터를 수집합니다. ClickPipe를 생성하거나 스키마 탐색(schema discovery)을 수행하려면 API Key와 실행 중인 대상 서비스가 필요합니다. 소스마다 전용 clickpipe create <source> 하위 명령이 있으며, --help를 붙여 실행하면 해당 명령의 플래그를 확인할 수 있습니다.
IAM role을 사용하여 S3에서 파일을 로드합니다. 먼저 스키마(schema)를 탐색한 다음 컬럼을 선택하세요.
--table-mapping은 ReplacingMergeTree 테이블을 생성하므로, 현재 상태를 조회하려면 FINAL WHERE _peerdb_is_deleted = 0을 사용하십시오. Kafka 파이프도 같은 패턴을 따릅니다. 동일한 소스 플래그로 clickpipe schema-discover kafka를 실행한 다음, 컬럼을 전달하십시오:
--replication-mode cdc와 --replication-method를 지정하고, --table-mapping-json에 테이블별 워터마크(watermark) 컬럼 또는 이벤트 함수를 지정하십시오. 동기화 일정은 --sync-cron 또는 --sync-interval-seconds로 설정합니다. 기존 파이프는 다음 명령으로 관리합니다:
update 전에 Paused 상태여야 합니다. 파이프를 중지하고 Paused 상태가 될 때까지 get으로 폴링한 다음 업데이트하세요. 서비스가 업데이트 과정에서 파이프를 재개할 수 있으므로, get에 여전히 Paused로 표시되는 경우에만 start를 실행하세요. --start-paused는 객체 스토리지, Kafka, Kinesis, Pub/Sub에서 사용할 수 있습니다. 그 밖의 명령 그룹으로는 cdc-scaling, context get(GCP 워크로드 아이덴티티 준비 상태 및 주체), reverse-private-endpoint가 있습니다. 자세한 내용은 ClickPipes 가이드 및 ClickPipe 구성 참고를 참조하세요.
ClickStack
cloud clickstack은 기존 Managed ClickStack 서비스의 소스, 대시보드, 알림, 웹훅, 저장된 검색 및 역할을 관리합니다. 리소스는 JSON 파일로 전달합니다(--file 사용, stdin에서 읽으려면 - 지정). 읽기 작업은 OAuth 인증을 지원하지만, 쓰기 작업에는 API Key가 필요합니다.
get --json으로 현재 상태를 저장한 후, 변경된 필드만이 아니라 전체 정의를 전송하십시오. 자세한 내용은 ClickStack 가이드를 참조하십시오.
Cloud의 사용자 정의 함수(UDFs)
cloud udf는 조직 범위의 실행 가능한 사용자 정의 함수(Executable UDFs)와 그 버전, 그리고 서비스 ATTACH를 관리합니다. deploy는 local udf로 테스트한 디렉터리를 업로드하고 빌드가 완료될 때까지 대기한 다음, 해당 버전을 ATTACH하고 배포가 완료될 때까지 대기합니다:
udf create, udf version create, udf attach(유휴 상태인 서비스에는 --wake 사용), udf detach, udf delete를 사용하십시오. 이 명령들은 요청이 수락되면 바로 반환되므로 udf get 및 udf attachment get을 폴링하여 진행 상태를 확인하십시오. 읽기 작업은 OAuth를 지원하지만, 쓰기 작업에는 API Key가 필요합니다. 자세한 내용은 사용자 정의 함수 가이드를 참조하십시오.
조직 및 액세스
cloud org 하위 명령은 위치 기반 ID가 아니라 항상 --org-id로 대상을 지정합니다. org usage로 조회할 수 있는 기간은 최대 31일입니다. org에는 quota, balance, notification-types, role(사용자 정의 조직 역할), byoc(BYOC 인프라) 하위 명령도 있습니다. 알림 기능은 현재 베타입니다.
구성원, 초대 및 API 키 관리:
key create에서 --ip-allow를 생략하면 모든 네트워크 액세스가 거부됩니다. 이는 서비스 생성 시의 동작과 다릅니다. 시크릿은 한 번만 표시됩니다. key list는 --all을 지정하지 않으면 한 페이지만 반환합니다. key update에서 생략한 플래그는 기존 설정이 그대로 유지되며, --clear-expiry, --clear-roles, --clear-ip-allow를 지정하면 해당 설정이 제거됩니다.
백업
cloud backup bucket(get, create, update, delete)은 provider별 JSON 파일을 기반으로 사용자 소유 백업 버킷(bring-your-own backup bucket)을 구성합니다. 자세한 내용은 클라우드 서비스 가이드의 백업 섹션을 참조하십시오.
JSON 출력
로컬, Cloud,skills, update, telemetry 명령어를 비롯하여 구조화된 데이터를 반환하는 명령어는 모두 --json 옵션을 지원합니다.
AI_AGENT를 설정하는 모든 도구)를 감지하면 자동으로 JSON을 선택합니다. 단, SQL 및 네이티브 클라이언트는 자체 포맷을 그대로 사용합니다. cloud service query는 JSON 모드에서 JSONEachRow를 반환하며, local client의 출력은 항상 네이티브 포맷입니다. 쿼리 출력을 파싱하는 스크립트에서는 --format을 명시적으로 지정해야 합니다.
JSON 모드에서 런타임 오류는 변경되지 않는 code와 message를 포함한 객체 형태로 stderr에 출력됩니다:
error.code를 기준으로 분기하십시오. 사용법 오류는 텍스트 형식 그대로 출력되며 종료 코드 2를 반환합니다. 출력 형태와 오류 코드는 자동화 및 출력 계약을 참고하십시오.
종료 코드
local client, local postgres client 등 네이티브 클라이언트로 제어를 넘기는 명령은 해당 클라이언트의 종료 상태를 그대로 반환합니다.
에이전트 스킬
공식 ClickHouse agent skills를 코딩 에이전트에 설치하십시오:--global을 지정하면 홈 디렉터리에 설치됩니다. 공유 .agents/skills/ 디렉터리는 항상 포함됩니다. 터미널이 없는 환경에서는 --agent, --all, --detected-only 중 하나를 반드시 지정해야 합니다. 지원되는 에이전트 이름은 clickhousectl skills --help를 실행하여 확인하세요.
자체 업데이트
텔레메트리
clickhousectl은 개발 방향을 정하는 데 참고하기 위해 익명의 사용량 데이터를 수집합니다. 처음 실행할 때는 안내 메시지만 표시하고 아무것도 전송하지 않으며, 비활성화하지 않으면 그다음 실행부터 수집이 시작됩니다.
각 이벤트에는 다음 정보가 포함됩니다.
- 명령 경로와 명시적으로 전달된 플래그 및 인수의 이름(값은 절대 포함되지 않음)
- 실행 결과 및 종료 코드
- 명령을 잘못 입력한 경우 CLI가 제안한 명령 또는 플래그 이름(실제로 입력한 내용은 절대 포함되지 않음)
- 런타임 실패 시 범위가 제한된 범주 정보: 실패 스테이지 및 유형, 허용 목록에 포함된 HTTP 상태, 재시도·프로비저닝 상태·소요 시간 범주
- CLI 버전, OS 및 아키텍처, CI 환경에서의 실행 여부, 감지된 코딩 에이전트
-- 뒤의 인수, 오류 메시지는 절대 기록되지 않습니다. 설치 ID나 기기 ID도 사용하지 않습니다.
수집을 거부하려면 다음과 같이 하십시오.
CHCTL_TELEMETRY_DEBUG=1을 설정하면 데이터를 전송하지 않고 payload를 stderr에 출력합니다. 자세한 내용은 텔레메트리 세부 정보를 참조하십시오.