Skip to main content
ClickHouse ODBC 드라이버는 ODBC 호환 애플리케이션을 ClickHouse에 연결하기 위한 표준 준수 인터페이스를 제공합니다. 이 드라이버는 ODBC API를 구현하여 애플리케이션, BI 도구 및 스크립팅 환경에서 SQL 쿼리를 실행하고 결과를 가져오며 익숙한 방식으로 ClickHouse와 상호 작용할 수 있도록 합니다. 드라이버는 모든 ClickHouse 배포 환경에서 기본적으로 지원되는 HTTP 프로토콜을 통해 ClickHouse 서버와 통신합니다. 따라서 로컬 설치 환경, 클라우드 관리형 서비스, HTTP 기반 액세스만 사용 가능한 환경 등 다양한 환경에서 일관되게 작동합니다. 드라이버의 소스 코드는 ClickHouse-ODBC GitHub 리포지토리에서 확인할 수 있습니다.
호환성을 높이려면 ClickHouse 서버를 버전 24.11 이상으로 업데이트하는 것이 좋습니다.
이 드라이버는 현재 활발히 개발되고 있습니다. 일부 ODBC 기능은 아직 완전히 구현되지 않았을 수 있습니다. 현재 버전은 필수 연결 기능과 핵심 ODBC 기능 제공에 중점을 두고 있으며, 추가 기능은 향후 릴리스에서 제공될 예정입니다.피드백은 매우 소중하며 새 기능과 개선 사항의 우선순위를 정하는 데 도움이 됩니다. 제한 사항, 누락된 기능 또는 예상치 못한 동작을 발견한 경우 다음 이슈 추적기를 통해 의견이나 기능 요청을 공유하십시오. https://github.com/ClickHouse/clickhouse-odbc/issues

Windows 설치

최신 드라이버 버전은 https://github.com/ClickHouse/clickhouse-odbc/releases/latest에서 확인할 수 있습니다. 여기에서 MSI 설치 관리자를 다운로드하고 실행한 후 간단한 설치 단계를 따르십시오.

테스트

이 간단한 PowerShell 스크립트를 실행하여 드라이버를 테스트할 수 있습니다. 아래 텍스트를 복사하고 URL, 사용자 이름, password를 설정한 다음 PowerShell 명령 프롬프트에 붙여 넣으십시오. $reader.GetValue(0)을 실행하면 ClickHouse 서버 version이 표시됩니다.

구성 매개변수

아래 매개변수는 ClickHouse ODBC 드라이버 연결을 설정할 때 가장 자주 사용하는 설정입니다. 필수 인증, 연결 동작, 데이터 처리 옵션을 포함합니다. 지원되는 매개변수의 전체 목록은 프로젝트 GitHub 페이지 https://github.com/ClickHouse/clickhouse-odbc에서 확인할 수 있습니다.
  • Url: ClickHouse 서버의 전체 HTTP(S) 엔드포인트를 지정합니다. 프로토콜, 호스트, 포트 및 선택적 경로를 포함합니다.
  • Username: ClickHouse 서버 인증에 사용하는 사용자 이름입니다.
  • Password: 지정된 사용자 이름에 연결된 비밀번호입니다. 제공하지 않으면 드라이버는 비밀번호 인증 없이 연결합니다.
  • Database: 연결에 사용할 기본 데이터베이스입니다.
  • Timeout: 요청을 중단하기 전에 드라이버가 서버 응답을 기다리는 최대 시간(초)입니다.
  • ClientName: 클라이언트 메타데이터의 일부로 ClickHouse 서버에 전송되는 사용자 지정 식별자입니다. 추적하거나 서로 다른 애플리케이션의 트래픽을 구분하는 데 유용합니다. 이 매개변수는 드라이버가 생성하는 HTTP 요청의 User-Agent 헤더 일부가 됩니다.
  • Compression: 요청 및 응답 payload에 대한 HTTP 압축을 활성화하거나 비활성화합니다. 활성화하면 대규모 결과 집합의 대역폭 사용량을 줄이고 성능을 개선할 수 있습니다.
  • SqlCompatibilitySettings: ClickHouse가 기존 관계형 데이터베이스처럼 동작하도록 하는 쿼리 설정을 활성화합니다. 예를 들어 Power BI와 같은 타사 도구가 쿼리를 자동으로 생성할 때 유용합니다. 이러한 도구는 일반적으로 일부 ClickHouse 전용 동작을 인식하지 못하므로 오류 또는 예기치 않은 결과를 초래하는 쿼리를 생성할 수 있습니다. 자세한 내용은 SqlCompatibilitySettings 구성 매개변수에서 사용하는 ClickHouse 설정 을 참조하십시오.
