【clickhouse】 使用 SQLAlchemy 连接 ClickHouse 数据库的完整指南

---

我听见有人猜
你是敌人潜伏的内线
和你相知多年
我确信对你的了解
你舍命救我画面
一一在眼前浮现
司空见惯了鲜血
你忘记你本是娇娆的红颜
感觉你我彼此都那么依恋
                     🎵 许嵩《内线》

---

ClickHouse 是一款非常高效的开源列式数据库，因其在处理大规模数据时的高性能和低延迟而广受欢迎。对于使用 Python 进行数据分析和处理的开发者而言，SQLAlchemy 是一个非常流行的数据库抽象层，可以用于连接和操作各种数据库。在这篇博客中，我们将介绍如何使用 SQLAlchemy 连接 ClickHouse 数据库，并展示一些基本的查询操作。

1. 为什么选择 SQLAlchemy 连接 ClickHouse？

SQLAlchemy 是 Python 中一个非常流行的 ORM（对象关系映射）框架，通常用于与数据库进行交互。相比于直接编写 SQL 语句，SQLAlchemy 提供了更高层次的抽象，支持多种数据库，并且可以灵活地生成 SQL 查询。通过 SQLAlchemy，我们可以更加优雅地与数据库交互，编写可维护、可扩展的代码。

虽然 ClickHouse 本身有许多客户端和 API 接口可供使用，但通过 SQLAlchemy 进行连接可以将 ClickHouse 与现有的 Python 数据库交互代码无缝集成，尤其在你使用多个数据库时会更加方便。

2. 安装所需库

要使用 SQLAlchemy 连接 ClickHouse，需要安装以下几个 Python 库：

SQLAlchemy：用于与数据库进行高层次的交互。
ClickHouse SQLAlchemy：这是 SQLAlchemy 的 ClickHouse 方言库。
ClickHouse-Connect（或其他驱动）：这是用于与 ClickHouse 通信的 Python 驱动。
在终端中使用以下命令来安装这些依赖项：

pip install sqlalchemy
pip install clickhouse-sqlalchemy
pip install clickhouse-connect

3. 连接 ClickHouse 数据库

ClickHouse 使用的是 HTTP 或 TCP 协议，因此连接 ClickHouse 时，我们可以选择 HTTP 端点或 TCP 端点。为了与 SQLAlchemy 配合使用，我们使用 clickhouse-sqlalchemy 库，它支持通过 SQLAlchemy 的连接字符串格式连接 ClickHouse。

3.1 基本的连接字符串格式

SQLAlchemy 使用统一的数据库 URI 连接格式，ClickHouse 也遵循类似的格式。以下是 ClickHouse 的基本连接字符串格式：

from sqlalchemy import create_engine

# ClickHouse 数据库的连接字符串格式
CLICKHOUSE_URI = 'clickhouse+http://<username>:<password>@<host>:<port>/<database>'

其中：
username: ClickHouse 用户名，通常是 default。
password: 用户密码。
host: ClickHouse 服务器的地址。
port: ClickHouse 服务器使用的端口（默认 HTTP 端口是 8123）。
database: 要连接的 ClickHouse 数据库名称。

3.2 创建数据库引擎

使用 SQLAlchemy 的 create_engine() 函数来创建连接引擎。引擎是与数据库交互的基础对象。

以下是一个完整的示例，展示如何使用 SQLAlchemy 创建到 ClickHouse 的连接：

from sqlalchemy import create_engine

# 定义连接字符串
CLICKHOUSE_URI = 'clickhouse+http://default:@localhost:8123/default'

# 创建 SQLAlchemy 引擎
engine = create_engine(CLICKHOUSE_URI)

# 测试连接
with engine.connect() as connection:
    result = connection.execute("SELECT version()")
    for row in result:
        print(f"ClickHouse 版本: {row[0]}")

在这个例子中，default:@localhost:8123/default 表示我们正在使用默认用户（没有密码），连接到本地运行的 ClickHouse 实例，默认数据库是 default。

4. 使用 SQLAlchemy 进行基本操作

