clickhousectl

curl https://clickhouse.com/cli | sh

# 버전 설치
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

~/.clickhousectl/
├── versions/
│   └── 26.3.4.3/
│       └── clickhouse
└── default              # 현재 활성 버전을 추적

clickhousectl local init

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  # 특정 호스트/포트에 연결

# 서버 시작 (기본적으로 백그라운드에서 실행)
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

.clickhousectl/
├── .gitignore              # 자동 생성됨, 모든 항목 무시
├── credentials.json        # Cloud API 자격 증명 (설정된 경우)
└── servers/
    ├── default/
    │   └── data/           # "default" 서버의 ClickHouse 데이터 파일
    └── dev/
        └── data/           # "dev" 서버의 ClickHouse 데이터 파일

clickhousectl cloud auth login

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

# 대화형 프롬프트
clickhousectl cloud auth login --interactive

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)

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

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>

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

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>

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

# 기본값: 사람을 위한 대화형 모드, 범위 선택 후 에이전트 선택
clickhousectl skills

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

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

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

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