ShardingSphere-JDBC 整合 ClickHouse 完全指南-优快云博客

ShardingSphere-JDBC 整合 ClickHouse 完全指南

shardingsphere 项目地址: https://gitcode.com/gh_mirrors/shard/shardingsphere

背景介绍

ShardingSphere-JDBC 作为一款强大的分布式数据库中间件，默认情况下并不直接支持 ClickHouse 的 JDBC 驱动。本文将详细介绍如何在 ShardingSphere-JDBC 项目中集成 ClickHouse 数据库，并解决实际使用中可能遇到的各种问题。

环境准备

依赖配置

要在项目中使用 ClickHouse 作为 ShardingSphere-JDBC 的数据节点，需要在项目中添加以下 Maven 依赖：

<dependencies>
    <!-- ShardingSphere-JDBC 核心依赖 -->
    <dependency>
        <groupId>org.apache.shardingsphere</groupId>
        <artifactId>shardingsphere-jdbc</artifactId>
        <version>${shardingsphere.version}</version>
    </dependency>
    
    <!-- ClickHouse SQL 解析器 -->
    <dependency>
        <groupId>org.apache.shardingsphere</groupId>
        <artifactId>shardingsphere-parser-sql-clickhouse</artifactId>
        <version>${shardingsphere.version}</version>
    </dependency>
    
    <!-- ClickHouse JDBC 驱动 -->
    <dependency>
        <groupId>com.clickhouse</groupId>
        <artifactId>clickhouse-jdbc</artifactId>
        <classifier>http</classifier>
        <version>0.6.3</version>
    </dependency>
</dependencies>

详细配置步骤

1. 启动 ClickHouse 服务

使用 Docker 快速启动 ClickHouse 服务是最便捷的方式。创建如下 docker-compose.yml 文件：

version: '3'
services:
  clickhouse-server:
    image: clickhouse/clickhouse-server:25.4.5.24
    ports:
      - "8123:8123"
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_PASSWORD=

执行 docker-compose up -d 命令即可启动服务。

2. 创建业务数据库和表

建议使用 DBeaver 等数据库管理工具连接 ClickHouse 并创建业务表结构：

-- 创建数据库
CREATE DATABASE IF NOT EXISTS demo_ds_0;
CREATE DATABASE IF NOT EXISTS demo_ds_1;
CREATE DATABASE IF NOT EXISTS demo_ds_2;

-- 在每个数据库中创建订单表
CREATE TABLE IF NOT EXISTS t_order (
    order_id   Int64 NOT NULL,
    order_type Int32,
    user_id    Int32 NOT NULL,
    address_id Int64 NOT NULL,
    status     VARCHAR(50)
) ENGINE = MergeTree
    PRIMARY KEY (order_id)
    ORDER BY (order_id);

3. 配置 ShardingSphere 数据源

在项目 resources 目录下创建 demo.yaml 配置文件：

dataSources:
  ds_0:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.clickhouse.jdbc.ClickHouseDriver
    jdbcUrl: jdbc:ch://localhost:8123/demo_ds_0
    username: default
    password: ""
  ds_1:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.clickhouse.jdbc.ClickHouseDriver
    jdbcUrl: jdbc:ch://localhost:8123/demo_ds_1
    username: default
    password: ""
  ds_2:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.clickhouse.jdbc.ClickHouseDriver
    jdbcUrl: jdbc:ch://localhost:8123/demo_ds_2
    username: default
    password: ""

rules:
- !SHARDING
  tables:
    t_order:
      actualDataNodes: ds_${0..2}.t_order
      keyGenerateStrategy:
        column: order_id
        keyGeneratorName: snowflake
  defaultDatabaseStrategy:
    standard:
      shardingColumn: user_id
      shardingAlgorithmName: inline
  shardingAlgorithms:
    inline:
      type: INLINE
      props:
        algorithm-expression: ds_${user_id % 2}
  keyGenerators:
    snowflake:
      type: SNOWFLAKE

代码集成示例

基本操作示例

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import java.sql.*;

public class ShardingSphereClickHouseExample {
    
    public static void main(String[] args) {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:shardingsphere:classpath:demo.yaml");
        config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
        
        try (HikariDataSource dataSource = new HikariDataSource(config);
             Connection connection = dataSource.getConnection();
             Statement statement = connection.createStatement()) {
            
            // 插入数据
            statement.execute("INSERT INTO t_order (user_id, order_type, address_id, status) " +
                             "VALUES (1, 1, 1, 'INSERT_TEST')");
            
            // 查询数据
            ResultSet resultSet = statement.executeQuery("SELECT * FROM t_order");
            while (resultSet.next()) {
                System.out.println("Order ID: " + resultSet.getLong("order_id"));
            }
            
            // 删除数据
            statement.execute("ALTER TABLE t_order DELETE WHERE user_id=1");
            
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

使用限制与解决方案

1. SQL 语句限制

目前 ShardingSphere-JDBC 对 ClickHouse 的以下语句支持有限：

CREATE TABLE 表创建语句
TRUNCATE TABLE 清空表语句
DROP TABLE 删除表语句

解决方案：这些操作建议直接通过 ClickHouse 原生客户端执行。

2. 主键生成限制

ClickHouse 原生支持 UUID 类型作为主键，而 ShardingSphere 的雪花算法生成的是 Long 类型数值。使用时需要注意：

确保表定义中的主键字段类型为 Int64 或 UInt64
在 Java 代码中获取生成的主键时，需要特殊处理：

try (PreparedStatement ps = connection.prepareStatement(
        "INSERT INTO t_order (user_id, order_type, address_id, status) VALUES (?, ?, ?, ?)",
        Statement.NO_GENERATED_KEYS)) {
    
    ps.setInt(1, 1);
    ps.setInt(2, 1);
    ps.setLong(3, 1);
    ps.setString(4, "INSERT_TEST");
    ps.executeUpdate();
    
    try (ResultSet rs = ps.getGeneratedKeys()) {
        if (rs.next()) {
            long generatedId = rs.getLong(1);
            System.out.println("Generated ID: " + generatedId);
        }
    }
}