Skip to main content
ClickHouse CLI(clickhousectl)는 ClickHouse Cloud 리소스 관리와 로컬 환경에서의 ClickHouse 개발을 위한 통합 명령줄 도구입니다. 또한 ClickHouse Cloud Postgres 서비스와 ClickPipes 관리도 지원합니다. 이 페이지는 clickhousectl 0.4.2의 명령어 체계에 대한 참고 문서입니다. 설치된 버전을 확인하려면 clickhousectl --version을 실행하고, 특정 명령어의 전체 플래그 목록을 보려면 clickhousectl <command> --help를 실행하십시오.

설치

편의를 위해 chctl 별칭이 자동으로 함께 생성됩니다. 기존 설치를 최신 버전으로 업데이트하려면:

Cloud 관리

명령줄에서 직접 ClickHouse Cloud에 인증하고 서비스를 관리할 수 있습니다.

인증

API Key는 .clickhouse/credentials.json에 저장됩니다(프로젝트 로컬, git 추적 제외). 환경 변수를 사용할 수도 있습니다:
자격 증명의 precedence는 높은 순서부터 낮은 순서로 다음과 같습니다: --api-key/--api-secret 플래그, .clickhouse/credentials.json에 저장된 프로젝트 자격 증명, environment variables(shell, 그다음 .env), cloud auth login으로 발급받은 OAuth 토큰. OAuth 토큰은 읽기 전용입니다. 쓰기 명령어(create, delete, start, stop, update, scale)에는 API Key 인증이 필요합니다.

서비스

쿼리 실행

Query API를 사용해 HTTP로 Cloud 서비스에서 SQL을 실행합니다. 로컬 clickhouse binary나 service password는 필요하지 않습니다. --id 또는 --name 중 반드시 하나만 지정해야 합니다:
API Key 인증을 사용하면 쿼리는 읽기 및 쓰기 액세스 권한으로 실행됩니다. 서비스의 query 엔드포인트가 이미 해당 키를 인가한 상태라면 인증된 키가 그대로 사용되고, 그렇지 않으면 첫 번째 쿼리가 query 엔드포인트와 서비스별 읽기/쓰기 키를 프로비저닝한 뒤 그 키를 .clickhouse/credentials.json에 저장합니다. 프로비저닝하지 않고 실패하도록 하려면 --no-auto-enable을 전달하십시오. OAuth를 사용하면 SQL이 cloud 사용자 권한으로 읽기 전용 액세스(SELECT만 가능)로 실행되며, 프로비저닝되는 것은 없습니다. 알아두어야 할 사항:
  • service query는 요청당 하나의 statement만 실행합니다. 다중 statement SQL은 --query, --queries-file, stdin 중 어떤 경로로 전달되든 Query API에서 거부되며 Error: SQL error 62: Syntax error (Multi-statements are not allowed)가 반환됩니다. 단일 statement 끝에 ;가 붙는 것은 문제없습니다. script를 실행할 때는 clickhousectl local use latest를 실행한 뒤 해당 서비스에 clickhouse client로 접속하십시오.
  • --query와 --queries-file은 함께 사용할 수 없습니다(종료 코드 2). stdin은 둘 다 지정되지 않았을 때만 읽습니다. --query는 stdin을 읽지 않으므로, 이와 함께 데이터를 리다이렉트하거나 파이프로 전달하면 조용히 무시되는 것이 아니라 오류로 처리됩니다: Error: --query cannot be combined with SQL or data on stdin. 대신 INSERT와 해당 데이터를 하나의 single stream으로 보내거나 — printf 'INSERT INTO t FORMAT CSV\n' | cat - data.csv | clickhousectl cloud service query --id <service-id> — --queries-file -로 stdin에서 statement 전체를 읽으십시오.
  • 기본 출력 형식은 terminal에서는 PrettyCompact, 파이프로 연결된 경우 TabSeparated입니다. --json은 JSONEachRow를 선택하며 --format과 함께 사용할 수 없습니다(종료 코드 2).
  • 엔드포인트가 HTTP 401/403으로 거부하는 저장된 Query API 키는 자동으로 대체되지 않습니다. CLI는 거부 사유를 알리기 위해서만 해당 키의 management 레코드를 읽습니다. 이 자격 증명 하나만 clickhousectl cloud service repair-query-key <service-id>로 교체하십시오. 이 명령은 대체된 기존 키도 함께 삭제합니다. 실행 중인 서비스에서는 새 키로 수행한 probe 쿼리가 성공해야만 0으로 종료되며, 그 결과는 --json 출력의 verification 항목에 표시됩니다. readiness 윈도우가 끝날 때까지 Query API가 여전히 키를 거부하면 명령은 1로 종료되지만 복구 자체는 유효합니다. 명령을 다시 실행하지 말고 cloud service query를 실행하십시오.
  • Query API는 약 30초 후 타임아웃됩니다. statement는 서비스에서 계속 실행되지만 결과는 유실됩니다. 더 오래 걸리는 작업에는 clickhousectl local use latest를 실행해 표준 clickhouse binary를 PATH에 추가한 뒤 clickhouse client --host <host> --secure --port 9440 --user default --password <password>로 연결하십시오.