다음은 연결을 설정하기 위해 드라이버에 전달하는 전체 연결 문자열의 예시입니다.
  • WSL 인스턴스에 로컬로 설치된 ClickHouse 서버
  • ClickHouse Cloud 인스턴스

Microsoft Power BI 통합

ODBC 드라이버를 사용하여 Microsoft Power BI를 ClickHouse 서버에 연결할 수 있습니다. Power BI는 표준 설치에 포함된 두 가지 연결 옵션, 즉 범용 ODBC Connector와 ClickHouse Connector를 제공합니다. 두 Connector는 모두 내부적으로 ODBC를 사용하지만 지원하는 기능이 다릅니다.
  • ClickHouse Connector(권장) 내부적으로 ODBC를 사용하지만 DirectQuery 모드를 지원합니다. 이 모드에서는 Power BI가 SQL 쿼리를 자동으로 생성하고 각 시각화 또는 필터 작업에 필요한 데이터만 가져옵니다.
  • ODBC Connector Import 모드만 지원합니다. Power BI는 사용자가 제공한 쿼리를 실행하거나 전체 테이블을 선택한 후, 전체 결과 집합을 Power BI로 가져옵니다. 이후 갱신 시에는 전체 데이터셋을 다시 가져옵니다.
사용 사례에 따라 Connector를 선택하십시오. DirectQuery는 대규모 데이터셋을 사용하는 대화형 대시보드에 가장 적합합니다. 데이터의 전체 로컬 복사본이 필요한 경우에는 Import 모드를 선택하십시오. Microsoft Power BI와 ClickHouse 통합에 관한 자세한 내용은 Power BI 통합에 관한 ClickHouse 문서 페이지를 참조하십시오.

SQL 호환성 설정

ClickHouse는 고유한 SQL 방언을 사용하며, 경우에 따라 MS SQL Server, MySQL, PostgreSQL 등의 다른 데이터베이스와 다르게 동작합니다. 이러한 차이는 ClickHouse 기능을 더 쉽게 사용할 수 있는 개선된 구문을 제공하므로 대개 장점으로 작용합니다. 하지만 ODBC 드라이버는 사용자가 직접 쿼리를 작성하는 대신 Power BI와 같은 타사 도구가 쿼리를 생성하는 환경에서 흔히 사용됩니다. 이러한 쿼리는 일반적으로 SQL 표준의 제한된 부분 집합만 사용합니다. 이때 ClickHouse가 SQL 표준과 다르게 동작하면 예상과 다른 결과나 오류가 발생할 수 있습니다. ODBC 드라이버는 ClickHouse의 동작을 표준 SQL에 더 가깝게 맞추기 위한 특정 쿼리 설정을 활성화하는 추가 구성 매개변수 SqlCompatibilitySettings를 제공합니다.

SqlCompatibilitySettings 구성 매개변수로 활성화되는 ClickHouse 설정

