메인 콘텐츠로 건너뛰기
ClickHouse CLI(clickhousectl, 별칭 chctl)를 사용하면 터미널, 스크립트 또는 코딩 에이전트에서 ClickHouse Cloud를 관리할 수 있습니다. 이 페이지에서는 CLI의 Cloud 관련 기능을 다룹니다. 모든 명령 그룹과 로컬 개발, 전체 동작에 대한 자세한 내용은 clickhousectl 참고 문서를 참조하십시오.

관리할 수 있는 항목

clickhousectl cloud 명령어로 다음 항목을 관리할 수 있습니다.
  • 서비스: ClickHouse Cloud 서비스를 생성, 확장, 시작 및 중지하고, 쿼리 API를 통해 해당 서비스에서 SQL을 실행합니다.
  • Managed Postgres (Beta): Postgres 서비스, 읽기 복제본(Read Replicas), 특정 시점 복원을 생성하고 구성을 변경합니다.
  • ClickPipes: 객체 스토리지, Kafka, Kinesis, Pub/Sub, Postgres, MySQL, MongoDB, BigQuery에서 데이터를 수집합니다.
  • ClickStack: Managed ClickStack 서비스의 소스, 대시보드, 알림, 웹훅, 저장된 검색 및 역할을 관리합니다.
  • 사용자 정의 함수: 실행형 UDF를 로컬에서 테스트한 후 Cloud 서비스에 배포합니다.
  • 백업: 백업 목록을 조회하고, 백업 일정을 변경하며, 백업을 새 서비스로 복원합니다.
  • 조직 액세스: 조직, 구성원, 초대, API 키 및 활동 로그를 관리합니다.
각 명령의 플래그와 필요한 API Key 권한을 확인하려면 clickhousectl cloud <command> --help를 실행하십시오.

설치

이 스크립트는 ~/.local/bin/clickhousectl과 chctl 별칭을 설치합니다. ~/.local/bin이 PATH에 포함되어 있는지 확인하십시오. npm, pip, uv 등 다른 설치 방법은 설치를 참조하십시오.

인증

브라우저 OAuth 로그인은 읽기 전용입니다. 리소스를 생성하거나 변경하려면 해당 작업을 허용하는 역할이 부여된 API Key가 필요합니다.
로그인하면 자격 증명을 검증한 후 아이덴티티를 출력합니다. 언제든지 clickhousectl cloud auth whoami로 확인할 수 있습니다. 여러 조직에 속해 있다면 Cloud 명령어에 --org-id <org-id>(또는 --org-name <name>)를 추가하십시오. CI 환경에서는 로그인하는 대신 CLICKHOUSE_CLOUD_API_KEY와 CLICKHOUSE_CLOUD_API_SECRET을 설정하십시오. 자격 증명 우선순위와 로그아웃 방법은 인증을 참조하십시오.

예시

서비스 생성 및 쿼리

서비스 생성 명령은 서비스가 실행 상태가 되기 전에 반환됩니다. state가 running이 될 때까지 clickhousectl cloud service get "$CH_ID"를 폴링하십시오. API Key로 처음 쿼리를 실행하면 clickhousectl이 서비스의 쿼리 API 엔드포인트에 사용자의 API Key를 추가하며, 엔드포인트가 없으면 새로 생성합니다. 이때 새 키는 생성되지 않습니다. 이렇게 하는 대신 오류가 발생하도록 하려면 --no-auto-enable을 지정하십시오. OAuth를 사용하면 service query는 읽기 전용 SELECT SQL 문만 실행합니다. 쿼리 API는 약 30초가 지나면 시간 초과되므로, 오래 걸리는 쿼리나 대량 적재(bulk loads)에는 clickhouse client를 사용하십시오.

관리형 Postgres 서비스 생성

비밀번호와 연결 문자열(Connection String)은 create 실행 시에만 반환되므로 반드시 따로 저장하십시오. --ip-allow를 생략하면 5432 및 6432 포트가 모든 주소에 개방됩니다. state가 running이 될 때까지 기다린 후 CA 인증서를 사용하여 psql로 연결하십시오.

ClickPipes, ClickStack 및 백업 확인

이러한 읽기 명령어는 OAuth로 사용할 수 있습니다. ClickPipe를 생성하거나 ClickStack 리소스를 변경하려면 API Key가 필요합니다. 자세한 내용은 아래 리포지토리 가이드를 참조하십시오.

사용자 정의 함수(user-defined function) 배포

먼저 clickhousectl local udf deploy my_udf를 사용하여 로컬 서버에서 함수를 테스트하세요.

JSON 출력과 코딩 에이전트

Cloud 명령어는 --json 옵션을 지원하며, CLI는 코딩 에이전트를 감지하면 자동으로 JSON 출력을 사용합니다. 이때 cloud service query의 기본 포맷은 JSONEachRow가 되므로, 출력을 파싱하는 스크립트에서는 --format TabSeparated와 같이 --format을 명시적으로 지정하십시오. 자세한 내용은 JSON 출력 및 종료 코드를 참조하십시오. ClickHouse agent skills는 clickhousectl skills로 설치할 수 있습니다.

더 알아보기