Примеры кода для подключения к кластеру ClickHouse®

Статья создана

Обновлена 11 июня 2024 г.

Go
Java
Node.js
ODBC
- Linux
- Windows
PHP
Python (clickhouse-driver)
Python (requests)
Ruby

Вы можете подключаться к хостам кластера ClickHouse® в публичном доступе только с использованием SSL-сертификатов. В примерах ниже предполагается, что сертификаты RootCA.crt и IntermediateCA.crt:

расположены в директории /usr/local/share/ca-certificates/Yandex/ — для Ubuntu;
импортированы в хранилище доверенных корневых сертификатов — для Windows.

Подключение без использования SSL-сертификатов поддерживается только для хостов, находящихся не в публичном доступе. В этом случае трафик внутри виртуальной сети при подключении к БД шифроваться не будет.

При необходимости перед подключением настройте группы безопасности кластера.

При успешном подключении к кластеру и выполнении тестового запроса будет выведена версия ClickHouse®.

Примеры кода с заполненным FQDN хоста доступны в консоли управления по нажатию кнопки Подключиться на странице кластера.

Примеры для Linux проверялись в следующем окружении:

Виртуальная машина в Yandex Cloud с Ubuntu 20.04 LTS.
Bash: 5.0.16.
Python: 3.8.2; pip3: 20.0.2.
PHP: 7.4.3.
OpenJDK: 11.0.8; Maven: 3.6.3.
Node.JS: 10.19.0, npm: 6.14.4.
Go: 1.13.8.
Ruby: 2.7.0p0.
unixODBC: 2.3.6.

Примеры для Windows проверялись в следующем окружении:

Локальная машина с Windows 10 Pro build 19042.1052.
PowerShell: 5.1.19041.

Go

Перед подключением установите зависимости:

sudo apt update && sudo apt install --yes golang git

Подключение без SSL

Подключение с SSL

connect.go

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    const DB_HOST = "<FQDN_любого_хоста_ClickHouse®>"
    const DB_NAME = "<имя_БД>"
    const DB_USER = "<имя_пользователя_БД>"
    const DB_PASS = "<пароль_пользователя_БД>"

    conn := &http.Client{
        Transport: &http.Transport{},
    }

    req, _ := http.NewRequest("GET", fmt.Sprintf("http://%s:8123/", DB_HOST), nil)
    query := req.URL.Query()
    query.Add("database", DB_NAME)
    query.Add("query", "SELECT version()")

    req.URL.RawQuery = query.Encode()

    req.Header.Add("X-ClickHouse-User", DB_USER)
    req.Header.Add("X-ClickHouse-Key", DB_PASS)

    resp, err := conn.Do(req)
    if err != nil {
        panic(err)
    }

    defer resp.Body.Close()

    data, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(data))
}

connect.go

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
    "crypto/x509"
    "crypto/tls"
)

func main() {

    const DB_HOST = "<FQDN_любого_хоста_ClickHouse®>"
    const DB_NAME = "<имя_БД>"
    const DB_USER = "<имя_пользователя_БД>"
    const DB_PASS = "<пароль_пользователя_БД>"

    const CACERT = "/usr/local/share/ca-certificates/Yandex/RootCA.crt"

    caCert, err := ioutil.ReadFile(CACERT)
    if err != nil {
        panic(err)
    }
    caCertPool := x509.NewCertPool()
    caCertPool.AppendCertsFromPEM(caCert)
    conn := &http.Client{
        Transport: &http.Transport{
        TLSClientConfig: &tls.Config{
            RootCAs: caCertPool,
        },
    },
    }

    req, _ := http.NewRequest("GET", fmt.Sprintf("https://%s:8443/", DB_HOST), nil)
    query := req.URL.Query()
    query.Add("database", DB_NAME)
    query.Add("query", "SELECT version()")

    req.URL.RawQuery = query.Encode()

    req.Header.Add("X-ClickHouse-User", DB_USER)
    req.Header.Add("X-ClickHouse-Key", DB_PASS)

    resp, err := conn.Do(req)
    if err != nil {
        panic(err)
    }

    defer resp.Body.Close()

    data, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(data))
}

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

