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 키 및 활동 로그를 관리합니다.
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 서비스 생성
create 실행 시에만 반환되므로 반드시 따로 저장하십시오. --ip-allow를 생략하면 5432 및 6432 포트가 모든 주소에 개방됩니다. state가 running이 될 때까지 기다린 후 CA 인증서를 사용하여 psql로 연결하십시오.
ClickPipes, ClickStack 및 백업 확인
사용자 정의 함수(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로 설치할 수 있습니다.
더 알아보기
- clickhousectl 참고: 모든 명령 그룹, 로컬 개발, 스킬, 자체 업데이트, 텔레메트리를 다룹니다.
- 리포지토리 가이드:
- 리포지토리 참고 문서: 인증 및 액세스, SQL 및 쿼리 API, ClickPipe 구성, 자동화 및 출력 계약