折腾了两天终于把SQLAlchemy连上了金仓数据库

从一个报错开始

上周接了个小活，要把一个用SQLAlchemy写的数据分析脚本从MySQL迁到金仓。本来以为换个数据库驱动就行，结果跑起来直接报错：

No module named 'sqlalchemy.dialects.kingbase'

查了一圈才发现。SQLAlchemy不像MySQL、PostgreSQL那样自带驱动，金仓的包需要手动装。话说回来，折腾了两天才跑通，今天把过程记下来

为什么非要手动装

SQLAlchemy本身只是个壳。它不知道自己该怎么跟数据库说话。每种数据库需要一个“翻译”，这个翻译就叫包。

• 痛点 1：缺少官方支持的包。大多数主流数据库在安装时会自动包含对应，但金仓不在列表里需要自己下载并放置。
• 痛点 2：底层驱动依赖不清楚。金仓的包依赖ksycopg2驱动，所以这两个都得先装。

二、安装步骤

先装 SQLAlchemy

pip install sqlalchemy

装完看一眼装在哪了后面放包要用：

pip show sqlalchemy

我的机器输出是这样的：

Name: SQLAlchemy
Version: 1.x.x
Location: /usr/local/lib/python3./site-packages
...

记下这个Location方法。

装 ksycopg2 驱动

pip install ksycopg2

This usually succeeds without issue. Windows 使用者可能需要装 /ksycopg2-win64/.

放包

找到 SQLAlchemy 的安装目录，进去找到 /dialects/ 文件夹：

cd /usr/local/lib/python3./site-packages/sqlalchemy/dialects/

把从官网下载的 /kingbase/ 文件夹整个复制到这里。最终目录结构应该是：

sqlalchemy/dialects/
├── kingbase/
│ ├── __init__.py
│ └── base.py
├── mysql/
├── postgresql/
└── ...

I initially put it in root of /site-packages/ ,which caused loading failures.

• 坑 1：放错位置导致模块找不到。老实说，
• 坑 2：版本不匹配导致奇怪错误。
• Tip: 确保将完整的 /kingbase/ `folder` 放在 /dialects/ `folder` 下而不是直接放在 site-packages 根目录。

版本匹配问题：* 官方提供了 1.x、1.y 和 1.z 三个版本的包。其实，我用的是 SQLAlchemy 1.x，需要选对应的 1.x 包。否则会报 “module not found” 等错误。

三、连接数据库

连接字符串怎么写

The connection string format is:

from sqlalchemy import create_engine
engine = create_engine
engine = create_engine


`kingbase` – 名；告诉 SQLAlchemy 用金仓的包。按理说，

`ksycopg2` – 驱动名；实际执行任务的是它，

`SYSTEM` – 数据库使用者名。

`PASSWORD` – 密码，可留空。
按理说，

`IP_ADDRESS` – IP 地址。

`PORT` – 金仓默认端口，一般是 `54320`。

`TEST` – 数据库名。


测试一下能不能连上：
python
from sqlalchemy import create_engine
conn_str = 'kingbase://SYSTEM:@IP_ADDRESS:PORT/TEST'
engine = create_engine
conn = engine.connect
result = conn.execute")
print)
conn.close
如果看到版本信息输出，则成功连上。

连接池参数**\* **\*
engine = create_engine(
'kingbase://SYSTEM:@IP_ADDRESS:PORT/TEST',pool_size=10。max_overflow=5,pool_recycle=3600,pool_pre_ping=True
)


`pool_pre_ping=True` 可以避免拿到已断开的连接。

四、ORM建模和基本操作
**定义模型**
python
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column,Integer,String,DateTime
from datetime import datetime
Base = declarative_base
class User:
__tablename__ = 'test_user' # 表名必须写明
id = Column
name = Column)
email = Column)
created_at = Column
def __repr__:
return f"User"


建表

python
Base.metadata.create_all # 幂等操作，多次执行无副作用


创建 Session

python
from sqlalchemy.orm import sessionmaker

Session = sessionmaker
session = Session


增删改查



操作
示例代码




插入数据
python

user1 = User

user2 = User

session.add_all

session.commit




查询数据
python

users= session.query.all

for u in users:

print



# 条件查询

user=session.query.filter.first

print



# 模糊查询

users=session.query.filter).all




更新数据
python

# 方法一：先取出来再改属性

user=session.query.filter.first

user.email=''

session.commit



# 方法二：批量更新。不取对象直接改

session.query.filter.update

session.commit




删除数据
python

# 单条删

user=session.query.filter.first

session.delete

session.commit



# 批量删

session.query.filter.delete

session.commit






事务处理

默认 Session 不自动提交，需要手工 commit 或 rollback

python
try这方面，session.add)
# 若此处出错…session.commit
except Exception as e:
session.rollback
print
finally:
session.close


五、踩过的几个坑



痛点
原因
对策




坑 ① 包放错位置
把 kingbase 文件夹直接拷贝到 site-packages 根目录，而不是 dialects/ 子目录。
确认放在 /dialects/kingbase/ 下。


坑 ② 版本不匹配
使用 SQLAlchemy 1.x 时选用了与之不兼容的老版或新版包。
根据 SQLAlchemy 主版本号挑选对应的 KingBase 版本。


坑 ③ libkci.so 找不到
缺少底层共享库导致链接失败。
设置环境变量，例如 export LD_LIBRARY_PATH=/home/user/kcibase/lib:$LD_LIBRARY_PATH.


坑 ④ 连线字符串写错
写成 kingbase+psycopg2://…按理说， 而实际使用的是 ksycopg2.
正确写成 kingbase+ksycopg2://… 或简化为 kingbase://….




六、小结

折腾下来SQLAlchemy 连金仓其实不算复杂，只是需要手工配置包这一点与其他主流数据库不同。

至于整体流程，


安装 SQLAlchemy 与 ksycopg2。

把下载好的 KingBase 文件夹拷贝至 /dialects/.

用以 kingbase://… 开头的连接字符串创建 Engine。


ORM 操作与使用 MySQL/PostgreSQL 基本一致，无需改代码即可迁移项目。