【Clickhouse从入门到精通】第10篇：ClickHouse客户端访问与连接详解

上一篇【第09篇】ClickHouse安装部署全攻略——从环境准备到服务启动
下一篇【第11篇】ClickHouse内置工具实战——clickhouse-local与clickhouse-benchmark

摘要

ClickHouse支持多种客户端访问方式，包括原生的CLI命令行工具、JDBC/ODBC驱动、多语言的Driver库以及HTTP接口。本文全面介绍了ClickHouse的各种客户端连接方式，详细讲解了每种方式的使用方法、参数配置、代码示例和适用场景，帮助开发者根据不同的业务需求选择最适合的连接方式。同时，文章还介绍了MySQL协议兼容接口和第三方BI工具的连接配置，为构建完整的ClickHouse数据应用提供全面指导。

关键词：ClickHouse客户端、JDBC连接、Python Driver、HTTP接口、MySQL协议、BI工具连接

1 引言

ClickHouse作为分析型数据库，需要从多种渠道接收数据查询和写入请求。为了满足不同开发者的需求，ClickHouse提供了丰富的客户端访问方式。既有适合DBA操作的高效CLI工具，也有适合应用集成的JDBC驱动和HTTP接口，还有兼容MySQL协议的特殊接口。本文将系统性地介绍这些访问方式的特点、使用方法和最佳实践。

2 CLI命令行客户端

2.1 clickhouse-client基础用法

clickhouse-client是ClickHouse官方提供的命令行客户端工具，是DBA日常管理最常用的工具。

基本连接语法：

# 基本连接（使用默认参数）
clickhouse-client

# 指定主机和端口
clickhouse-client --host 192.168.1.100 --port 9000

# 指定用户和密码
clickhouse-client --user default --password my_password

# 连接指定数据库
clickhouse-client --database mydb

# 组合参数
clickhouse-client -h 192.168.1.100 -p 9000 -u admin --password secret -d mydb

常用参数说明：

2.2 交互式模式与批处理模式

clickhouse-client支持两种工作模式：交互式模式和批处理模式。

交互式模式：

# 进入交互式界面
clickhouse-client

# 界面示例：
# ClickHouse client version 22.8.2.2.
# Connecting to localhost:9000 as user default.
# Connected to ClickHouse server version 22.8.2.2.
#
# smiley-clickhouse :)

# 执行查询
smile:) SELECT 1
# ┌───1─┐
# │  1  │
# └───┘

# 多行查询
smile:) SELECT
smile:)     number,
smile:)     number * 2 AS doubled
smile:) FROM system.numbers
smile:) LIMIT 5
# ┌─number─┬─doubled─┐
# │      0 │       0 │
# │      1 │       2 │
# │      2 │       4 │
# │      3 │       6 │
# │      4 │       8 │
# └────────┴─────────┘

# 退出
smile:) EXIT
# 或 Ctrl+D

批处理模式（单行查询）：

# 执行单个查询并退出
clickhouse-client -q "SELECT 1"

# 执行查询并显示时间
clickhouse-client -t -q "SELECT count() FROM system.numbers_mt(10000000)"

# 查询结果
# 10000000
# Elapsed: 0.052 sec.

批处理模式（多行查询）：

# 使用分号分隔多个查询
clickhouse-client -q "SELECT 1; SELECT 2; SELECT 3"

# 使用-multiquery参数
clickhouse-client --multiquery -q "
CREATE TABLE IF NOT EXISTS test (
    id UInt32,
    name String,
    created_at DateTime
) ENGINE = MergeTree()
ORDER BY id;

INSERT INTO test VALUES (1, 'Alice', now());

SELECT * FROM test;
"

从文件执行查询：

# 创建查询文件
cat > /tmp/query.sql << 'EOF'
-- 这是一个测试查询文件
SELECT
    database,
    table,
    formatReadableQuantity(rows) AS rows,
    formatReadableQuantity(bytes) AS bytes
FROM system.tables
WHERE database = 'system'
ORDER BY rows DESC
LIMIT 10;
EOF

# 执行文件中的查询
clickhouse-client --queries-file=/tmp/query.sql

