ClickHouse Native JDBC 使用教程

项目介绍

ClickHouse Native JDBC 是一个基于 ClickHouse 原生 TCP 协议实现的 JDBC 驱动。该项目旨在提供一个高效、稳定的 ClickHouse 数据库连接方式，支持与 Apache Spark 等大数据处理框架的集成。ClickHouse Native JDBC 项目遵循 Apache License 2.0 开源协议，由社区维护。

项目快速启动

环境要求

• Java 8 或更高版本
• Scala 2.11/2.12 或更高版本（如果使用 Spark 集成）
• Spark 2.4 或更高版本（可选）

安装

Gradle 安装

推荐使用 shaded 版本：

// (recommended) shaded version available since 2.3-stable
compile "com.github.housepower:clickhouse-native-jdbc-shaded:$[clickhouse_native_jdbc_version]"

// normal version
compile "com.github.housepower:clickhouse-native-jdbc:$[clickhouse_native_jdbc_version]"

Maven 安装

推荐使用 shaded 版本：

<!-- (recommended) shaded version available since 2.3-stable -->
<dependency>
    <groupId>com.github.housepower</groupId>
    <artifactId>clickhouse-native-jdbc-shaded</artifactId>
    <version>$[clickhouse-native-jdbc version]</version>
</dependency>

<!-- normal version -->
<dependency>
    <groupId>com.github.housepower</groupId>
    <artifactId>clickhouse-native-jdbc</artifactId>
    <version>$[clickhouse-native-jdbc version]</version>
</dependency>

示例代码

以下是一个简单的示例代码，展示如何使用 ClickHouse Native JDBC 连接到 ClickHouse 数据库并执行查询：

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

public class ClickHouseExample {
    public static void main(String[] args) {
        try {
            // 加载驱动
            Class.forName("com.github.housepower.jdbc.ClickHouseDriver");

            // 建立连接
            String url = "jdbc:clickhouse://localhost:8123";
            Connection connection = DriverManager.getConnection(url);

            // 创建语句
            Statement statement = connection.createStatement();

            // 执行查询
            ResultSet resultSet = statement.executeQuery("SELECT 1");

            // 处理结果
            while (resultSet.next()) {
                System.out.println(resultSet.getInt(1));
            }

            // 关闭连接
            resultSet.close();
            statement.close();
            connection.close();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

应用案例和最佳实践

集成 Apache Spark

ClickHouse Native JDBC 可以与 Apache Spark 集成，用于大规模数据处理。以下是一个简单的集成示例：

环境要求

• Java 8 或更高版本
• Scala 2.11/2.12 或更高版本
• Spark 2.4 或更高版本

集成步骤

1. 添加依赖：

// available since 2.4.0
compile "com.github.housepower:clickhouse-integration-spark_2.11:$[clickhouse_native_jdbc_version]"

2. 编写 Spark 代码：

import org.apache.spark.sql.SparkSession

object ClickHouseSparkExample {
    def main(args: Array[String]): Unit = {
        val spark = SparkSession.builder()
            .appName("ClickHouseSparkExample")
            .getOrCreate()

        val url = "jdbc:clickhouse://localhost:8123"
        val df = spark.read.format("jdbc")
            .option("url", url)
            .option("dbtable", "default.table_name")
            .load()

        df.show()

        spark.stop()
    }
}

最佳实践

• 使用 shaded 版本以避免依赖冲突。
• 在高并发场景下，合理配置连接池参数以提高性能。