前言先澄清一个命名问题日常说的「金仓数据库」正式产品名是KingbaseES简称 KES由电科金仓原人大金仓研发。它是一款国产通用关系型数据库语法和协议层面与 PostgreSQL 有很深的渊源但它有自己的官方 Python 驱动不能简单地认为「PostgreSQL 驱动一定也能连」。最常见的误解有两个第一以为pip install psycopg2就能连金仓。KingbaseES 官方提供的 Python 驱动叫ksycopg2它是基于libkci金仓的客户端接口库封装的独立驱动通过 PyPI 发布需要pip install ksycopg2。它的接口风格与 psycopg2 高度相似但依赖的是金仓自己的客户端库不是 libpq所以两者不能互相替代。第二以为「连上了就万事大吉」。数据库编程真正的坑几乎都不在连接那一步而在事务边界、异常处理和连接复用上忘记commit()导致数据丢、异常路径上没rollback()导致连接卡在失败事务里、每次请求都新建连接导致连接数暴涨。本文按「装驱动 → 建连接 → 执行 SQL → 事务控制 → 用连接池」的顺序讲清一条完整链路。文中所有 SQL 都使用参数化占位符不拼接字符串。由于金仓驱动的版本迭代与部署环境差异较大涉及具体参数名时请以官方文档为准。一、驱动选型ksycopg2 与它的定位KingbaseES 官方 Python 驱动 ksycopg2 的关键事实实现了 Python DB-API 2.0 规范PEP 249因此connect()/cursor()/execute()/fetchone()/commit()/rollback()这一套接口是通用的。线程安全官方说明中提到多个线程可以共用一个连接。但「接口线程安全」不等于「你的业务逻辑可以随便并发用同一个游标」——同一个Cursor对象仍然不应该被多个线程同时操作。依赖平台和 Python 大版本驱动是二进制包按操作系统架构和 Python 版本区分Python 3.x 各小版本之间通常需要对应的包。装不上时第一步先确认「驱动包的 Python 大版本 ↔ 解释器大版本」是否对齐。依赖底层库ksycopg2 封装libkcilibkci又依赖 OpenSSL 一类的库。Linux 上如果报找不到共享库需要把客户端库目录加进动态库搜索路径Windows 上如果报 DLL 加载失败通常是缺少对应的 MSVC 运行库。安装与自检的最小流程# 安装Python 3python -m pip install ksycopg2# 验证是否能导入并确认版本python -c import ksycopg2; print(ksycopg2.__version__)如果pip install ksycopg2在你的平台上没有匹配的 wheel就去金仓官网的驱动下载页取对应平台的二进制包解压后把ksycopg2目录放进site-packages。注意这是唯一需要手工放包的情况不要从第三方来源随便拷贝驱动文件。二、建立连接连接串还是关键字参数ksycopg2 的connect()沿用了 psycopg2 的风格既接受 libpq 形式的连接串也接受关键字参数。两种写法对照写法示例适用场景连接串connect(host... port... dbname... user... password...)配置集中在一个环境变量里关键字参数connect(host..., port..., dbname..., user..., password...)参数来自配置对象便于校验关键点库名用dbnamelibpq 风格不是database。这一点与 pymysql / mysql-connector 不同照抄 MySQL 的代码会直接报错。端口按实际部署填写。金仓实例的监听端口在部署时配置默认安装常见为 54321但改过的实例很多不要写死猜测值。不要把密码写进源码。用环境变量或配置文件读取例如os.environ[KES_PASSWORD]并把配置文件排除在版本控制之外。# 适用于 Python 3.8import osimport ksycopg2conn ksycopg2.connect(hostos.environ.get(KES_HOST, 127.0.0.1),portint(os.environ.get(KES_PORT, 54321)),dbnameos.environ[KES_DB],useros.environ[KES_USER],passwordos.environ[KES_PASSWORD],connect_timeout5,)print(连接成功服务端版本, conn.server_version)conn.close()connect_timeout建议一定写上。不写的话网络不通时程序会长时间挂在那里看起来像「卡死」实际是在等 TCP/握手超时。三、执行 SQL只写参数化查询这是全文最重要的一节。绝对不要用 Python 的字符串拼接去构造 SQL——那样会把用户输入当成 SQL 语法的一部分执行这就是 SQL 注入的成因。正确做法是把值交给驱动去绑定用%s占位符注意这里的%s不是 Python 的字符串格式化它由驱动替换成数据库参数不会经过 Python 的%运算。# 适用于 Python 3.8import ksycopg2conn ksycopg2.connect(dbnamesample userSYSTEM passwordsecret host127.0.0.1)with conn.cursor() as cur:# 建表DDL 不含用户输入直接执行cur.execute(CREATE TABLE IF NOT EXISTS account (id BIGSERIAL PRIMARY KEY,owner VARCHAR(64) NOT NULL,balance NUMERIC(12,2) NOT NULL DEFAULT 0))# 写数据值一律走占位符cur.execute(INSERT INTO account (owner, balance) VALUES (%s, %s),(张三, 100.00),)# 读数据条件值同样走占位符cur.execute(SELECT id, owner, balance FROM account WHERE owner %s,(张三,),)for row in cur:print(row)conn.commit()conn.close()几个必须记住的细节单元素元组要写逗号(张三,)而不是(张三)。后者在 Python 里只是一个字符串驱动会把它当成「一串字符」逐个绑定报参数个数不匹配。%是驱动自己的占位符字符。如果你的 SQL 里要出现字面量的%比如LIKE abc%需要写成%%否则驱动会以为你要绑参数。executemany适合批量写循环里逐条execute会把往返次数放大批量插入改用cur.executemany(sql, rows)其中rows是一个可迭代对象每个元素是参数序列。返回结果集用迭代或fetchall()不要用while True加下标去猜行数。关于「怎么防注入」除了参数化还有两条原则表名、列名这类标识符不能参数化占位符只能绑值必须用白名单映射数据库账号权限最小化应用账号只给必要的表和操作权限这样即使出了纰漏影响面也被限制住。四、事务与连接管理DB-API 的默认行为是「手动提交」INSERT/UPDATE/DELETE执行完不会立即生效必须显式commit()。这条规则是新手最容易踩的坑——程序跑完不报错去数据库一看没数据。正确的写法是把「事务」当成一个整体要么全成功要么全回滚。# 适用于 Python 3.8import ksycopg2def transfer(conn, from_id: int, to_id: int, amount):同库转账两条 UPDATE 必须同生共死。with conn.cursor() as cur:cur.execute(UPDATE account SET balance balance - %s WHERE id %s,(amount, from_id),)if cur.rowcount ! 1:raise ValueError(f扣款账户不存在: {from_id})cur.execute(UPDATE account SET balance balance %s WHERE id %s,(amount, to_id),)if cur.rowcount ! 1:raise ValueError(f收款账户不存在: {to_id})conn ksycopg2.connect(dbnamesample userSYSTEM passwordsecret host127.0.0.1)try:transfer(conn, 1, 2, 50.00)conn.commit() # 两条 UPDATE 一起生效except Exception:conn.rollback() # 任何一步失败全部撤销raisefinally:conn.close() # 连接一定要关finally里的close()是必须的。如果异常路径上没有rollback()连接会停留在「事务失败」状态之后复用这个连接执行任何语句都会继续报错这就是「明明修好了 SQL 还是连不上」的典型症状。关于连接池如果应用是常驻服务Web 服务、定时任务不要在每次请求里connect()。建连接涉及网络握手和认证成本远高于执行一条语句。金仓官方文档里提供了客户端连接池的配置指南ksycopg2 也提供了与 psycopg2 同名的连接池实现简单池和可跨线程使用的池。使用要点是池的minconn/maxconn按数据库的max_connections留出余量别把池上限设得比数据库允许的连接数还大。从池里拿到的连接用完必须归还putconn而不是close()。直接close()会把池里的连接消耗光之后getconn就会阻塞或报错。借出的连接在归还前要确保事务已经结束commit()或rollback()否则下一个使用者会继承一个脏的事务状态。常见坑点1. 把密码硬编码在源码里❌conn ksycopg2.connect(dbnamex userSYSTEM passwordKes123 host127.0.0.1)直接提交进仓库。✅ 从环境变量或受控配置文件读取import osconn ksycopg2.connect(dbnameos.environ[KES_DB],useros.environ[KES_USER],passwordos.environ[KES_PASSWORD],hostos.environ[KES_HOST],)2. 用字符串拼接构造 SQL❌sql SELECT * FROM account WHERE owner name ——用户输入name里只要含有引号就能改变语句结构。✅cur.execute(SELECT * FROM account WHERE owner %s, (name,))值永远交给驱动绑定。3. 忘记 commit数据「丢了」❌ 执行完INSERT就close()程序无异常数据库里查不到新行。✅ 事务结束处显式conn.commit()读操作可以不加但养成「写操作必配 commit」的习惯更稳。4. 单元素参数元组漏了逗号❌cur.execute(... WHERE id %s, (user_id))——(user_id)不是元组是user_id本身。✅cur.execute(... WHERE id %s, (user_id,))。5. 异常路径上没有 rollback❌try: ...; conn.commit() except: pass——异常被吞掉连接停在失败事务里后续所有操作连环报错。✅except Exception: conn.rollback(); raise让上层知道失败同时把连接恢复到可用状态。6. 照抄 MySQL 的连接参数名❌ksycopg2.connect(host..., user..., password..., databasesample)—— 金仓驱动用的是dbname不是database。✅ksycopg2.connect(host..., user..., password..., dbnamesample)。7. 用同一个游标对象跨线程并发❌ 多线程共享一个cur各自execute后fetchall()结果互相串行取到别人的结果集。✅ 每个线程用自己的游标conn.cursor()连接可以复用或者干脆用连接池每线程取一个连接。8. SQL 里出现字面量%却没转义❌cur.execute(SELECT * FROM t WHERE name LIKE ab%)—— 驱动会把%当占位符报「参数个数不匹配」。✅ 参数化写法cur.execute(SELECT * FROM t WHERE name LIKE %s, (ab%,))把%放进参数值里。总结环节关键结论最容易踩的坑驱动用官方 ksycopg2DB-API 2.0 接口依赖 libkci误用 psycopg2 或未对齐 Python 大版本连接参数名是dbname密码来自环境变量设connect_timeout硬编码密码、写死端口执行值一律走%s占位符标识符走白名单字符串拼接 SQL事务手动提交失败必须 rollback忘 commit、异常路径漏 rollback连接管理常驻服务用连接池用完归还而不是 close每请求新建连接、close 掉池连接金仓的 Python 接入在语法上和 PostgreSQL 高度一致真正决定代码质量的是参数化习惯和事务边界的严谨程度。把这两点做对剩下的就是按官方文档对齐驱动的版本与平台了。