서비스 엔드포인트 및 구성

--backup-start-time은 반드시 정시(HH:00)여야 하며, API 호출 전에 CLI에서 이를 검사합니다. 또한 백업 주기가 24시간 또는 48시간이어야 합니다. 동일한 명령에서 --backup-period-hours 24 또는 --backup-period-hours 48을 전달하거나, 두 값 중 하나가 이미 저장되어 있어야 합니다. 그 외의 주기가 저장되어 있으면 CLI는 API를 호출하기 전에 Error: the stored backup period is 12 hours, but --backup-start-time requires 24 or 48. 메시지와 함께 요청을 거부합니다. --clear-backup-start-time은 저장된 시작 시간을 제거하고 해당 제한을 해제합니다. --backup-period-hours와 함께 사용하면 한 번의 호출로 시작 시간을 지우고 원하는 주기를 설정할 수 있습니다. 이 옵션은 --backup-start-time과 함께 사용할 수 없습니다.

백업

백업을 복원하려면 해당 백업으로 새 서비스를 생성하십시오: clickhousectl cloud service create --name restored-service --backup-id <backup-id>.

ClickPipes

Cloud 서비스로 데이터를 수집하는 ClickPipes를 관리합니다. 대부분의 명령어는 서비스 ID를 첫 번째 인수로 받습니다.
알아두어야 할 사항:
  • clickpipe create postgres는 --table-mapping <schema.table:target_table>(반복 지정 가능, 플래그당 테이블 1개) 또는 --table-mapping-json <json> 중 하나가 필요하며, 두 옵션을 함께 사용할 수도 있습니다. JSON 형식은 API의 테이블 매핑 객체를 그대로 받으며, excludedColumns, sortingKeys, partitionByExpr, partitionKey, tableEngine을 설정할 수 있는 유일한 방법입니다. partitionKey는 병렬 처리를 위해 초기 스냅샷을 분할하는 값이며, 대상 테이블의 PARTITION BY와는 무관하다는 점에 유의하십시오. PARTITION BY에 해당하는 것은 partitionByExpr입니다. --iam-role은 --auth IAM_ROLE과 함께 사용해야 하며 기본 인증에서는 거부됩니다. --replication-slot-name은 --replication-mode cdc_only에서만 유효합니다.
  • Postgres CDC 설정은 파이프 생성 시 적용됩니다: --sync-interval-seconds, --pull-batch-size, --initial-load-parallelism, --snapshot-rows-per-partition, --snapshot-parallel-tables, --allow-nullable-columns, --enable-failover-slots, --delete-on-merge. 이후에 변경할 수 있는 것은 sync interval과 pull batch 크기뿐이며, 스냅샷 및 초기 로드 설정은 변경할 수 없습니다.
  • 모든 clickpipe create 하위 명령에서 --role <role>은 반복 지정할 수 있으며, 파이프의 대상 사용자에게 부여할 ClickHouse 역할을 지정합니다. 이 옵션은 해당 사용자가 원래 받게 될 역할을 대체합니다. --role을 지정하지 않으면 사용자는 clickpipes_system과 default_role을 갖고, --role my_role을 지정하면 clickpipes_system과 my_role을 갖습니다. 해당 역할은 대상 데이터베이스에서 테이블을 생성할 수 있어야 하며, 읽기 전용 역할을 사용하면 Not enough privileges 오류로 생성이 실패합니다. API가 예약한 이름인 clickpipes와 clickpipes_system은 거부됩니다.
  • Postgres 소스에서는 TLS와 certificate verification이 기본적으로 활성화되어 있습니다. 공개적으로 신뢰되는 소스 체인은 CA 파일이 필요하지 않지만, 비공개 또는 자체 서명된 소스 CA를 사용하는 경우 --ca-certificate <path>로 해당 PEM bundle을 전달하십시오. ClickHouse Cloud Postgres 소스라면 clickhousectl cloud postgres certs get으로 해당 bundle을 가져올 수 있습니다. 호스트명 검증에는 --host가 사용되며, --tls-host <hostname>으로 재정의할 수 있습니다.
  • Kafka 및 Kinesis 파이프에서는 --auth를 생략하면 credential 플래그를 통해 값이 추론되며, credential 플래그를 전혀 지정하지 않으면 인증 정보가 전송되지 않습니다.
  • clickpipe settings는 스트리밍(Kafka, Kinesis) 및 객체 스토리지 파이프의 수집 설정만 다루며, Kafka 전용 설정은 Kafka가 아닌 파이프에서는 제외됩니다. 데이터베이스 CDC 파이프(Postgres, MySQL, MongoDB, BigQuery)에는 수집 설정이 없습니다. 이러한 파이프에 settings get을 실행하면 종료 코드 1로 종료되며 clickhousectl cloud clickpipe get <service-id> <clickpipe-id>를 안내합니다. 이 명령에서 sync interval과 pull batch 크기를 확인할 수 있습니다.
  • 파이프는 Ready 상태에 도달한 Reverse Private Endpoint만 사용할 수 있습니다. AWS PrivateLink 엔드포인트는 소스를 소유한 account에서 연결 요청이 수락될 때까지 PendingAcceptance 상태로 유지됩니다. Kafka 파이프는 --reverse-private-endpoint-id(반복 지정 가능)로 엔드포인트를 ID로 참조하며, Postgres 및 MySQL CDC 파이프는 엔드포인트의 dnsNames 중 하나를 --host로 전달합니다.
  • Google Cloud Pub/Sub 파이프는 제한 미리 보기 상태입니다. 파이프를 생성하기 전에 지원팀에 문의하여 조직에 해당 기능을 활성화하십시오. --service-account-file은 GCP service account JSON 키의 경로를 받으며, -를 지정하면 stdin에서 키를 읽습니다. 키를 인라인으로 지정하는 것은 허용되지 않으므로 프로세스 목록과 셸 기록에 노출되지 않습니다.