go run connect.go

Java

Перед подключением:

Установите зависимости:

sudo apt update && sudo apt install --yes default-jdk maven

Создайте директорию для проекта Maven:

cd ~/ && mkdir --parents project/src/java/com/example && cd project/

Создайте конфигурационный файл для Maven:

pom.xml

<?xml version="1.0" encoding="utf-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>app</artifactId>
  <packaging>jar</packaging>
  <version>0.1.0</version>
  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.clickhouse</groupId>
      <artifactId>clickhouse-jdbc</artifactId>
      <version>0.2.4</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>1.7.30</version>
    </dependency>
  </dependencies>
  <build>
    <finalName>${project.artifactId}-${project.version}</finalName>
    <sourceDirectory>src</sourceDirectory>
    <resources>
      <resource>
        <directory>src</directory>
      </resource>
    </resources>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>attached</goal>
            </goals>
            <phase>package</phase>
            <configuration>
              <descriptorRefs>
                <descriptorRef>
                jar-with-dependencies</descriptorRef>
              </descriptorRefs>
              <archive>
                <manifest>
                  <mainClass>com.example.App</mainClass>
                </manifest>
              </archive>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.1.0</version>
        <configuration>
          <archive>
            <manifest>
              <mainClass>com.example.App</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Актуальные версии зависимостей для Maven:

Подключение без SSL

Подключение с SSL

src/java/com/example/App.java

package com.example;

import java.sql.*;

public class App {
  public static void main(String[] args) {
    String DB_HOST    = "<FQDN_любого_хоста_ClickHouse®>";
    String DB_NAME    = "<имя_БД>";
    String DB_USER    = "<имя_пользователя_БД>";
    String DB_PASS    = "<пароль_пользователя_БД>";

    String DB_URL = String.format("jdbc:clickhouse://%s:8123/%s", DB_HOST, DB_NAME);

    try {
      Class.forName("com.clickhouse.jdbc.ClickHouseDriver");

      Connection conn = DriverManager.getConnection(DB_URL, DB_USER, DB_PASS);
      ResultSet rs = conn.createStatement().executeQuery("SELECT version()");
      if(rs.next()) {System.out.println(rs.getString(1));}

      conn.close();
    }
    catch(Exception ex) {ex.printStackTrace();}
  }
}

src/java/com/example/App.java

package com.example;

import java.sql.*;

public class App {
  public static void main(String[] args) {
    String DB_HOST    = "<FQDN_любого_хоста_ClickHouse®>";
    String DB_NAME    = "<имя_БД>";
    String DB_USER    = "<имя_пользователя_БД>";
    String DB_PASS    = "<пароль_пользователя_БД>";

    String CACERT     = "/usr/local/share/ca-certificates/Yandex/RootCA.crt";

    String DB_URL = String.format("jdbc:clickhouse://%s:8443/%s?ssl=1&sslmode=strict&sslrootcert=%s", DB_HOST, DB_NAME, CACERT);

    try {
      Class.forName("com.clickhouse.jdbc.ClickHouseDriver");
      Connection conn = DriverManager.getConnection(DB_URL, DB_USER, DB_PASS);
      ResultSet rs = conn.createStatement().executeQuery("SELECT version()");
      if(rs.next()) {System.out.println(rs.getString(1));}

      conn.close();
    }
    catch(Exception ex) {ex.printStackTrace();}
  }
}

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

mvn clean package && \
java -jar target/app-0.1.0-jar-with-dependencies.jar

Node.js

Перед подключением установите зависимости:

sudo apt update && sudo apt install --yes nodejs npm && \
npm install querystring

Подключение без SSL

Подключение с SSL

app.js

"use strict"
const http = require('http');
const querystring = require('querystring');
const fs = require('fs');

const DB_HOST = "<FQDN_любого_хоста_ClickHouse®>";
const DB_NAME = "<имя_БД>";
const DB_USER = "<имя_пользователя_БД>";
const DB_PASS = "<пароль_пользователя_БД>";

