如何从SQLAlchemy连接到ClickHouse

ClickHouse是市场上最快的开源数据库之一，它声称比Spark更快。在WhiteBox，我们已经用一个+20亿行的表测试了这一假设，我们可以向你保证，它确实是这样的! 我们的测试结果是，对于一个带有几个过滤器的复杂聚合，速度快了3倍。

关于这个教程，这篇文章中的所有代码和步骤都是在2021年5月和Ubuntu 20.04操作系统下测试的，所以如果代码在2025年9月不起作用，请不要抱怨哈😅。

要求

该集成的要求如下。

• **ClickHouse服务器。**它可以很容易地按照官方文档安装。当前版本（21.4.5.46）。

• Python库。

  • SQLAlchemy：它可以安装使用管道安装SQLAlchemy==1.3.24

  • clickhouse-sqlalchemy: 可以使用 pip install clickhouse-sqlalchemy==0.1.6 安装。还有一个库 "sqlalchemy-clickhouse"，但它不支持大部分的SQLAlchemy魔法。

设置

安装ClickHouse

本教程可以对任何ClickHouse数据库进行测试。然而，为了得到一个本地的ClickHouse数据库来测试集成，它可以很容易地按照下面的步骤安装。

sudo apt-get install apt-transport-https ca-certificates dirmngr
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv E0C56BD4

echo "deb https://repo.clickhouse.tech/deb/stable/ main/" | sudo tee \
    /etc/apt/sources.list.d/clickhouse.list
sudo apt-get update

sudo apt-get install -y clickhouse-server clickhouse-client

sudo service clickhouse-server start

在shell上运行clickhouse-client，确保你的ClickHouse安装是正常工作。此外，它可以帮助你调试SQLAlchemy的DDL。

Python环境

这些是运行本教程中所有代码所需的Python库。

pip install SQLAlchemy==1.3.24
pip install clickhouse-sqlalchemy==0.1.6

集成

SQLAlchemy设置

以下几行代码执行SQLAlchemy的标准连接。

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

conn_str = 'clickhouse://default:@localhost/default'

engine = create_engine(conn_str)
session = sessionmaker(bind=engine)()

DDL

创建一个新的数据库

from sqlalchemy import DDL

database = 'test'

engine.execute(DDL(f'CREATE DATABASE IF NOT EXISTS {database}'))

可以用SHOW DATABASES这句话从命令行连接中测试ClickHouse中当前的数据库。下面的输出应该显示在屏幕上。

创建一个新的表

下面的步骤显示了如何在ClickHouse使用SQLAlchemy ORM模型创建一个MergeTree引擎表。

ORM模型定义

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

from clickhouse_sqlalchemy import engines

Base = declarative_base()

class NewTable(Base):
    __tablename__ = 'new_table'
    __table_args__ = (
        engines.MergeTree(order_by=['id']),
        {'schema': database},
    )

    id = Column(Integer, primary_key=True)
    var1 = Column(String)
    var2 = Column(Date)

DDL

NewTable().__table__.create(engine)

一个新的表应该出现在新的数据库中。

SQL

INSERT

from datetime import date

for i in range(1000):
    row = NewTable(id=i, var1=f'test_str_{i}', var2=date(2021, 5, 3))
    session.add(row)

session.commit()

选择

session.query(NewTable).filter(NewTable.id >= 500).first().id
session.query(NewTable).filter_by(var1='test_str_2').first().id

结论

ClickHouse应该取代传统的数据库，如Postgres，MySQL，Oracle？绝对不是。这些数据库有很多功能是ClickHouse目前不具备的，也不打算在未来具备（主键基本概念，唯一列...）。它可以被认为是一个分析数据库，但不是一个功能齐全的交易型数据库。

然而，ClickHouse的速度是如此惊人，以至于当有大量的表格数据时，它应该绝对是GOTO。

热评