Postgres 서비스(베타)

ClickHouse Cloud Postgres 서비스를 생성하고 관리합니다.
알아두어야 할 사항:
  • --provider의 기본값은 aws이며, gcp도 사용할 수 있습니다. GCP에서는 c4-standard-4와 같은 머신 크기를 지정합니다. --size는 CLI가 아니라 Cloud API에서 검사하므로, 지원되지 않는 크기는 서버에서만 거부됩니다.
  • 역할 변경은 최종적 일관성을 따르며, API는 promote와 switchover를 실제로 적용하기 전에 먼저 응답을 반환합니다. 따라서 종료 코드 0만으로는 역할이 변경되었다고 단정할 수 없습니다. 두 명령 모두 --wait를 지원하여 target이 새 역할을 보고할 때까지 폴링하며, --wait-timeout <seconds>(기본값 300)으로 폴링 시간을 제한할 수 있습니다. 이전 프라이머리가 그 후 몇 분 동안 계속 isPrimary=true를 보고할 수 있으므로, clickhousectl cloud postgres list --filter isPrimary=true로 프라이머리 service가 정확히 하나인지 확인하십시오.
  • postgres delete는 running을 포함한 모든 state에서 동작하므로, service를 먼저 중지할 필요가 없습니다.

조직

API Keys

