本地使用SQLAlchemy连接ClickHouse遇方言加载错误的解决方案咨询

问题 #

本地机器通过SQLAlchemy连接ClickHouse时，报错：Can't load plugin: sqlalchemy.dialects:clickhouse.native，但相同连接方式在JupyterHub中可正常运行。由于需要上传大文件，无法使用JupyterHub。

当前连接代码：

import sqlalchemy as sa
import pandas as pd
import polars as pl
import os

ch_host = os.getenv('CH_HOST', default='my_host')
ch_cert = os.getenv('CH_CERT', default='../path/to/cert')
ch_port = os.getenv('CH_PORT', default='my_port')
ch_db   = os.getenv('CH_DB', default='name_db')
ch_user = os.getenv('CH_USER', default='username')
ch_pass = os.getenv('CH_PASS', default='pass')
engine  = sa.create_engine(f'clickhouse+native://{ch_user}:{ch_pass}@{ch_host}:{ch_port}/{ch_db}?secure=True&ca_certs={ch_cert}')

# test connection
print(pd.read_sql('show tables', engine).head(5))

使用的包版本：

pandas: 2.0.3
polars: 0.18.10
SQLAlchemy: 2.0.19

解决方案 #

1. 安装ClickHouse的SQLAlchemy方言包 #

本地环境缺少适配的方言包（JupyterHub已预装），根据使用的协议选择安装：

• 若用clickhouse+native协议，安装clickhouse-sqlalchemy：

pip install clickhouse-sqlalchemy

• 若上述包安装后仍报错，尝试安装旧版兼容包sqlalchemy-clickhouse：

pip install sqlalchemy-clickhouse

2. 确保版本兼容 #

你的SQLAlchemy是2.0.19，需保证方言包支持SQLAlchemy 2.x。更新clickhouse-sqlalchemy到最新版本：

pip install --upgrade clickhouse-sqlalchemy

3. 调整连接协议 #

若native协议仍无法识别，尝试切换为HTTP协议（注意对应端口，默认8123）：

engine = sa.create_engine(f'clickhouse+http://{ch_user}:{ch_pass}@{ch_host}:{ch_port}/{ch_db}?secure=True&ca_certs={ch_cert}')

4. 修正证书路径 #

本地相对路径可能因工作目录问题找不到证书，改为绝对路径：

ch_cert = os.getenv('CH_CERT', default='/absolute/path/to/cert')

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