const options = {
    'method': 'GET',
    'path': '/?' + querystring.stringify({
        'database': DB_NAME,
        'query': 'SELECT version()',
    }),
    'port': 8123,
    'hostname': DB_HOST,
    'headers': {
        'X-ClickHouse-User': DB_USER,
        'X-ClickHouse-Key': DB_PASS,
    },
};

const rs = http.request(options, (res) => {
    res.setEncoding('utf8');
    res.on('data', (chunk) => {
        console.log(chunk);
    });
});

rs.end();

app.js

"use strict"
const https = require('https');
const querystring = require('querystring');
const fs = require('fs');

const DB_HOST = "<FQDN_любого_хоста_ClickHouse®>";
const DB_NAME = "<имя_БД>";
const DB_USER = "<имя_пользователя_БД>";
const DB_PASS = "<пароль_пользователя_БД>";

const CACERT = "/usr/local/share/ca-certificates/Yandex/RootCA.crt";

const options = {
    'method': 'GET',
    'ca': fs.readFileSync(CACERT),
    'path': '/?' + querystring.stringify({
        'database': DB_NAME,
        'query': 'SELECT version()',
    }),
    'port': 8443,
    'hostname': DB_HOST,
    'headers': {
        'X-ClickHouse-User': DB_USER,
        'X-ClickHouse-Key': DB_PASS,
    },
};

const rs = https.request(options, (res) => {
    res.setEncoding('utf8');
    res.on('data', (chunk) => {
        console.log(chunk);
    });
});

rs.end();

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

node app.js

ODBC

Способ настройки различается для Linux и Windows.

Linux

Перед подключением:

Установите зависимости:

sudo apt update && sudo apt install --yes git unixodbc build-essential cmake \
libpoco-dev libssl-dev libicu-dev unixodbc-dev && \
cd ~/ && git clone https://github.com/ClickHouse/clickhouse-odbc.git && \
cd clickhouse-odbc/ && git submodule update --init

Соберите драйвер из исходных файлов:

cd ~/clickhouse-odbc/ && mkdir build && cd build && \
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .. && \
cmake --build . --config RelWithDebInfo

После завершения процесса сборки скопируйте файлы драйвера в директорию /usr/local/lib64/:
```
sudo mkdir --parents /usr/local/lib64 && sudo cp driver/*.so /usr/local/lib64/
```

Зарегистрируйте драйвер ClickHouse® ODBC, добавив следующие строки в файл odbcinst.ini (файл-пример):

/etc/odbcinst.ini

[ODBC Drivers]
ClickHouse ODBC Driver (ANSI)    = Installed
ClickHouse ODBC Driver (Unicode) = Installed

[ClickHouse ODBC Driver (ANSI)]
Description = ODBC Driver (ANSI) for ClickHouse
Driver      = /usr/local/lib64/libclickhouseodbc.so
Setup       = /usr/local/lib64/libclickhouseodbc.so
UsageCount  = 1

[ClickHouse ODBC Driver (Unicode)]
Description = ODBC Driver (Unicode) for ClickHouse
Driver      = /usr/local/lib64/libclickhouseodbcw.so
Setup       = /usr/local/lib64/libclickhouseodbcw.so
UsageCount  = 1

Подключение без SSL

Подключение с SSL

/etc/odbc.ini

[ClickHouse]
Driver = ClickHouse ODBC Driver (Unicode)
Server = <FQDN_любого_хоста_ClickHouse®>
Database = <имя_БД>
UID = <имя_пользователя_БД>
PWD = <пароль_пользователя_БД>
Port = 8123
Proto = http

/etc/odbc.ini

[ClickHouse]
Driver = ClickHouse ODBC Driver (Unicode)
Server = <FQDN_любого_хоста_ClickHouse®>
Database = <имя_БД>
UID = <имя_пользователя_БД>
PWD = <пароль_пользователя_БД>
Port = 8443
Proto = https
SSLMode = allow
CertificateFile = /usr/local/share/ca-certificates/Yandex/RootCA.crt
CALocation = /etc/ssl/certs/ca-certificates.crt

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

