clickhouse-client로 ClickHouse Cloud에 데이터 삽입하기

clickhouse-client — ClickHouse 공식 CLI 클라이언트 — 를 사용해서 로컬 CSV 파일의 데이터를 ClickHouse Cloud 서비스에 삽입할 거예요. 클라이언트 설치부터 샘플 데이터 준비, 연결, 테이블 생성, 데이터 삽입까지 전체 흐름을 배워요.

출처: Insert data into ClickHouse Cloud using clickhouse-client

본문

사전 요구사항 (Prerequisites)

이 가이드를 성공적으로 따라 하려면 다음이 필요해요:

실행 중인 ClickHouse Cloud 서비스. 아직 없다면 ClickHouse Cloud 퀵 스타트를 먼저 완료하세요.

다음 퀵스타트도 완료했어야 해요:

Cloud 연결 정보 얻기 — 연결하려면 호스트명, 사용자명, 비밀번호가 필요해요.

만들게 될 것 (What you'll build)

이 퀵스타트에서는 clickhouse-client — ClickHouse 공식 CLI 클라이언트 — 를 사용해서 로컬 CSV 파일의 데이터를 ClickHouse Cloud 서비스에 삽입해요. clickhouse-client를 설치하고, 샘플 데이터셋을 준비하고, Cloud 서비스에 연결하고, 테이블을 만들고, 로컬 머신에서 데이터를 삽입할 거예요. 끝나면 로컬 파일을 ClickHouse Cloud에 로드하는 clickhouse-client 사용법을 알게 돼요. 이 워크플로는 CSV, Parquet, JSON 등 많은 포맷에서 동작해요.

1. clickhouse-client 설치하기

clickhouse-client는 ClickHouse에 연결하는 공식 CLI예요. ClickHouse 바이너리에 포함되어 있어요. 유니버설 인스톨러로 설치하세요:

curl https://clickhouse.com/ | sh

이렇게 하면 최신 clickhouse 바이너리가 현재 디렉터리에 내려받아져요. 설치를 확인해 보세요:

./clickhouse client --version

ClickHouse 버전 번호를 보여 주는 출력이 보이면 clickhouse-client를 사용할 준비가 된 거예요.

2. 샘플 CSV 파일 준비하기

이 퀵스타트가 단독으로 동작하도록 작은 샘플 CSV 파일을 만들게요. 터미널에서 다음을 실행하세요:

cat <<'EOF' > sample_data.csv
timestamp,event_type,user_id,duration_ms,status
2024-01-15 10:30:00,page_view,1001,120,success
2024-01-15 10:31:15,click,1002,45,success
2024-01-15 10:32:00,page_view,1003,200,success
2024-01-15 10:33:30,purchase,1001,1500,success
2024-01-15 10:34:00,click,1004,60,error
2024-01-15 10:35:45,page_view,1002,95,success
2024-01-15 10:36:10,purchase,1005,2200,success
2024-01-15 10:37:00,click,1003,30,success
2024-01-15 10:38:20,page_view,1004,150,error
2024-01-15 10:39:00,purchase,1002,1800,success
EOF

3. Cloud 서비스에 연결하기

아래 명령들은 Cloud 연결 정보 얻기 퀵스타트에서 설명한 대로 CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD를 환경 변수로 내보냈다고 가정해요. 내보내지 않았다면 그 자리에 실제 값을 직접 넣으면 돼요. Cloud 서비스에 간단한 쿼리를 실행해서 연결을 테스트해 보세요:

./clickhouse client \
  --host $CLICKHOUSE_HOST \
  --port 9440 \
  --user $CLICKHOUSE_USER \
  --password $CLICKHOUSE_PASSWORD \
  --secure \
  -q "SELECT 1"

연결이 성공하면 터미널에 1이 출력돼요. 연결 오류가 나면 Cloud 콘솔에서 서비스가 깨어 있는지, 호스트명과 비밀번호가 정확한지 확인하세요.

포트 9440은 ClickHouse Cloud의 보안 네이티브 프로토콜 포트예요. --secure 플래그는 TLS 암호화를 켜요. 이 둘은 모든 Cloud 연결에 필수예요.

4. 대상 테이블을 만들고 데이터 삽입하기

먼저 Cloud 서비스에 데이터를 받을 테이블을 만드세요:

./clickhouse client \
  --host $CLICKHOUSE_HOST \
  --port 9440 \
  --user $CLICKHOUSE_USER \
  --password $CLICKHOUSE_PASSWORD \
  --secure \
  -q "
    CREATE TABLE IF NOT EXISTS events (
      timestamp DateTime,
      event_type LowCardinality(String),
      user_id UInt32,
      duration_ms UInt32,
      status LowCardinality(String)
    )
    ENGINE = MergeTree
    ORDER BY (event_type, timestamp)
  "

이제 로컬 CSV 파일의 데이터를 삽입하세요. 이게 핵심 단계예요 — clickhouse-client는 파일을 stdin에서 읽어 원격 서비스로 스트리밍해요:

./clickhouse client \
  --host $CLICKHOUSE_HOST \
  --port 9440 \
  --user $CLICKHOUSE_USER \
  --password $CLICKHOUSE_PASSWORD \
  --secure \
  -q "INSERT INTO events FORMAT CSVWithNames" < sample_data.csv

clickhouse-client는 CSV 파일의 내용을 Cloud 서비스로 직접 보내요. CSVWithNames 포맷은 첫 번째 행이 컬럼 헤더임을 ClickHouse에 알려 줘요.

5. 데이터가 삽입되었는지 확인하기

행이 도착했는지 확인하려면 Cloud 서비스에 쿼리를 실행하세요:

./clickhouse client \
  --host $CLICKHOUSE_HOST \
  --port 9440 \
  --user $CLICKHOUSE_USER \
  --password $CLICKHOUSE_PASSWORD \
  --secure \
  -q "SELECT count() FROM events"

샘플 CSV의 행 수인 10이 보일 거예요. 데이터를 미리 보세요:

./clickhouse client \
  --host $CLICKHOUSE_HOST \
  --port 9440 \
  --user $CLICKHOUSE_USER \
  --password $CLICKHOUSE_PASSWORD \
  --secure \
  -q "SELECT * FROM events ORDER BY timestamp LIMIT 5"

이 동일한 워크플로는 Parquet, TSV, JSON, Avro, ORC 등 다른 많은 지원 포맷에서도 동작해요 — FORMAT 절만 바꾸고 적절한 파일을 파이프로 넣으면 돼요.

다음 단계 (Next steps)

이 퀵스타트에서 clickhouse-client를 설치하고, ClickHouse Cloud 서비스에 연결하고, 로컬 CSV 파일의 데이터를 Cloud로 스트리밍했어요. 같은 접근은 Parquet, JSON 등 수십 가지 포맷에도 적용돼요. 다음 퀵스타트를 계속 진행해 보세요:

첫 번째 MergeTree 테이블 만들기

또는 레퍼런스 문서로 더 깊이 들어가 보세요:

clickhouse-client로 ClickHouse Cloud에 데이터 삽입하기