database/sql 또는 “표준” API를 사용하면 표준 인터페이스를 준수함으로써, 애플리케이션 코드가 기본 데이터베이스에 종속되지 않아야 하는 시나리오에서 클라이언트를 사용할 수 있습니다. 다만 그에 따른 대가도 있습니다. 추가적인 추상화 계층과 간접화가 생기며, ClickHouse와 완전히 맞지 않는 기본 타입도 포함됩니다. 그러나 도구가 여러 데이터베이스에 연결해야 하는 환경에서는 이러한 비용이 일반적으로 수용 가능한 수준입니다.
또한 이 클라이언트는 전송 계층으로 HTTP를 사용하는 것도 지원합니다. 이 경우에도 최적의 성능을 위해 데이터는 계속 Native 형식으로 인코딩됩니다.
연결
clickhouse://<host>:<port>?<query_option>=<value> 형식의 DSN 문자열과 Open 메서드를 사용하거나 clickhouse.OpenDB 메서드를 통해 설정할 수 있습니다. 후자는 database/sql 사양의 일부는 아니지만 sql.DB 인스턴스를 반환합니다. 이 메서드는 프로파일링과 같은 기능을 제공하며, 이러한 기능은 database/sql 사양만으로는 명확하게 노출하기 어렵습니다.
conn 변수가 이미 생성되어 사용 가능한 것으로 가정합니다.
연결 설정
hosts- 로드 밸런싱 및 장애 조치를 위한 단일 주소 호스트를 쉼표로 구분한 목록 - Connecting to Multiple Nodes를 참조하십시오.username/password- 인증 자격 증명 - Authentication을 참조하십시오.database- 현재 기본 데이터베이스를 선택합니다dial_timeout- 기간 문자열로, 부호가 있을 수도 있는 10진수 값에 선택적 소수부와300ms,1s같은 단위 접미사를 붙여 지정합니다. 유효한 시간 단위는ms,s,m입니다.connection_open_strategy-random/in_order(기본값random) - Connecting to Multiple Nodes를 참조하십시오.round_robin- 집합에서 라운드 로빈 방식으로 서버를 선택합니다in_order- 지정된 순서에서 먼저 사용 가능한 서버를 선택합니다
debug- 디버그 출력을 활성화합니다 (불리언 값)compress- 압축 알고리즘을 지정합니다 -none(기본값),zstd,lz4,gzip,deflate,br.true로 설정하면lz4가 사용됩니다. 네이티브 통신에서는lz4와zstd만 지원됩니다.compress_level- 압축 수준(기본값은0)입니다. 압축을 참조하십시오. 이는 알고리즘에 따라 다릅니다:gzip--2(최고 속도)부터9(최고 압축)까지deflate--2(최고 속도)부터9(최고 압축)까지br-0(최고 속도)부터11(최고 압축)까지zstd,lz4- 무시됩니다
secure- 보안 SSL 연결을 설정합니다 (기본값은false)skip_verify- 인증서 검증을 건너뜁니다 (기본값은false)block_buffer_size- block 버퍼 크기를 제어할 수 있습니다.BlockBufferSize를 참조하십시오. (기본값은2)
HTTP를 통한 연결
세션
HTTP 전용세션은 HTTP 전송을 사용할 때만 필요합니다. 네이티브 TCP 연결은 세션이 기본으로 자동 제공됩니다.
session_id를 설정으로 전달해 임시 테이블과 같은 세션 기반 기능을 활성화합니다.
실행
sql SQL 문을 실행할 수 있습니다.
ExecContext를 사용할 수 있습니다. 자세한 내용은 Context 사용을 참조하십시오.
배치 삽입
Being 메서드로 sql.Tx를 생성하면 구현할 수 있습니다. 그런 다음 INSERT 문으로 Prepare 메서드를 사용해 배치를 준비할 수 있습니다. 그러면 Exec 메서드로 행을 추가할 수 있는 sql.Stmt가 반환됩니다. 배치는 원래 sql.Tx에서 Commit을 실행할 때까지 메모리에 누적됩니다.
행 조회
QueryRow 메서드를 사용해 수행할 수 있습니다. 이 메서드는 *sql.Row를 반환하며, 여기서 컬럼이 매핑될 변수의 포인터를 전달해 Scan을 호출할 수 있습니다. QueryRowContext 변형을 사용하면 background가 아닌 다른 Context를 전달할 수 있습니다. 자세한 내용은 Context 사용를 참조하십시오.
Query 메서드를 사용해야 합니다. 이 메서드는 *sql.Rows 구조체를 반환하며, 이 구조체에서 Next를 호출해 행을 순회할 수 있습니다. 이에 해당하는 QueryContext는 context를 전달할 수 있습니다.
비동기 삽입
ExecContext 메서드를 사용해 삽입을 실행하면 구현할 수 있습니다. 아래와 같이 비동기 모드가 활성화된 Context를 전달해야 합니다. 이렇게 하면 클라이언트가 서버의 삽입 완료까지 기다릴지, 아니면 데이터가 수신되는 즉시 응답할지를 사용자가 지정할 수 있습니다. 이는 사실상 wait_for_async_insert 매개변수를 제어합니다.
매개변수 바인딩
Exec, Query, QueryRow 메서드(및 이에 상응하는 Context 버전)에 매개변수를 전달할 수 있습니다. 위치 기반, 이름 기반, 번호 기반 매개변수를 지원합니다.
Using context
Context 변형을 사용해 구현합니다. 즉, 기본적으로 background context를 사용하는 Exec 같은 메서드에는 context를 첫 번째 매개변수로 전달할 수 있는 ExecContext 변형이 있습니다. 이를 통해 애플리케이션 흐름의 어느 단계에서나 context를 전달할 수 있습니다. 예를 들어, ConnContext를 통해 연결을 설정할 때나 QueryRowContext를 통해 쿼리 행을 요청할 때 context를 전달할 수 있습니다. 사용 가능한 모든 메서드의 예시는 아래와 같습니다.
context를 사용해 마감 시간, 취소 신호, Query id, quota 키, 연결 설정을 전달하는 방법에 대한 자세한 내용은 ClickHouse API의 Context 사용를 참조하십시오.
동적 스캔
Scan에 전달할 수 있는 올바른 유형의 변수 런타임 인스턴스를 생성할 수 있습니다. 이를 통해 유형을 미리 알 수 없는 컬럼도 읽을 수 있습니다.
외부 테이블
SELECT 쿼리와 함께 데이터를 ClickHouse로 보낼 수 있습니다. 이 데이터는 임시 테이블에 저장되며, 쿼리 자체에서 평가에 사용할 수 있습니다.
쿼리와 함께 클라이언트에서 외부 데이터를 보내려면, 먼저 ext.NewTable로 외부 테이블을 생성한 다음 이를 Context를 통해 전달해야 합니다.
OpenTelemetry
clickhouse.WithSpan을 사용해 쿼리에 스팬을 연결하십시오.
HTTP 전송 제한 사항ClickHouse 서버는 표준
traceparent / tracestate HTTP 헤더를 허용하지만, clickhouse-go의 HTTP 전송은 현재 이를 전송하지 않으므로 HTTP에서는 WithSpan이 적용되지 않습니다. 우회 방법으로 연결 옵션의 HttpHeaders를 통해 헤더를 수동으로 설정할 수 있습니다.압축
lz4 및 zstd 압축을 지원합니다. 또한 HTTP 연결에서는 gzip, deflate, br 압축도 지원합니다. 이들 중 하나라도 활성화되면 삽입 시 블록과 쿼리 응답에 압축이 적용됩니다. 그 외 요청(예: Ping 또는 쿼리 요청)은 압축되지 않습니다. 이는 lz4 및 zstd 옵션의 동작과 일치합니다.
연결을 설정할 때 OpenDB 메서드를 사용하는 경우 Compression 구성을 전달할 수 있습니다. 여기에는 압축 수준을 지정하는 기능도 포함됩니다(아래 참조). DSN과 함께 sql.Open으로 연결하는 경우 compress 매개변수를 사용하십시오. 이 값에는 gzip, deflate, br, zstd, lz4와 같은 특정 압축 알고리즘이나 불리언 플래그를 사용할 수 있습니다. true로 설정하면 lz4가 사용됩니다. 기본값은 none이며, 즉 압축이 비활성화된 상태입니다.
compress_level 또는 Compression 옵션의 Level 필드로 제어할 수 있습니다. 기본값은 0이지만 알고리즘마다 다릅니다:
gzip--2(최고 속도) ~9(최고 압축)deflate--2(최고 속도) ~9(최고 압축)br-0(최고 속도) ~11(최고 압축)zstd,lz4- 무시됩니다