isql -v ClickHouse

После подключения к СУБД выполните команду SELECT version();.

Windows

Установите драйвер clickhouse-odbc подходящей разрядности. Например, если вы используете 32-разрядное приложение для подключения через ODBC, установите драйвер такой же разрядности.
Запустите приложение Администратор источника данных ODBC.
На вкладке Пользовательские DSN нажмите кнопку Добавить...
Выберите драйвер ClickHouse® с подходящей кодировкой и нажмите кнопку Готово.
Укажите параметры подключения к кластеру ClickHouse®:
Подключение без SSL

Подключение с SSL
- Name — имя подключения.
- Host — FQDN любого хоста ClickHouse®.
- Port — 8443.
- Database — имя БД.
- User — имя пользователя БД.
- Password — пароль пользователя БД.
- Name — имя подключения.
- Host — FQDN любого хоста ClickHouse®.
- Port — 8443.
- Database — имя БД.
- SSLMode — allow.
- User — имя пользователя БД.
- Password — пароль пользователя БД.
Нажмите кнопку Ok.
Подключитесь к кластеру ClickHouse® с помощью ODBC, например через приложение Microsoft Excel.

PHP

Перед подключением:

Установите зависимости:

sudo apt update && sudo apt install --yes php

Убедитесь, что для параметра allow_url_fopen задано значение On в настройках PHP:
```
cat /etc/php/7.4/apache2/php.ini | grep "allow_url_fopen"
```
Если это не так, то установите нужное значение и перезапустите Apache:
```
sudo sed -i 's/\(^allow_url_fopen = \).*/\1On/' /etc/php/7.4/apache2/php.ini && \
sudo systemctl restart apache2
```

Подключение без SSL

Подключение с SSL

connect.php

<?php
    $host = '<FQDN_любого_хоста_ClickHouse®>';
    $db = '<имя_БД>';
    $query = 'SELECT version()';

    $auth = [
        'X-ClickHouse-User: <имя_пользователя_БД>',
        'X-ClickHouse-Key: <пароль_пользователя_БД>',
    ];

    $context = stream_context_create([
        'http' => [
            'method' => 'GET',
            'protocol_version' => 1.1,
            'header' => $auth
        ]
    ]);

    $url = sprintf('http://%s:8123/?database=%s&query=%s', $host, $db, urlencode($query));

    $rs = file_get_contents($url, false, $context);
    print_r($rs);
?>

connect.php

<?php
    $host = '<FQDN_любого_хоста_ClickHouse®>';
    $db = '<имя_БД>';
    $query = 'SELECT version()';

    $auth = [
        'X-ClickHouse-User: <имя_пользователя_БД>',
        'X-ClickHouse-Key: <пароль_пользователя_БД>',
    ];

    $ssl = [
        'cafile' => '/usr/local/share/ca-certificates/Yandex/RootCA.crt',
        'verify_peer' => true,
    ];

    $context = stream_context_create([
        'http' => [
            'method' => 'GET',
            'protocol_version' => 1.1,
            'header' => $auth
        ],
        'ssl' => $ssl
    ]);

    $url = sprintf('https://%s:8443/?database=%s&query=%s', $host, $db, urlencode($query));

    $rs = file_get_contents($url, false, $context);
    print_r($rs);
?>

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

php connect.php

Python (clickhouse-driver)

Перед подключением установите зависимости:

sudo apt update && sudo apt install --yes python3 python3-pip && \
pip3 install clickhouse-driver

Подключение без SSL

Подключение с SSL

connect.py

from clickhouse_driver import Client

client = Client(host='<FQDN_любого_хоста_ClickHouse®>',
                user='<имя_пользователя_БД>',
                password='<пароль_пользователя_БД>',
                port=9000)

print(client.execute('SELECT version()'))

connect.py

from clickhouse_driver import Client

