ODBC 드라이버

ODBC 드라이버 (ODBC driver)

ClickHouse ODBC 드라이버는 ODBC 호환 애플리케이션을 ClickHouse에 연결하기 위한 표준 준수 인터페이스를 제공해요. ODBC API를 구현해서 애플리케이션, BI 도구, 스크립팅 환경이 익숙한 방식으로 SQL 쿼리를 실행하고 결과를 가져올 수 있게 해 줘요.

출처: 문서

본문

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에 설치 (Installation on Windows)

드라이버의 최신 버전은 https://github.com/ClickHouse/clickhouse-odbc/releases/latest에서 찾을 수 있어요. 거기서 MSI 설치 프로그램을 다운로드해 실행하고 간단한 설치 단계를 따르면 돼요.

테스트 (Testing)

이 간단한 PowerShell 스크립트를 실행해 드라이버를 테스트할 수 있어요. 아래 텍스트를 복사하고 URL, 사용자, 비밀번호를 설정한 다음 PowerShell 명령 프롬프트에 붙여 넣으세요 — $reader.GetValue(0)를 실행하면 ClickHouse 서버 버전이 표시돼야 해요.

$url = "http://127.0.0.1:8123/"
$username = "default"
$password = ""
$conn = New-Object System.Data.Odbc.OdbcConnection("`
    Driver={ClickHouse ODBC Driver (Unicode)};`
    Url=$url;`
    Username=$username;`
    Password=$password")
$conn.Open()
$cmd = $conn.CreateCommand()
$cmd.CommandText = "select version()"
$reader = $cmd.ExecuteReader()
$reader.Read()
$reader.GetValue(0)
$reader.Close()
$conn.Close()

구성 파라미터 (Configuration parameters)

아래 파라미터는 ClickHouse ODBC 드라이버와 연결을 설정할 때 가장 흔하게 사용되는 설정들을 나타내요. 필수 인증, 연결 동작, 데이터 처리 옵션을 다룹니다. 지원되는 파라미터의 전체 목록은 프로젝트의 GitHub 페이지 https://github.com/ClickHouse/clickhouse-odbc에서 볼 수 있어요.

• Url: ClickHouse 서버의 전체 HTTP(S) 엔드포인트를 지정. 프로토콜, 호스트, 포트, 선택적 경로를 포함해요.
• Username: ClickHouse 서버와의 인증에 사용되는 사용자 이름.
• Password: 지정된 사용자 이름과 연관된 비밀번호. 제공하지 않으면 드라이버는 비밀번호 인증 없이 연결해요.
• Database: 연결에 사용할 기본 데이터베이스.
• Timeout: 드라이버가 요청을 중단하기 전에 서버 응답을 기다리는 최대 시간(초).
• ClientName: 클라이언트 메타데이터의 일부로 ClickHouse 서버에 보내지는 사용자 정의 식별자. 추적하거나 서로 다른 애플리케이션의 트래픽을 구분하는 데 유용해요. 이 파라미터는 드라이버가 생성하는 HTTP 요청의 User-Agent 헤더의 일부가 돼요.
• Compression: 요청 및 응답 페이로드에 대한 HTTP 압축을 활성화하거나 비활성화. 활성화하면 대용량 결과 세트에서 대역폭 사용을 줄이고 성능을 개선할 수 있어요.
• SqlCompatibilitySettings: ClickHouse가 전통적인 관계형 데이터베이스처럼 동작하게 만드는 쿼리 설정을 활성화. 이는 Power BI 같은 서드파티 도구가 쿼리를 자동으로 생성할 때 유용해요. 그런 도구들은 보통 ClickHouse 특유의 동작을 알지 못하며 오류나 예상치 못한 결과를 만드는 쿼리를 생성할 수 있어요. 자세한 내용은 SqlCompatibilitySettings 구성 파라미터가 사용하는 ClickHouse 설정을 참고해요.

다음은 연결을 설정하기 위해 드라이버에 전달되는 전체 연결 문자열의 몇 가지 예시예요.

• WSL 인스턴스에 로컬로 설치된 ClickHouse 서버

Driver={ClickHouse ODBC Driver (Unicode)};Url=http://localhost:8123/;Username=default

• ClickHouse Cloud 인스턴스

Driver={ClickHouse ODBC Driver (Unicode)};Url=https://you-instance-url.gcp.clickhouse.cloud:8443/;Username=default;Password=your-password

Microsoft Power BI 통합 (Microsoft Power BI Integration)

ODBC 드라이버를 사용해 Microsoft Power BI를 ClickHouse 서버에 연결할 수 있어요. Power BI는 두 가지 연결 옵션을 제공해요. 일반 ODBC 커넥터와 ClickHouse 커넥터이며, 둘 다 표준 Power BI 설치에 포함돼 있어요.

두 커넥터 모두 내부적으로 ODBC에 의존하지만 기능이 달라요:

• ClickHouse 커넥터 (권장) 내부적으로 ODBC를 사용하지만 DirectQuery 모드를 지원해요. 이 모드에서 Power BI는 자동으로 SQL 쿼리를 생성하고 각 시각화 또는 필터 작업에 필요한 데이터만 가져와요.
• ODBC 커넥터 Import 모드만 지원해요. Power BI는 사용자가 제공한 쿼리(또는 전체 테이블 선택)를 실행하고 전체 결과 세트를 Power BI로 가져와요. 이후 새로고침은 전체 데이터 세트를 다시 가져와요.

사용 사례에 따라 커넥터를 선택하세요. DirectQuery는 대용량 데이터 세트가 있는 대화형 대시보드에 가장 잘 작동해요. 데이터의 전체 로컬 복사본이 필요할 때는 Import 모드를 선택하세요.

Microsoft Power BI를 ClickHouse와 통합하는 방법에 대한 자세한 내용은 Power BI 통합 문서 페이지를 참고해요.

SQL 호환성 설정 (SQL compatibility settings)

ClickHouse에는 고유한 SQL 방언이 있으며, 어떤 경우에는 MS SQL Server, MySQL, PostgreSQL 같은 다른 데이터베이스와 다르게 동작해요. 종종 이런 차이는 ClickHouse 기능을 더 쉽게 사용하게 해 주는 개선된 구문을 도입하므로 장점이에요.

하지만 ODBC 드라이버는 종종 Power BI 같은 서드파티 도구가 사용자가 아니라 쿼리를 생성하는 환경에서 사용돼요. 그런 쿼리는 보통 SQL 표준의 최소 하위 집합에 의존해요. 그런 경우 ClickHouse의 SQL 표준에서의 편차가 예상대로 동작하지 않아 예상치 못한 결과나 오류를 만들 수 있어요. ODBC 드라이버는 ClickHouse 동작을 표준 SQL에 더 가깝게 맞추는 특정 쿼리 설정을 활성화하는 추가 구성 파라미터 SqlCompatibilitySettings를 제공해요.

SqlCompatibilitySettings 구성 파라미터가 활성화하는 ClickHouse 설정 (ClickHouse settings enabled by SqlCompatibilitySettings configuration parameter)

이 섹션은 ODBC 드라이버가 수정하는 설정과 그 이유를 설명해요.

cast_keep_nullable

기본적으로 ClickHouse는 nullable 타입을 non-nullable 타입으로 변환하는 것을 허용하지 않아요. 하지만 많은 BI 도구는 타입 변환을 수행할 때 nullable과 non-nullable 타입을 구분하지 않아요. 그 결과 BI 도구가 다음과 같은 쿼리를 생성하는 것을 어렵지 않게 볼 수 있어요:

SELECT sum(CAST(value, 'Int32'))
FROM values

기본적으로 value 열이 nullable이면 이 쿼리는 다음 메시지로 실패해요:

DB::Exception: Cannot convert NULL value to non-Nullable type: while executing 'FUNCTION CAST(__table1.value :: 2,
'Int32'_String :: 1) -> CAST(__table1.value, 'Int32'_String) Int32 : 0'. (CANNOT_INSERT_NULL_IN_ORDINARY_COLUMN)

cast_keep_nullable을 활성화하면 CAST의 동작이 바뀌어 인수의 nullability를 보존해요. 이렇게 하면 ClickHouse 동작이 이런 변환에 대해 다른 데이터베이스 및 SQL 표준에 더 가까워져요.

prefer_column_name_to_alias

ClickHouse는 같은 SELECT 목록에서 표현식을 별칭(alias)으로 참조할 수 있게 해 줘요. 예를 들어 이 쿼리는 반복을 피하고 더 쓰기 쉬워요:

SELECT
    sum(value) AS S,
    count() AS C,
    S / C
FROM test

이 기능은 널리 사용되지만, 다른 데이터베이스는 보통 같은 SELECT 목록에서 이렇게 별칭을 해석하지 않으며 그런 쿼리는 오류가 나요. 별칭이 열과 같은 이름을 가질 때 문제가 가장 두드러져요. 예를 들어:

SELECT
    sum(value) AS value,
    avg(value)
FROM test

avg(value)는 어떤 value를 집계할까요? 기본적으로 ClickHouse는 별칭을 선호해서 사실상 중첩 집계로 바꾸는데, 이는 대부분의 도구가 기대하는 바가 아니에요.

그 자체로는 거의 문제가 되지 않지만, 일부 BI 도구는 열 별칭을 재사용하는 하위 쿼리가 있는 쿼리를 생성해요. 예를 들어 Power BI는 자주 다음 같은 쿼리를 생성해요:

SELECT
    sum(C1) AS C1,
    count(C1) AS C2
FROM
(
    SELECT sum(value) AS C1
    FROM test
    GROUP BY group_index
) AS TBL

C1에 대한 참조는 다음 오류를 만들 수 있어요:

Code: 184. DB::Exception: Received from localhost:9000. DB::Exception: Aggregate function sum(C1) AS C1 is found
inside another aggregate function in query. (ILLEGAL_AGGREGATION)

다른 데이터베이스는 보통 같은 레벨에서 이렇게 별칭을 해석하지 않고 C1을 하위 쿼리의 열로 취급해요. ClickHouse에서도 비슷한 동작을 보존하고 그런 쿼리가 오류 없이 실행되게 하기 위해 ODBC 드라이버는 prefer_column_name_to_alias를 활성화해요.

대부분의 경우 이 설정을 활성화하는 것은 문제가 되지 않아요. 하지만 readonly 설정이 1로 설정된 사용자는 SELECT 쿼리에서도 어떤 설정도 변경할 수 없어요. 그런 사용자의 경우 SqlCompatibilitySettings를 활성화하면 오류가 발생해요. 다음 섹션은 읽기 전용 사용자에게 이 구성 파라미터가 작동하게 하는 방법을 설명해요.

읽기 전용 사용자를 위한 SQL 호환성 설정 작동시키기 (Making SQL compatibility settings work for read-only users)

SqlCompatibilitySettings 파라미터를 활성화한 채 ODBC 드라이버로 ClickHouse에 연결하면, readonly 설정이 1로 설정된 사용자는 드라이버가 쿼리 설정을 수정하려 하므로 오류를 만나게 돼요:

Code: 164. DB::Exception: Cannot modify 'cast_keep_nullable' setting in readonly mode. (READONLY)
Code: 164. DB::Exception: Cannot modify 'prefer_column_name_to_alias' setting in readonly mode. (READONLY)

이는 읽기 전용 모드의 사용자가 개별 SELECT 쿼리에서도 설정을 변경할 수 없기 때문이에요. 이것을 고치는 방법은 여러 가지가 있어요.

옵션 1. readonly를 2로 설정

이것이 가장 간단한 옵션이에요. readonly를 2로 설정하면 사용자를 읽기 전용 모드로 유지하면서 설정 변경을 허용해요.

ALTER USER your_odbc_user MODIFY SETTING
    readonly = 2

대부분의 경우 readonly를 2로 설정하는 것이 이 문제를 해결하는 가장 쉽고 권장되는 방법이에요. 그것이 잘 안 된다면 두 번째 옵션을 사용하세요.

옵션 2. ODBC 드라이버가 설정하는 설정과 일치하도록 사용자 설정 변경

이것도 간단해요. ODBC 드라이버가 설정하려는 값과 이미 일치하도록 사용자 설정을 업데이트하는 거예요.

ALTER USER your_odbc_user MODIFY SETTING
    cast_keep_nullable = 1,
    prefer_column_name_to_alias = 1

이 변경으로 ODBC 드라이버는 여전히 설정을 적용하려 시도할 수 있지만, 값이 이미 일치하므로 실제 변경은 없고 오류는 피할 수 있어요.

이 옵션도 간단하지만 유지 관리가 필요해요. 새 드라이버 버전이 설정 목록을 바꾸거나 호환성을 위해 새 설정을 추가할 수 있으니까요. ODBC 사용자에 이 설정들을 하드코딩하면 ODBC 드라이버가 추가 설정을 적용하기 시작할 때 업데이트해야 할 수 있어요.

더 알아보기 (Learn more)

• JDBC 드라이버
• HTTP 인터페이스
• Power BI 통합