跳到主要内容
版本：1.0.x

连接客户端

文档类型：教程型

文档结构：教程目的，前置准备，分步骤讲解原理 & 示例，相关文档推荐；

内容提要：

  1. ByConity 提供哪些客户端或者驱动方式进行与其他系统的交互
  2. 如何在部署好集群后，下载、启动这些客户端

命令行客户端（CLI）​

Docker Client​

如果你已经安装了 Docker，那么只需下面命令就可以直接建立 ByConity 连接：

docker run -it yandex/clickhouse-client --host 127.0.0.1 --port 9000 --user default --password xxxx

下面各项均为可选项，视情况而定：

  • --host xxx 主机 IP 或域名
  • --port 9000 tcp 端口，默认为 9000
  • --user default 用户名
  • --password xxxx 密码

Clickhouse Client​

Byconity 兼容 ClickHouse 开源社区所提供的客户端。

curl -O 'https://builds.clickhouse.com/master/macos/clickhouse' \
&& chmod a+x ./clickhouse

sudo mv ./clickhouse /usr/local/bin/

  • 建立连接：
clickhouse client --host 127.0.0.1 --password xxxx

  • clickhouse client --help 可以查看可选参数，这里的参数和上面

docker run -it yandex/clickhouse-client ... 后面的参数名是一致的

各语言驱动器（Driver）​

Clickhouse 官方提供的各种语言的开源 Driver 可直接用于 Byconity 连接。

Python​

clickhouse-connect​

  • clickhouse-connect 只支持 python3
  • 安装：pip3 install clickhouse-connect
  • 示例代码：
import clickhouse_connect

# connect
client = clickhouse_connect.get_client(host='localhost', username='default', password='xxxx')

# query
query_result = client.query('SHOW DATABASES;')
print (query_result.result_set)

clickhouse-driver​

  • Python3 安装：pip3 install clickhouse-driver
  • Python2 安装：pip install clickhouse-driver
  • 示例代码：
from clickhouse_driver import Client
from clickhouse_driver import connect

# connect
client = Client(host='localhost',port =9000, user='default', password='xxxx')

# query
query_result = client.execute('SHOW DATABASES;')
print (query_result)

Go​

使用 clickhouse-go 连接​

  • clickhouse-go 相比后面的 ch-go 对 Go 的类型支持更友好，底层由 ch-go 实现，推荐使用。
  • 在项目中执行 go get ``github.com/ClickHouse/clickhouse-go/v2 安装
  • 示例代码：
package main

import (
        "context"
        "log"
        "net"
        "time"

        "github.com/ClickHouse/clickhouse-go/v2"
)

func main() {
        ctx := context.Background()

        // 配置连接参数
        conn, err := clickhouse.Open(&clickhouse.Options{
                Addr: string[]{"127.0.0.1"},
                Auth: clickhouse.Auth{
                        Database: "my_db",
                        Username: "default",
                        Password: "xxxx",
                },
                DialContext: func(ctx context.Context, addr string) (net.Conn, error) {
                        var d net.Dialer
                        return d.DialContext(ctx, "tcp", addr)
                },
                Settings: clickhouse.Settings{
                        "max_execution_time": 60,
                },
                DialTimeout:      time.Duration(10) * time.Second,
                MaxOpenConns:     5,
                MaxIdleConns:     5,
                ConnMaxLifetime:  time.Duration(10) * time.Minute,
                ConnOpenStrategy: clickhouse.ConnOpenInOrder,
        })
        if err != nil {
                log.Panic(err)
        }

        if err := conn.Ping(ctx); err != nil {
                log.Panic(err)
        }

        // 执行 SQL
        if err := conn.Exec(ctx, "SHOW DATABASES;"); err != nil {
                log.Panic(err)
        }
}

使用 ch-go 连接​

  • ch-go 对 Clickhouse 数据类型支持更好，性能稍高于 clickhouse-go。
  • 安装：go get ``github.com/ClickHouse/ch-go
  • 示例代码：
package main

import (
  "context"
  "fmt"

  "github.com/ClickHouse/ch-go"
  "github.com/ClickHouse/ch-go/proto"
)

func main() {
  ctx := context.Background()
  c, err := ch.Dial(ctx, ch.Options{Address: "localhost:9000"})
  if err != nil {
    panic(err)
  }
  var (
    numbers int
    data    proto.ColUInt64
  )
  if err := c.Do(ctx, ch.Query{
    Body: "SELECT number FROM system.numbers LIMIT 500000000",
    Result: proto.Results{
      {Name: "number", Data: &data},
    },
    // OnResult will be called on next received data block.
    OnResult: func(ctx context.Context, b proto.Block) error {
      numbers += len(data)
      return nil
    },
  }); err != nil {
    panic(err)
  }
  fmt.Println("numbers:", numbers)
}

Java​

用 clickhouse-jdbc 连接

  • 通过 maven 配置安装：
<dependency>
    <!-- please stop using ru.yandex.clickhouse as it's been deprecated -->
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.3.2-patch11</version>
    <!-- use uber jar with all dependencies included, change classifier to http for smaller jar -->
    <classifier>all</classifier>
    <exclusions>
        <exclusion>
            <groupId>*</groupId>
            <artifactId>*</artifactId>
        </exclusion>
    </exclusions>
</dependency>

  • 示例代码：
String url = "jdbc:ch://localhost:8123";
Properties properties = new Properties();
properties.setProperty("max_execution_time", "120");
ClickHouseDataSource dataSource = new ClickHouseDataSource(url, properties);
try (Connection conn = dataSource.getConnection("default", "password");
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("SHOW DATABASES;");
    while(rs.next()) {
        // ...
    }
}

HTTP​

ByConity 也提供 HTTP 连接方式，可以用 curl 或 postman 方式执行 SQL。curl 示例：

curl --location --request POST '127.0.0.1:8123/?max_execution_time=60&default_format=Native' \
--header 'Authorization: Basic xxx' \
--header 'Content-Type: text/plain' \
--data-raw 'SHOW DATABASES;'

  • 以 Basic Auth(用户名 + 密码)方式进行加密，加密结果为上面的 --header 'Authorization: Basic xxx'
  • 在 Body 中直接填写要执行的 SQL，对应上面的 --data-raw 'SHOW DATABASES;'
  • HTTP 接口默认端口号为 8123
  • 示例参数：
  • max_execution_time=60 指定查询最大等待时间(秒)
  • 默认情况下，返回的数据是 TabSeparated 格式的，default_format 可以指定 TabSeparated 之外的默认格式

参考文档​