client = Client(host='<FQDN_любого_хоста_ClickHouse®>',
                user='<имя_пользователя_БД>',
                password='<пароль_пользователя_БД>',
                port=9440,
                secure=True,
                verify=True,
                ca_certs='/usr/local/share/ca-certificates/Yandex/RootCA.crt')

print(client.execute('SELECT version()'))

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

python3 connect.py

Python (requests)

Перед подключением установите зависимости:

sudo apt update && sudo apt install --yes python3 python3-pip && \
pip3 install requests

Подключение без SSL

Подключение с SSL

connect.py

import requests

response = requests.get(
    'http://{0}:8123'.format('<FQDN_любого_хоста_ClickHouse®>'),
    params={
        'query': 'SELECT version()',
    },
    headers={
        'X-ClickHouse-User': '<имя_пользователя_БД>',
        'X-ClickHouse-Key': '<пароль_пользователя_БД>',
    })

response.raise_for_status()
print(response.text)

connect.py

import requests

response = requests.get(
    'https://{0}:8443'.format('<FQDN_любого_хоста_ClickHouse®>'),
    params={
        'query': 'SELECT version()',
    },
    verify='/usr/local/share/ca-certificates/Yandex/RootCA.crt',
    headers={
        'X-ClickHouse-User': '<имя_пользователя_БД>',
        'X-ClickHouse-Key': '<пароль_пользователя_БД>',
    })

response.raise_for_status()
print(response.text)

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

python3 connect.py

Ruby

Перед подключением установите зависимости:

sudo apt update && sudo apt install --yes ruby

Подключение без SSL

Подключение с SSL

connect.rb

require "net/http"
require "uri"

DB_HOST = "<FQDN_любого_хоста_ClickHouse®>"
DB_NAME = "<имя_БД>"
DB_USER = "<имя_пользователя_БД>"
DB_PASS = "<пароль_пользователя_БД>"

QUERYSTRING = { :database => DB_NAME, :query => "SELECT version()" }

uri = URI("http://" + DB_HOST + "/")
uri.port = 8123
uri.query = URI.encode_www_form(QUERYSTRING)

req = Net::HTTP::Get.new(uri)
req.add_field("X-ClickHouse-User", DB_USER)
req.add_field("X-ClickHouse-Key", DB_PASS)

conn = Net::HTTP.new(uri.host, uri.port)

rs = conn.request(req)
puts rs.body

connect.rb

require "net/http"
require "openssl"
require "uri"

DB_HOST = "<FQDN_любого_хоста_ClickHouse®>"
DB_NAME = "<имя_БД>"
DB_USER = "<имя_пользователя_БД>"
DB_PASS = "<пароль_пользователя_БД>"

QUERYSTRING = { :database => DB_NAME, :query => "SELECT version()" }

uri = URI("https://" + DB_HOST + "/")
uri.port = 8443
uri.query = URI.encode_www_form(QUERYSTRING)

req = Net::HTTP::Get.new(uri)
req.add_field("X-ClickHouse-User", DB_USER)
req.add_field("X-ClickHouse-Key", DB_PASS)

conn = Net::HTTP.new(uri.host, uri.port)
conn.ca_file = "/usr/local/share/ca-certificates/Yandex/RootCA.crt"
conn.use_ssl = true
conn.verify_mode = OpenSSL::SSL::VERIFY_PEER

rs = conn.request(req)
puts rs.body

О том, как получить FQDN хоста, см. инструкцию.

Подключение:

ruby connect.rb

ClickHouse® является зарегистрированным товарным знаком ClickHouse, Inc.

Примеры кода для подключения к кластеру ClickHouse®

GoGo

JavaJava

Node.jsNode.js

ODBCODBC

LinuxLinux

WindowsWindows

PHPPHP

Python (clickhouse-driver)Python (clickhouse-driver)

Python (requests)Python (requests)

RubyRuby

Была ли статья полезна?

Go

Java

Node.js

ODBC

Linux

Windows

PHP

Python (clickhouse-driver)

Python (requests)

Ruby