2.3 格式化输出

clickhouse-client支持多种输出格式，通过–format参数指定。

常用输出格式：

# TabSeparated格式（默认）
clickhouse-client -q "SELECT 1 AS a, 2 AS b" --format TabSeparated
# 输出: 1	2

# TabSeparatedRaw（无引号转义）
clickhouse-client -q "SELECT 'hello' AS a" --format TabSeparatedRaw

# CSV格式
clickhouse-client -q "SELECT 1, 'hello'" --format CSV
# 输出: 1,"hello"

# JSON格式
clickhouse-client -q "SELECT 1 AS a, 2 AS b" --format JSON
# 输出:
# {
   
   
#     "meta":
#     [
#         {"name":"a","type":"UInt8"},
#         {"name":"b","type":"UInt8"}
#     ],
#     "data":
#     [
#         {"a":1,"b":2}
#     ],
#     "rows":1,
#     "statistics":{"elapsed":0.0001,"rows_read":1,"bytes_read":1}
# }

# JSONCompact
clickhouse-client -q "SELECT 1 AS a, 2 AS b" --format JSONCompact
# 输出: [[1,2]]

# JSONEachRow（流式JSON）
clickhouse-client -q "SELECT 1 AS id, 'test' AS name" --format JSONEachRow
# 输出: {"id":1,"name":"test"}

# Pretty格式（美化输出）
clickhouse-client -q "SELECT * FROM system.numbers LIMIT 3" --format PrettyCompact
# ┌─number─┐
# │      0 │
# │      1 │
# │      2 │
# └───┘

# PrettyJSON
clickhouse-client -q "SELECT arrayMap(x -> x*2, range(3))" --format PrettyJSONCompact

格式对比表：

2.4 客户端配置文件

可以通过配置文件为clickhouse-client设置默认参数。

配置文件位置：

• ~/.clickhouse-client/config.xml（用户级）
• /etc/clickhouse-client/config.xml（系统级）

配置文件示例：

<?xml version="1.0"?>
<clickhouse-client>
    <!-- 默认连接参数 -->
    <host>127.0.0.1</host>
    <port>9000</port>
    <user>default</user>
    <password></password>
    <database>default</database>

    <!-- 客户端设置 -->
    <secure>false</secure>
    <compression>false</compression>

    <!-- 连接超时（秒） -->
    <connect_timeout>10</connect_timeout>

    <!-- 查询超时（秒） -->
    <query_timeout>300</query_timeout>

    <!-- 交互式提示符 -->
    <prompt>clickhouse:{database}></prompt>

    <!-- 日志配置 -->
    <log_level>information</log_level>

    <!-- 输出格式 -->
    <default_format>TabSeparated</default_format>
</clickhouse-client>

高级提示符配置：

<!-- 在config.xml中 -->
<prompt_by_database>
    <database default="default">
        <text>my_database({DATABASE})> </text>
    </database>
    <database test>
        <text>TEST({DATABASE})> </text>
        <highlight_syntax>1</highlight_syntax>
    </database>
</prompt_by_database>

3 JDBC驱动连接

3.1 JDBC驱动获取

ClickHouse提供官方JDBC驱动，可以通过Maven或手动下载方式获取。

Maven依赖配置：

<dependencies>
    <dependency>
        <groupId>com.clickhouse</groupId>
        <artifactId>clickhouse-jdbc</artifactId>
        <version>0.4.6</version>
    </dependency>
</dependencies>

Gradle依赖配置：

implementation 'com.clickhouse:clickhouse-jdbc:0.4.6'

手动下载：

# 下载JDBC驱动
curl -O https://github.com/ClickHouse/clickhouse-jdbc/releases/download/0.4.6/clickhouse-jdbc-0.4.6-all.jar

# 或者使用Maven下载
mvn dependency:get -Dartifact=com.clickhouse:clickhouse-jdbc:0.4.6

JDBC驱动版本对比：

3.2 JDBC连接与代码示例

JDBC URL格式：

jdbc:clickhouse://<host>:<port>/<database>?<params>

基础连接代码：

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