创建完引擎之后，我们可以使用 SQLAlchemy 提供的各种方法来进行数据库操作，例如查询、插入、更新和删除数据。

4.1 查询数据

我们可以使用 SQLAlchemy 的 execute() 方法来执行任意 SQL 查询。比如，执行一个简单的 SELECT 查询，获取 ClickHouse 表中的数据：

# 假设有一个 `users` 表，查询其中的数据
with engine.connect() as connection:
    result = connection.execute("SELECT * FROM users LIMIT 5")
    for row in result:
        print(row)

在这个示例中，我们查询了 users 表中的前 5 条记录，并打印出结果。

4.2 插入数据

通过 execute() 方法，你也可以直接执行 INSERT 语句，向 ClickHouse 中插入数据。注意，ClickHouse 是一个列式数据库，通常不支持逐行插入，但在特定情况下（如小批量插入）可以进行插入操作。

insert_query = """
INSERT INTO users (id, name, age) VALUES
(1, 'Alice', 30),
(2, 'Bob', 24)
"""

with engine.connect() as connection:
    connection.execute(insert_query)
    print("数据插入成功")

4.3 创建表

SQLAlchemy 也可以用来创建表结构，以下是一个简单的表创建示例：

from sqlalchemy import Table, Column, Integer, String, MetaData

# 定义表结构
metadata = MetaData()

users_table = Table('users', metadata,
    Column('id', Integer, primary_key=True),
    Column('name', String),
    Column('age', Integer)
)

# 创建表
metadata.create_all(engine)
print("表 `users` 创建成功")

在这个例子中，我们定义了一个 users 表，并通过 metadata.create_all() 创建该表。

5. ORM 模式操作

SQLAlchemy 还支持使用 ORM（对象关系映射）模式与数据库交互。通过定义 Python 类，我们可以将数据库表映射为对象，并使用面向对象的方式操作数据库。

5.1 定义 ORM 模型

以下是定义一个 ORM 模型的例子：

from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, Integer, String

# 创建 ORM 基类
Base = declarative_base()

# 定义一个 User 类，对应数据库中的 users 表
class User(Base):
    __tablename__ = 'users'

    id = Column(Integer, primary_key=True)
    name = Column(String)
    age = Column(Integer)

# 创建数据库中的表
Base.metadata.create_all(engine)

5.2 插入数据（ORM）

我们可以通过创建对象的方式插入数据：

from sqlalchemy.orm import sessionmaker

# 创建会话
Session = sessionmaker(bind=engine)
session = Session()

# 创建新用户
new_user = User(id=3, name='Charlie', age=29)

# 添加并提交
session.add(new_user)
session.commit()

5.3 查询数据（ORM）

使用 ORM 模式查询数据也非常简单，像操作对象一样查询：

# 查询用户
users = session.query(User).filter_by(age=29).all()
for user in users:
    print(user.name)

6. 性能与优化

ClickHouse 是一个专为大数据设计的高性能数据库，使用 SQLAlchemy 与 ClickHouse 交互时，需要注意以下几点以保持性能：

批量操作：ClickHouse 更适合批量插入和查询数据，避免逐行操作。
并行执行：ClickHouse 支持并发查询，利用 SQLAlchemy 的连接池或并行库可以加速数据访问。
使用合适的驱动：clickhouse-connect 驱动性能较好，适用于高并发和大数据量的场景。

7. 总结

通过 clickhouse-sqlalchemy 和 SQLAlchemy 的结合，Python 开发者可以非常方便地连接并操作 ClickHouse 数据库。无论是通过 SQLAlchemy 的核心查询功能，还是 ORM 模式，SQLAlchemy 都能为你的 ClickHouse 项目提供强大的数据库抽象层。对于那些需要处理大量数据的应用，ClickHouse 与 SQLAlchemy 的结合能够提升开发效率，简化数据库操作的复杂度。

你可以根据需要扩展你的爬取任务、分析任务或其他大数据应用程序，借助 ClickHouse 强大的性能和 SQLAlchemy 的灵活性，构建高效的数据处理管道。