이 섹션에서는 ODBC 드라이버가 수정하는 설정과 그 이유를 설명합니다. cast_keep_nullable 기본적으로 ClickHouse에서는 널 허용 타입을 널 비허용 타입으로 변환할 수 없습니다. 하지만 많은 BI 도구는 타입 변환 시 널 허용 타입과 널 비허용 타입을 구분하지 않습니다. 따라서 BI 도구가 생성한 다음과 같은 쿼리를 흔히 볼 수 있습니다:
기본적으로 value 컬럼이 널 허용인 경우 이 쿼리는 다음 메시지와 함께 실패합니다.
cast_keep_nullable을 활성화하면 CAST가 인수의 널 허용 여부를 유지하도록 동작이 변경됩니다. 이 설정을 사용하면 이러한 유형의 변환에서 ClickHouse의 동작이 다른 데이터베이스 및 SQL 표준에 더욱 가까워집니다. prefer_column_name_to_alias ClickHouse에서는 같은 SELECT 목록에 있는 표현식을 별칭으로 참조할 수 있습니다. 예를 들어, 다음 쿼리는 반복을 줄여 더 쉽게 작성할 수 있습니다:
이 기능은 널리 사용되지만, 다른 데이터베이스에서는 일반적으로 동일한 SELECT 목록에서 이와 같은 방식으로 별칭을 해석하지 않으므로 이러한 쿼리에서 오류가 발생합니다. 별칭의 이름이 컬럼 이름과 같을 때 문제가 가장 두드러집니다. 예시:
avg(value)는 어떤 value를 집계해야 할까요? 기본적으로 ClickHouse는 별칭을 우선하므로 사실상 중첩 집계가 되며, 이는 대부분의 도구가 기대하는 동작이 아닙니다. 이 문제는 단독으로는 드물게 발생하지만, 일부 BI 도구는 컬럼 별칭을 재사용하는 서브쿼리가 포함된 쿼리를 생성합니다. 예를 들어 Power BI는 다음과 유사한 쿼리를 자주 생성합니다:
C1을 참조하면 다음과 같은 오류가 발생할 수 있습니다:
다른 데이터베이스는 일반적으로 이처럼 같은 수준에서 별칭을 해석하지 않고, 대신 C1을 서브쿼리의 컬럼으로 처리합니다. ClickHouse에서도 유사한 동작을 유지하고 이러한 쿼리를 오류 없이 실행할 수 있도록 ODBC 드라이버는 prefer_column_name_to_alias를 활성화합니다. 대부분의 경우 이러한 설정을 활성화해도 문제없습니다. 하지만 readonly 설정이 1인 사용자는 SELECT 쿼리에서도 어떤 설정도 변경할 수 없습니다. 이러한 사용자에게 SqlCompatibilitySettings를 활성화하면 오류가 발생합니다. 다음 섹션에서는 이 구성 매개변수를 읽기 전용 사용자에게도 적용하는 방법을 설명합니다.

읽기 전용 사용자에게 SQL 호환성 설정 적용하기

SqlCompatibilitySettings 매개변수를 활성화한 상태로 ODBC 드라이버를 통해 ClickHouse에 연결하면, readonly 설정이 1인 사용자는 드라이버가 쿼리 설정을 수정하려고 시도하므로 오류가 발생합니다:
읽기 전용 모드의 사용자는 개별 SELECT 쿼리에 대해서도 설정을 변경할 수 없으므로 이 문제가 발생합니다. 해결 방법은 여러 가지가 있습니다. 옵션 1. readonly2로 설정 가장 간단한 방법입니다. readonly2로 설정하면 사용자를 읽기 전용 모드로 유지하면서도 설정을 변경할 수 있습니다.
대부분의 경우 readonly를 2로 설정하는 것이 이 문제를 해결하는 가장 쉽고 권장되는 방법입니다. 이 방법이 효과가 없으면 두 번째 옵션을 사용하십시오. 옵션 2. ODBC 드라이버가 설정하는 값에 맞게 사용자 설정을 변경합니다. 이 방법도 간단합니다. ODBC 드라이버가 설정하려는 값과 일치하도록 사용자 설정을 업데이트하십시오.
이 변경 사항을 적용하면 ODBC 드라이버가 계속 설정 적용을 시도하더라도 값이 이미 일치하므로 실질적인 변경은 이루어지지 않으며 오류도 방지됩니다. 이 방법도 간단하지만 유지 관리가 필요합니다. 최신 드라이버 버전에서는 호환성을 위해 설정 목록이 변경되거나 새 설정이 추가될 수 있습니다. ODBC 사용자에 이러한 설정을 하드코딩한 경우, ODBC 드라이버가 추가 설정을 적용하기 시작할 때마다 해당 설정을 업데이트해야 할 수 있습니다.
마지막 수정일 2026년 8월 18일