Spark JDBC连接ClickHouse报NoClassDefFoundError错误排查

问题描述 #

尝试通过ClickHouse JDBC驱动建立Spark与ClickHouse的JDBC连接时，遇到以下错误：

Py4JJavaError: An error occurred while calling o101.load.
: java.lang.NoClassDefFoundError: Could not initialize class ru.yandex.clickhouse.ClickHouseDriver

使用的代码片段如下：

spark = SparkSession.builder \
    .appName("ClickHouse Example") \
    .master("spark://spark-master:7077") \
    .config("spark.driver.extraClassPath", "/opt/spark/jars/clickhouse-jdbc-0.4.6-all.jar") \
    .getOrCreate()

properties = {
    "url": "jdbc:clickhouse://127.0.0.1:8123/clickstream_data",
    "user": "1",
    "password": "2"
}

df = spark.read \
    .format("jdbc") \
    .option("url", properties["url"]) \
    .option("dbtable", "123") \
    .option("user", properties["user"]) \
    .option("password", properties["password"]) \
    .option("driver", "ru.yandex.clickhouse.ClickHouseDriver") \
    .load()

已将ClickHouse JDBC驱动（clickhouse-jdbc-0.4.6-all.jar）放置在/opt/spark/jars/目录，但驱动未被识别或存在兼容性问题。

错误原因分析 #

• Driver类路径未覆盖Executor节点：spark.driver.extraClassPath仅配置了Driver端的类路径，Spark集群模式下Executor节点无法访问该路径，导致驱动加载失败。
• 版本兼容性不匹配：ClickHouse JDBC驱动版本（0.4.6）与Spark版本、运行环境的Java版本存在兼容冲突。
• 驱动包权限不足：/opt/spark/jars/下的驱动包权限设置错误，Spark进程无法读取该文件。
• Driver类名过时：新版ClickHouse JDBC驱动已将类名从ru.yandex.clickhouse.ClickHouseDriver变更为com.clickhouse.jdbc.ClickHouseDriver，旧类名不适用于当前驱动版本。

解决方法 #

1. 统一配置Driver与Executor的类路径
   替换spark.driver.extraClassPath为spark.jars，让Driver和Executor都能加载驱动包：

   spark = SparkSession.builder \
       .appName("ClickHouse Example") \
       .master("spark://spark-master:7077") \
       .config("spark.jars", "/opt/spark/jars/clickhouse-jdbc-0.4.6-all.jar") \
       .getOrCreate()
   

   也可以在所有集群节点的/opt/spark/jars/目录下放一份驱动包，确保Executor能访问。

2. 修复版本兼容性

   • 确认Spark版本与ClickHouse JDBC驱动的兼容关系：比如Spark 3.x推荐使用0.4.x及以上版本的驱动。
   • 检查Java版本，确保与Spark、ClickHouse驱动兼容（推荐Java 8或11），不匹配则更换对应版本的驱动或Java环境。

3. 调整驱动包权限
   执行命令修改驱动包的权限，让Spark进程可读取：

   chmod 644 /opt/spark/jars/clickhouse-jdbc-0.4.6-all.jar
   chown spark:spark /opt/spark/jars/clickhouse-jdbc-0.4.6-all.jar
   

4. 修正Driver类名
   如果使用的是新版驱动，将代码中的驱动类名替换为：

   .option("driver", "com.clickhouse.jdbc.ClickHouseDriver")
   

额外配置建议 #

• 添加连接优化参数：补充超时、批次大小等参数提升连接稳定性：

  df = spark.read \
      .format("jdbc") \
      .option("url", properties["url"]) \
      .option("dbtable", "123") \
      .option("user", properties["user"]) \
      .option("password", properties["password"]) \
      .option("driver", "com.clickhouse.jdbc.ClickHouseDriver") \
      .option("socketTimeout", "30000") \
      .option("batchsize", "10000") \
      .load()
  

• 配置序列化方式：如果遇到数据序列化问题，添加序列化配置：

  .config("spark.serializer", "org.apache.spark.serializer.KryoSerializer")
  

• 提前测试连通性：先用命令确认ClickHouse服务正常：

  curl http://127.0.0.1:8123/
  

  返回Ok.则说明服务可达。

内容的提问来源于stack exchange，提问作者FeoJun