public class ClickHouseJDBCExample {
   
   
    public static void main(String[] args) {
   
   
        // JDBC URL配置
        String jdbcUrl = "jdbc:clickhouse://127.0.0.1:8123/default";

        // 连接属性
        Properties props = new Properties();
        props.setProperty("user", "default");
        props.setProperty("password", "");
        props.setProperty("connect_timeout", "10000");
        props.setProperty("socket_timeout", "30000");
        props.setProperty("compress", "1");  // 启用压缩
        props.setProperty("ssl", "false");   // SSL连接

        try {
   
   
            // 加载驱动（新版DriverManager自动加载）
            Class.forName("com.clickhouse.jdbc.ClickHouseDriver");

            // 建立连接
            Connection conn = DriverManager.getConnection(jdbcUrl, props);

            // 创建语句
            Statement stmt = conn.createStatement();

            // 执行查询
            ResultSet rs = stmt.executeQuery("SELECT 1 AS a, 'Hello' AS b");
            while (rs.next()) {
   
   
                System.out.println("a: " + rs.getInt("a"));
                System.out.println("b: " + rs.getString("b"));
            }

            // 关闭连接
            rs.close();
            stmt.close();
            conn.close();

        } catch (Exception e) {
   
   
            e.printStackTrace();
        }
    }
}

PreparedStatement使用：

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.Timestamp;

public class ClickHousePreparedStatement {
   
   
    public static void main(String[] args) {
   
   
        String jdbcUrl = "jdbc:clickhouse://127.0.0.1:8123/testdb";
        Properties props = new Properties();
        props.setProperty("user", "default");

        try (Connection conn = DriverManager.getConnection(jdbcUrl, props)) {
   
   

            // 插入数据（使用PreparedStatement）
            String insertSQL = "INSERT INTO user_events (user_id, event_type, event_time, amount) VALUES (?, ?, ?, ?)";
            try (PreparedStatement pstmt = conn.prepareStatement(insertSQL)) {
   
   
                for (int i = 1; i <= 100; i++) {
   
   
                    pstmt.setInt(1, i);
                    pstmt.setString(2, "click");
                    pstmt.setTimestamp(3, new Timestamp(System.currentTimeMillis()));
                    pstmt.setDouble(4, Math.random() * 100);
                    pstmt.addBatch();
                }
                pstmt.executeBatch();
            }

            // 查询数据（使用PreparedStatement防注入）
            String selectSQL = "SELECT * FROM user_events WHERE user_id = ? AND amount > ?";
            try (PreparedStatement pstmt = conn.prepareStatement(selectSQL)) {
   
   
                pstmt.setInt(1, 1);
                pstmt.setDouble(2, 50.0);

                try (ResultSet rs = pstmt.executeQuery()) {
   
   
                    while (rs.next()) {
   
   
                        System.out.printf("User: %d, Event: %s, Amount: %.2f%n",
                            rs.getInt("user_id"),
                            rs.getString("event_type"),
                            rs.getDouble("amount"));
                    }
                }
            }

        } catch (Exception e) {
   
   
            e.printStackTrace();
        }
    }
}

连接池配置（HikariCP示例）：

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

public class ClickHouseConnectionPool {
   
   
    public static HikariDataSource createDataSource() {
   
   
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:clickhouse://127.0.0.1:8123/default");
        config.setUsername("default");
        config.setPassword("");

        // 连接池大小
        config.setMaximumPoolSize(20);
        config.setMinimumIdle(5);

        // 超时设置
        config.setConnectionTimeout(30000);
        config.setIdleTimeout(600000);
        config.setMaxLifetime(1800000);

        // 连接测试
        config.setConnectionTestQuery("SELECT 1");

        return new HikariDataSource(config);
    }
}

4 Python连接

4.1 clickhouse-driver安装与使用

clickhouse-driver是Python中使用最广泛的ClickHouse客户端库。

安装：

pip install clickhouse-driver

基础使用：

from clickhouse_driver import Client

# 创建客户端连接
client = Client(
    host='127.0.0.1',
    port=9000,
    database='default',
    user='default',
    password='',
    connect_timeout=10,