구성원 및 초대

활동 로그(Activity log)

JSON 출력

--json 플래그를 사용하면 모든 cloud 명령의 응답을 JSON 포맷으로 받을 수 있습니다:
org prometheus 및 service prometheus 명령어는 예외입니다. 이 명령어들은 항상 raw Prometheus exposition 텍스트를 출력하며, --json은 별도 알림 없이 무시합니다.

로컬 개발

CLI는 로컬 ClickHouse 설치본, 로컬 서버, Docker 기반 로컬 Postgres 인스턴스도 관리합니다. 로컬 개발을 시작하려면 clickhousectl (CLI) 페이지를 참조하십시오.
알아두어야 할 사항:
  • local 명령어는 프로젝트 범위로 동작합니다. 현재 작업 디렉터리 바로 아래의 .clickhouse 디렉터리만 사용하며, 상위 디렉터리는 탐색하지 않습니다. 실행하기 전에 프로젝트 루트로 이동하십시오.
  • clickhousectl local use는 ~/.local/bin/clickhouse에 대한 심볼릭 링크도 생성하므로 clickhouse client, clickhouse benchmark, clickhouse format 같은 표준 하위 명령어를 바로 사용할 수 있습니다. 심볼릭 링크 생성을 건너뛰려면 --no-global을 전달하십시오.
  • local remove는 설치된 정확한 버전을 인수로 받습니다. 어떤 프로젝트에서든 실행 중인 서버가 사용하는 버전이거나 현재 기본값으로 지정된 버전은 제거하지 않습니다. --force를 사용하면 해당 서버를 중지하고 기본값과 전역 심볼릭 링크를 해제합니다.
  • 이름을 지정하지 않으면 local server stop은 default가 있을 경우 이를 중지하고, 없으면 알려진 유일한 서버를 중지합니다. 기본값이 아닌 서버가 여러 개 있으면 이름을 입력하도록 요구합니다. 이름 없이 실행한 local server remove는 기존 default만 선택하며, 사용자 정의 서버를 임의로 선택하지 않습니다.
  • local client는 직접 호스트/포트 모드에서 설치된 클라이언트 버전을 선택할 수 있도록 -v/--version을 지원하고, -q를 반복해 여러 쿼리를 지정할 수 있으며, --queries-file에는 여러 경로를 지정할 수 있습니다. --query와 --queries-file을 함께 사용하면 사용법 오류가 발생합니다.
  • local postgres start는 PostgreSQL이 연결을 수락할 때까지 대기하며, 대기 시간은 --wait-timeout 초(기본값 60, 최대 600)로 제한됩니다. --port를 생략하면 5432가 사용 가능할 때 이를 사용하고, 그렇지 않으면 포트를 자동으로 선택합니다. 명시적으로 요청한 포트가 이미 사용 중이면 거부됩니다.

기타 명령어

요구 사항

  • macOS (aarch64, x86_64) 또는 Linux (aarch64, x86_64)
  • Cloud 명령을 실행하려면 쓰기 액세스를 위한 ClickHouse Cloud API Key가 필요합니다. OAuth 로그인은 읽기 전용입니다
  • clickhousectl local postgres를 실행하려면 Docker가 필요합니다
마지막 수정일 2026년 9월 26일