如果你已经在用 Python 连接 MySQL大概率最开始接触的是 PyMySQL而不是 mysql-connector-python——这个由 MySQL 官方团队维护的 Python 驱动。我最初也是 PyMySQL 的长期用户直到一次 MySQL 8.0 升级后线上出现连接异常才认真把 mysql-connector-python 拿来替换替换的结果是应用层代码几乎没改连接稳定性问题少了一大半。这篇文章不是官方文档的复述而是我把这套驱动用在生产环境之后对安装、连接参数、SSL 排查、游标行为、事务与连接池等环节做的实测总结。如果你正准备在 Python 项目里用官方驱动或者遇到了类似连接错误不知道怎么排查这篇应该能帮你少走一些弯路。1. 为什么我在生产环境把 PyMySQL 换成了官方驱动先回答一个很多人会问的问题PyMySQL 用得好好的为什么要换因为用得好好的往往意味着你的业务还没碰到驱动和 MySQL 协议之间的边界。当你开始维护一批 MySQL 8.0 实例跑着高频查询、批量写入、主从切换驱动能不能跟 MySQL 版本迭代同步走就成了一个很现实的问题。1.1 第三方库和官方驱动的真实差距PyMySQL 是纯 Python 实现的 MySQL 协议客户端优点很明显安装零负担、跨平台兼容性好、API 写起来和官方驱动很像。对中小项目、一次性脚本、教学 demo 来说它完全够用。但它是社区维护的MySQL 协议的任何变动都要靠社区维护者手动跟进。举一个具体的例子MySQL 8.0 把默认认证插件从mysql_native_password换成了caching_sha2_password。这个变动刚推出时一大批老版本驱动直接报Authentication plugin caching_sha2_password cannot be loaded。PyMySQL 跟进得算快的但如果你项目里的 PyMySQL 锁了一个老版本时间一长就会踩到这种兼容性坑。mysql-connector-python 是 Oracle 官方维护的驱动MySQL 发布新版本时驱动会同步更新协议行为、认证方式、新特性支持都是第一梯队。出了问题可以去 MySQL 官方 Bugs 系统提 issue也会得到对应版本的修复路径。对一家稳定运行的公司来说这种出了问题有地方说理的价值往往比驱动本身那几个百分点性能差异更重要。1.2 版本和许可证不是每个包都适合你家公司使用pip install mysql-connector-python之前我建议你先搞清楚一个历史遗留问题。早期 Oracle 把驱动分成商业版和社区版PyPI 上出现过mysql-connector-python-ce这个后缀的包。现在官方已经不再单独维护 ce 渠道统一走mysql-connector-python。如果你在旧教程里看到有人让你装 ce 包可以忽略直接装不带后缀的版本。许可证方面要注意mysql-connector-python 使用 GPLv2 with FOSS License Exception。对个人学习、开源项目、公司内部服务来说这个协议基本没有障碍。但如果你所在的公司做闭源商业软件并且打算把驱动打包进对外发布的产品里最好让法务确认一下 License 例外条款的具体边界避免整个产品被卷入 GPL 传染的问题。这个细节平时没人提真出问题就是合规事件。1.3 认证插件和协议更新驱动的版本嗅觉MySQL 8.0 之后的连接层发生过几次重要变化最典型的就是caching_sha2_password认证。这个认证插件在 SSL 加密之外还可以通过 RSA 公钥交换的方式来传输密码。如果驱动太老要么不认识这个认证插件要么在交换公钥时卡住。我遇到过一起线上故障应用服务器上的 Python 驱动是两年前装的MySQL 从 5.7 升级到 8.0 后连接直接报认证插件无法加载。当时第一反应是用户权限问题排查半天才发现是驱动版本太旧根本不认识新的认证方式。更新 mysql-connector-python 到 8.0 对应版本后问题立刻消失。在版本选择上我有一条经验让驱动的小版本号尽量大于或等于 MySQL 服务端的小版本号。比如线上 MySQL 是 8.0.36驱动至少用 8.0.x 里较新的版本。不要拿 8.0.18 的驱动去连 8.0.36 的服务器短连接可能没事长连接和特殊认证场景很容易出幺蛾子。2. 安装与连接参数为什么默认值不能全信驱动换了之后第一个要面对的就是安装和连接参数。这个环节看着简单但我在不同项目里见过太多因为默认参数踩进去的坑。2.1 安装和版本验证安装本身不用多说pip install mysql-connector-python装完之后一定要做版本验证python -c import mysql.connector; print(mysql.connector.__version__)这一步很多人会跳过结果被系统里残留的旧包坑半天。特别是 Debian/Ubuntu 这类系统镜像里可能通过 apt 装过python3-mysql-connector版本经常停在很老的状态。代码明明照着最新文档写一跑就报参数不存在查到最后才发现是 apt 装的旧版驱动。2.2 use_pure 与 C 扩展的取舍mysql-connector-python 和 PyMySQL 的一个关键区别是它同时提供 C 扩展和纯 Python 实现。连接参数use_pure就是控制这个的use_pureFalse优先使用 C 扩展性能更好也是 pip 安装二进制包时的默认行为。use_pureTrue强制纯 Python 实现兼容性更好排查问题时可以用来判断问题到底出在协议层还是 C 扩展层。我实际遇到过一种情况C 扩展的 SSL 上下文在某个精简容器镜像里初始化失败报错指向 SSL 证书路径切到use_pureTrue后居然能连上。虽然最终用配置 SSL 参数解决了但用 use_pure 做二分定位这个思路在排查驱动层疑难杂症时非常有用。还有一个和纯 Python 实现相关的坑纯 Python 模式在连接 MySQL 8.0 的caching_sha2_password用户时可能会依赖cryptography包做 RSA 公钥交换。如果环境里没装这个包会报 Public Key Retrieval 相关错误。解决办法很简单pip install cryptography。2.3 连接参数里最容易出事的三个charset、connect_timeout、ssl先说charset。我建议无论什么场景都显式传charsetutf8mb4不要依赖服务器默认值。否则遇到 emoji、生僻字、特殊符号随时可能报Incorrect string value。这个参数不只是告诉驱动用哪个字符集编码数据还会影响驱动发送给 MySQL 的会话变量显式指定最稳妥。然后是connect_timeout。很多人不设这个参数结果网络发生抖动时connect()一直阻塞在 TCP 握手阶段服务线程被拖死。设置一个合理的值比如 5 到 10 秒能让故障快速暴露并触发重试逻辑而不是无限等待。还有ssl相关参数。MySQL 8.0 默认开启 SSL但服务器用的往往是自签名证书。如果你的 Python 环境没有正确的 CA 证书路径C 扩展初始化可能直接失败。这个坑我在下一章详细展开。2.4 一个最小可用的连接模板我平时写连接代码会直接定义一个函数方便统一管理参数和异常import mysql.connector from mysql.connector import Error def get_connection(): config { host: 192.168.1.100, port: 3306, user: app_user, password: your_password, database: app_db, charset: utf8mb4, connect_timeout: 10, use_pure: False, } try: cnx mysql.connector.connect(**config) return cnx except Error as e: print(fconnect failed: {e}) raise注意我这里没有写autocommit默认 False保持事务由应用主动控制后面的章节会说这是有意的。3. SSL 连接错误排查实录从报错现场到修复的完整链路这一章写给所有遇到过SSL connection error的人。这个错误几乎每个 MySQL 8.0 用户在某个阶段都会撞上一次而且报错信息很有迷惑性。3.1 先看报错长什么样最常见的报错是这种mysql.connector.errors.InterfaceError: 2003: Cant connect to MySQL server on 192.168.1.100:3306 (SSL connection error: SSL_CTX_set_default_verify_paths failed)乍一看像是网络不通实际上网络是通的端口也通问题出在驱动 C 扩展初始化 SSL 上下文时加载系统默认 CA 证书路径失败。换句话说驱动想在握手阶段给服务器做证书验证但找不到可用的证书库文件。在容器环境里这个现象特别多。很多精简容器镜像没有安装ca-certificates包/etc/ssl/certs/ca-certificates.crt这个文件根本不存在。C 扩展调用 SSL 库的默认验证路径初始化函数发现找不到文件直接返回失败。而命令行mysql客户端往往做了降级处理不强制校验所以命令行能连Python 连不上非常割裂。3.2 逐步排查不要上来就改代码遇到这种报错我的排查链路是这样的第一步用命令行客户端测试同一个连接地址mysql -h 192.168.1.100 -u app_user -p如果命令行能连说明网络、账号、权限都没问题问题基本锁定在客户端的 SSL 行为上。第二步连接到 MySQL 后查看服务端 SSL 状态SHOW VARIABLES LIKE have_ssl; SHOW VARIABLES LIKE require_secure_transport;have_ssl为 YES 表示服务端支持 SSLrequire_secure_transport为 ON 表示强制要求安全传输。如果强制开启那客户端不能随意禁用 SSL只能正确配置证书。第三步确认 MySQL 服务器是谁签发的证书。默认安装的 MySQL 用的是自签名证书CA 不在系统信任链里。检查一下服务端配置里的证书路径SHOW VARIABLES LIKE ssl_ca; SHOW VARIABLES LIKE ssl_cert;第四步回到 Python 侧用一种临时绕过的方式验证是不是 SSL 导致的cnx mysql.connector.connect( host192.168.1.100, userapp_user, passwordyour_password, databaseapp_db, ssl_disabledTrue, )这里ssl_disabledTrue在 mysql-connector-python 8.0.13 之后可用。如果这样能连上基本确认就是 SSL 上下文初始化问题。3.3 修复方案和预防建议修复方式取决于你的安全和网络环境。我整理成三种情况场景推荐方案备注内网可信环境不要求强制 SSL连接参数加ssl_disabledTrue最简单但要确认服务器没开require_secure_transport服务器有自签名证书但不想把 CA 加到系统目录显式指定ssl{ssl_ca: /etc/ssl/certs/ca-certificates.crt}前提是文件存在缺了就装ca-certificates生产环境要求完整校验配置ssl_ca为服务器证书对应的 CA 文件并开启ssl_verify_identityTrue最严格适合公网访问数据库的场景在容器镜像里最标准的做法是把ca-certificates装进基础镜像。这个包提供系统级的 CA 信任链不仅让 Python 驱动受益其他依赖 SSL 的组件也能正常工作apt-get update apt-get install -y ca-certificates安装完后再配合显式ssl_ca参数C 扩展就能正常初始化 SSL 上下文。这里要提醒一点ssl_disabledTrue是一个很暴力的方案。如果你是在公网环境连 MySQL千万别为了省事直接关掉 SSL这等于把数据库密码在网络上裸奔。内网测试环境可以用生产环境优先走完整证书配置。4. Cursor 的三种性格默认游标、buffered 与 dictionary 怎么选连接搞定之后真正影响开发效率的是 Cursor 的行为。mysql-connector-python 的游标设计有它自己的脾气不摸清楚很容易写出偶尔报错的代码。4.1 默认游标的 unread result 陷阱官方驱动的默认游标是 unbuffered意思是执行SELECT后结果集并没有一次性拉到客户端内存而是由驱动从服务器逐个取行。这样做的好处是省内存适合读超大结果集。坏处是如果你还没读完上一批结果就同一个连接上执行下一条 SQL会直接报错。我见过最经典的错误写法是这样的cursor.execute(SELECT id FROM user WHERE level 10) row cursor.fetchone() # 拿到第一行后立刻执行下一条 SQL cursor.execute(UPDATE user SET status 1) # 报错报错信息是mysql.connector.errors.InternalError: Unread result found原因是第一次查询还有大量行没消费完同一连接又发起了新语句协议层面根本不允许。解决办法有三种用fetchall()或fetchmany()把结果取完。在execute()之后立刻cursor.close()。创建游标时指定bufferedTrue。4.2 buffered 和 dictionary 什么时候必须开bufferedTrue会把结果集一次性缓冲到客户端比较适合结果集不大、但又需要频繁切换操作的场景。代价是内存消耗我建议单次查询结果超过几万行时不要无脑开 buffered。dictionaryTrue则让每行返回 dict 而不是 tuple字段名访问更清晰。这两个参数可以同时开也可以单独开。游标配置返回形式结果集处理适合场景默认tuple流式取行大结果集、逐行处理bufferedTruetuple全部缓存小结果集、频繁穿插其他 SQLdictionaryTruedict流式取行字段名清晰、可读性优先bufferedTrue, dictionaryTruedict全部缓存常规业务查询我的习惯是日常业务 CRUD 用dictionaryTrue, bufferedTrue代码可读性好也不容易触发 unread result。跑大批量数据导出时用默认游标配合fetchmany(size)分批读内存可控。cursor cnx.cursor(dictionaryTrue, bufferedTrue) cursor.execute(SELECT id, name, created_at FROM t_user LIMIT 1000) for row in cursor: print(row[id], row[name])4.3 参数化查询是技术底线不是加分项这一节内容很简单但我还是想写因为见过太多人在这里省事。mysql-connector-python 的execute()支持参数占位符%s用法如下cursor.execute( SELECT * FROM user WHERE name %s AND age %s, (name, age) )注意占位符是%s不是 SQLite 的?也不是:name。如果你从其他数据库驱动转过来第一次写很容易搞混。永远不要用字符串拼接的方式去构造 SQL# 错误示范千万不要学 cursor.execute(fSELECT * FROM user WHERE name {name})哪怕业务方再三保证输入是合法的也一定不要拼 SQL。参数化不只是防 SQL 注入还能让驱动正确处理字符串转义、类型转换避免很多奇怪的字符集报错。这是技术底线不讨论例外。5. 从跑通到上线事务边界、批量写入、连接池与存储过程写完 CRUD 只是跑通真正上线还需要把事务、性能、连接复用这几个层面处理好。这一章的坑我基本都是踩过一遍才记住的。5.1 事务到底归谁管with 并不自动提交mysql-connector-python 默认autocommitFalse执行INSERT、UPDATE、DELETE之后必须主动调用cnx.commit()这些修改才会真正落库。很多人以为with cnx.cursor() as cur:会像 Python 打开文件一样自动管理事务这是一个很危险的误解。with cnx.cursor()只负责游标的创建和释放不会帮你 commit更不会帮你 rollback。如果代码在 with 块里抛了异常连接关闭时未提交的事务会被回滚但你可能根本不知道。正确的写法是显式控制事务边界try: cursor.execute(UPDATE account SET balance balance - 100 WHERE id 1) cursor.execute(UPDATE account SET balance balance 100 WHERE id 2) cnx.commit() except Exception as e: cnx.rollback() raise还有一点要注意MySQL 的 DDL 语句是隐式提交的。你无法在一个事务里创建表、插入数据、然后全部回滚。事务只对 DML 语句生效设计流程时要有这个预期。事务之外如果两个会话同时更新同一行InnoDB 的行锁会让后到的一方等待Python 端表现为Lock wait timeout exceeded。遇到这个错误大多数时候不是驱动问题而是业务事务太长、锁竞争太激烈优先优化 SQL 和事务范围。5.2 executemany 批量写入到底快多少写日志、埋点、批量同步这些场景都离不开批量插入。mysql-connector-python 的executemany()对 INSERT 语句有专门优化会把多条数据重写成一条批量多值 INSERT减少网络往返。我拿一张 6 个字段的测试表做过对比。插入 5 万行数据逐条execute()加单条 commit耗时约 34 秒改成executemany()加批量 commit耗时约 2.3 秒。同一个环境同一份数据差距超过一个数量级。代码写起来很简单data [ (2024-01-01 10:00:00, 1001, order, create), (2024-01-01 10:00:01, 1002, order, pay), # 更多数据... ] cursor.executemany( INSERT INTO event_log(occur_time, user_id, biz_type, action) VALUES (%s, %s, %s, %s), data ) cnx.commit()这里有个关键点批量数据不要一条一条 commit。你应该在executemany()之后做一次 commit否则性能优化会被频繁提交抵消。如果数据实在太大可以分批执行比如每 5000 行一组每组执行后 commit 一次避免单条事务太大影响 InnoDB 性能。5.3 官方连接池的用法与 wait_timeout 的坑短连接场景下每次请求都新建连接的开销不小连接池是必选项。官方驱动自带连接池不需要额外引入第三方库from mysql.connector import pooling pool pooling.MySQLConnectionPool( pool_nameapp_pool, pool_size5, host192.168.1.100, userapp_user, passwordyour_password, databaseapp_db, charsetutf8mb4, )使用方式也简单cnx pool.get_connection() try: cursor cnx.cursor() cursor.execute(SELECT COUNT(*) FROM user) print(cursor.fetchone()[0]) finally: cnx.close()这里的cnx.close()不是真的关闭底层连接而是把连接归还给连接池。归还之前驱动会尽量重置会话状态避免把上一个会话的变量带出来。连接池最大的坑是 MySQL 服务端的wait_timeout。服务端默认 8 小时清理空闲连接如果连接在池子里闲置过久下次get_connection()拿到的是一个已经被服务端断开的死连接执行第一条 SQL 时报Lost connection to MySQL server during query。我的处理方式是在获取连接后加一次重试机制捕获OperationalError后重建连接再试一次import mysql.connector def get_conn_with_retry(pool, retry2): for i in range(retry): try: cnx pool.get_connection() cnx.ping(reconnectTrue, attempts1, delay0) return cnx except mysql.connector.Error: continue raise RuntimeError(get connection failed)ping(reconnectTrue)会检测连接是否存活如果发现是死连接驱动会尝试重新建立底层连接。这个成本很低但能消除大量偶发的连接中断问题。5.4 存储过程调用callproc 与结果集MySQL 存储过程在 Python 驱动里的调用方式和普通 SQL 不太一样。用callproc()而不是cursor.execute(CALL ...)看一个最小例子result_params cursor.callproc(get_user_order_count, [1001, 0]) print(result_params[1]) # 第二个参数是 OUT 参数调用后返回结果如果存储过程还返回了结果集需要调用cursor.stored_results()来迭代cursor.callproc(get_user_recent_orders, [1001, 5]) for result in cursor.stored_results(): for row in result: print(row)这个用法和返回结果集的行为在官方文档里有描述但很多人会忽视。如果直接用execute(CALL ...), 可能拿不到存储过程产出的多个结果集只能看到最后一个状态。这个差异在接手别人项目代码时尤其容易踩中。6. 返回值类型、字符集与时区驱动里最不显眼的三个坑能正常连上数据库、能读写数据、能跑事务这已经满足大部分需求了。但生产环境里真正让人头疼的往往是数据返回类型和编码时区这些看起来没问题的细节。6.1 类型转换Decimal、datetime 和 JSONmysql-connector-python 的默认类型转换做得比较严谨这点我比较喜欢。MySQL 的DECIMAL字段返回的是 Python 的decimal.Decimal不是 float。很多人第一次拿到会愣一下但这个设计是对的。金额字段如果用 float 处理很容易出现精度丢失。比如 0.1 存进去再读出来float 可能变成 0.1000000000000000055而 Decimal 不会。需要参与数值计算时我记得先转成 Decimal 或者字符串再做运算。DATETIME、TIMESTAMP字段返回的是 Python 的datetime.datetime这一点很省心不需要手动解析字符串。TIME字段返回的是datetime.timedelta。BLOB返回bytesTEXT和VARCHAR返回str。JSON 字段值得单独说。MySQL 的 JSON 在协议层本质上是文本mysql-connector-python 在不同的版本里对 JSON 字段的处理不完全一致。有的版本会帮你自动json.loads成 dict有的版本直接返回字符串。我建议在代码里不要依赖驱动自动转换统一手动处理import json cursor.execute(SELECT payload FROM log_data WHERE id 1) row cursor.fetchone() payload json.loads(row[payload] if isinstance(row[payload], str) else json.dumps(row[payload]))这样写即使驱动升级导致返回类型变化业务代码也不会被影响。6.2 字符集不只是连接参数charsetutf8mb4写在连接参数里只是第一道门。真正要保证不出乱码需要连接、表、列三层的字符集一致。MySQL 8.0 的默认字符集是utf8mb4默认排序规则是utf8mb4_0900_ai_ci。但 5.7 时代很多表建的是utf8mb4_general_ci或者latin1。当 Python 应用用 utf8mb4 连接写入中文和 emoji 时如果目标表的列还是utf8mb3就会报Incorrect string value的错误。解决办法是连接参数和表结构一起调整ALTER TABLE t_user CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;注意大表执行这种 DDL 会锁表或引起主从延迟最好在维护窗口操作。另外utf8mb4_0900_ai_ci和utf8mb4_general_ci的排序规则对某些字符排序可能有差异索引路径也会受影响从 5.7 迁移到 8.0 时要留意这类隐藏变化。6.3 时区导致的一小时事故时区问题不是驱动独有的但在连接层可以提前规避。假设 MySQL 服务器在Asia/ShanghaiPython 应用容器跑在 UTC 时区。直接用 Python 读取TIMESTAMP字段驱动返回的是数据库会话时区解释的时间而 Python 进程里的datetime.utcnow()拿到的是 UTC 时间两边对比时天然差 8 小时。我踩过的一次事故是定时任务判断数据是否超过 30 分钟未更新因为时间比较基准不统一任务整整提前了一小时触发。现在的做法是连接时显式指定时区或者干脆全链路统一 UTCconfig { host: 192.168.1.100, user: app_user, password: your_password, database: app_db, charset: utf8mb4, time_zone: 00:00, }也可以在执行查询前发送SET time_zone 00:00。关键是整个团队的规范要一致要么全链路 UTC要么全链路本地时区不要让 Python 进程、MySQL 会话、定时任务各过各的时间。最后再分享一个小建议把 mysql-connector-python 的版本号写进服务日志或者 /debug 接口。排查连接类问题时第一条信息就是驱动版本。这个库的 API 表面上看和 PyMySQL 差不多但细节行为差异很多正式切换前拿一张核心表压测两天把游标、事务、字符集这些环节都过一遍后续上线会省心很多。
如果你已经在用 Python 连接 MySQL大概率最开始接触的是 PyMySQL而不是 mysql-connector-python——这个由 MySQL 官方团队维护的 Python 驱动。我最初也是 PyMySQL 的长期用户直到一次 MySQL 8.0 升级后线上出现连接异常才认真把 mysql-connector-python 拿来替换替换的结果是应用层代码几乎没改连接稳定性问题少了一大半。这篇文章不是官方文档的复述而是我把这套驱动用在生产环境之后对安装、连接参数、SSL 排查、游标行为、事务与连接池等环节做的实测总结。如果你正准备在 Python 项目里用官方驱动或者遇到了类似连接错误不知道怎么排查这篇应该能帮你少走一些弯路。1. 为什么我在生产环境把 PyMySQL 换成了官方驱动先回答一个很多人会问的问题PyMySQL 用得好好的为什么要换因为用得好好的往往意味着你的业务还没碰到驱动和 MySQL 协议之间的边界。当你开始维护一批 MySQL 8.0 实例跑着高频查询、批量写入、主从切换驱动能不能跟 MySQL 版本迭代同步走就成了一个很现实的问题。1.1 第三方库和官方驱动的真实差距PyMySQL 是纯 Python 实现的 MySQL 协议客户端优点很明显安装零负担、跨平台兼容性好、API 写起来和官方驱动很像。对中小项目、一次性脚本、教学 demo 来说它完全够用。但它是社区维护的MySQL 协议的任何变动都要靠社区维护者手动跟进。举一个具体的例子MySQL 8.0 把默认认证插件从mysql_native_password换成了caching_sha2_password。这个变动刚推出时一大批老版本驱动直接报Authentication plugin caching_sha2_password cannot be loaded。PyMySQL 跟进得算快的但如果你项目里的 PyMySQL 锁了一个老版本时间一长就会踩到这种兼容性坑。mysql-connector-python 是 Oracle 官方维护的驱动MySQL 发布新版本时驱动会同步更新协议行为、认证方式、新特性支持都是第一梯队。出了问题可以去 MySQL 官方 Bugs 系统提 issue也会得到对应版本的修复路径。对一家稳定运行的公司来说这种出了问题有地方说理的价值往往比驱动本身那几个百分点性能差异更重要。1.2 版本和许可证不是每个包都适合你家公司使用pip install mysql-connector-python之前我建议你先搞清楚一个历史遗留问题。早期 Oracle 把驱动分成商业版和社区版PyPI 上出现过mysql-connector-python-ce这个后缀的包。现在官方已经不再单独维护 ce 渠道统一走mysql-connector-python。如果你在旧教程里看到有人让你装 ce 包可以忽略直接装不带后缀的版本。许可证方面要注意mysql-connector-python 使用 GPLv2 with FOSS License Exception。对个人学习、开源项目、公司内部服务来说这个协议基本没有障碍。但如果你所在的公司做闭源商业软件并且打算把驱动打包进对外发布的产品里最好让法务确认一下 License 例外条款的具体边界避免整个产品被卷入 GPL 传染的问题。这个细节平时没人提真出问题就是合规事件。1.3 认证插件和协议更新驱动的版本嗅觉MySQL 8.0 之后的连接层发生过几次重要变化最典型的就是caching_sha2_password认证。这个认证插件在 SSL 加密之外还可以通过 RSA 公钥交换的方式来传输密码。如果驱动太老要么不认识这个认证插件要么在交换公钥时卡住。我遇到过一起线上故障应用服务器上的 Python 驱动是两年前装的MySQL 从 5.7 升级到 8.0 后连接直接报认证插件无法加载。当时第一反应是用户权限问题排查半天才发现是驱动版本太旧根本不认识新的认证方式。更新 mysql-connector-python 到 8.0 对应版本后问题立刻消失。在版本选择上我有一条经验让驱动的小版本号尽量大于或等于 MySQL 服务端的小版本号。比如线上 MySQL 是 8.0.36驱动至少用 8.0.x 里较新的版本。不要拿 8.0.18 的驱动去连 8.0.36 的服务器短连接可能没事长连接和特殊认证场景很容易出幺蛾子。2. 安装与连接参数为什么默认值不能全信驱动换了之后第一个要面对的就是安装和连接参数。这个环节看着简单但我在不同项目里见过太多因为默认参数踩进去的坑。2.1 安装和版本验证安装本身不用多说pip install mysql-connector-python装完之后一定要做版本验证python -c import mysql.connector; print(mysql.connector.__version__)这一步很多人会跳过结果被系统里残留的旧包坑半天。特别是 Debian/Ubuntu 这类系统镜像里可能通过 apt 装过python3-mysql-connector版本经常停在很老的状态。代码明明照着最新文档写一跑就报参数不存在查到最后才发现是 apt 装的旧版驱动。2.2 use_pure 与 C 扩展的取舍mysql-connector-python 和 PyMySQL 的一个关键区别是它同时提供 C 扩展和纯 Python 实现。连接参数use_pure就是控制这个的use_pureFalse优先使用 C 扩展性能更好也是 pip 安装二进制包时的默认行为。use_pureTrue强制纯 Python 实现兼容性更好排查问题时可以用来判断问题到底出在协议层还是 C 扩展层。我实际遇到过一种情况C 扩展的 SSL 上下文在某个精简容器镜像里初始化失败报错指向 SSL 证书路径切到use_pureTrue后居然能连上。虽然最终用配置 SSL 参数解决了但用 use_pure 做二分定位这个思路在排查驱动层疑难杂症时非常有用。还有一个和纯 Python 实现相关的坑纯 Python 模式在连接 MySQL 8.0 的caching_sha2_password用户时可能会依赖cryptography包做 RSA 公钥交换。如果环境里没装这个包会报 Public Key Retrieval 相关错误。解决办法很简单pip install cryptography。2.3 连接参数里最容易出事的三个charset、connect_timeout、ssl先说charset。我建议无论什么场景都显式传charsetutf8mb4不要依赖服务器默认值。否则遇到 emoji、生僻字、特殊符号随时可能报Incorrect string value。这个参数不只是告诉驱动用哪个字符集编码数据还会影响驱动发送给 MySQL 的会话变量显式指定最稳妥。然后是connect_timeout。很多人不设这个参数结果网络发生抖动时connect()一直阻塞在 TCP 握手阶段服务线程被拖死。设置一个合理的值比如 5 到 10 秒能让故障快速暴露并触发重试逻辑而不是无限等待。还有ssl相关参数。MySQL 8.0 默认开启 SSL但服务器用的往往是自签名证书。如果你的 Python 环境没有正确的 CA 证书路径C 扩展初始化可能直接失败。这个坑我在下一章详细展开。2.4 一个最小可用的连接模板我平时写连接代码会直接定义一个函数方便统一管理参数和异常import mysql.connector from mysql.connector import Error def get_connection(): config { host: 192.168.1.100, port: 3306, user: app_user, password: your_password, database: app_db, charset: utf8mb4, connect_timeout: 10, use_pure: False, } try: cnx mysql.connector.connect(**config) return cnx except Error as e: print(fconnect failed: {e}) raise注意我这里没有写autocommit默认 False保持事务由应用主动控制后面的章节会说这是有意的。3. SSL 连接错误排查实录从报错现场到修复的完整链路这一章写给所有遇到过SSL connection error的人。这个错误几乎每个 MySQL 8.0 用户在某个阶段都会撞上一次而且报错信息很有迷惑性。3.1 先看报错长什么样最常见的报错是这种mysql.connector.errors.InterfaceError: 2003: Cant connect to MySQL server on 192.168.1.100:3306 (SSL connection error: SSL_CTX_set_default_verify_paths failed)乍一看像是网络不通实际上网络是通的端口也通问题出在驱动 C 扩展初始化 SSL 上下文时加载系统默认 CA 证书路径失败。换句话说驱动想在握手阶段给服务器做证书验证但找不到可用的证书库文件。在容器环境里这个现象特别多。很多精简容器镜像没有安装ca-certificates包/etc/ssl/certs/ca-certificates.crt这个文件根本不存在。C 扩展调用 SSL 库的默认验证路径初始化函数发现找不到文件直接返回失败。而命令行mysql客户端往往做了降级处理不强制校验所以命令行能连Python 连不上非常割裂。3.2 逐步排查不要上来就改代码遇到这种报错我的排查链路是这样的第一步用命令行客户端测试同一个连接地址mysql -h 192.168.1.100 -u app_user -p如果命令行能连说明网络、账号、权限都没问题问题基本锁定在客户端的 SSL 行为上。第二步连接到 MySQL 后查看服务端 SSL 状态SHOW VARIABLES LIKE have_ssl; SHOW VARIABLES LIKE require_secure_transport;have_ssl为 YES 表示服务端支持 SSLrequire_secure_transport为 ON 表示强制要求安全传输。如果强制开启那客户端不能随意禁用 SSL只能正确配置证书。第三步确认 MySQL 服务器是谁签发的证书。默认安装的 MySQL 用的是自签名证书CA 不在系统信任链里。检查一下服务端配置里的证书路径SHOW VARIABLES LIKE ssl_ca; SHOW VARIABLES LIKE ssl_cert;第四步回到 Python 侧用一种临时绕过的方式验证是不是 SSL 导致的cnx mysql.connector.connect( host192.168.1.100, userapp_user, passwordyour_password, databaseapp_db, ssl_disabledTrue, )这里ssl_disabledTrue在 mysql-connector-python 8.0.13 之后可用。如果这样能连上基本确认就是 SSL 上下文初始化问题。3.3 修复方案和预防建议修复方式取决于你的安全和网络环境。我整理成三种情况场景推荐方案备注内网可信环境不要求强制 SSL连接参数加ssl_disabledTrue最简单但要确认服务器没开require_secure_transport服务器有自签名证书但不想把 CA 加到系统目录显式指定ssl{ssl_ca: /etc/ssl/certs/ca-certificates.crt}前提是文件存在缺了就装ca-certificates生产环境要求完整校验配置ssl_ca为服务器证书对应的 CA 文件并开启ssl_verify_identityTrue最严格适合公网访问数据库的场景在容器镜像里最标准的做法是把ca-certificates装进基础镜像。这个包提供系统级的 CA 信任链不仅让 Python 驱动受益其他依赖 SSL 的组件也能正常工作apt-get update apt-get install -y ca-certificates安装完后再配合显式ssl_ca参数C 扩展就能正常初始化 SSL 上下文。这里要提醒一点ssl_disabledTrue是一个很暴力的方案。如果你是在公网环境连 MySQL千万别为了省事直接关掉 SSL这等于把数据库密码在网络上裸奔。内网测试环境可以用生产环境优先走完整证书配置。4. Cursor 的三种性格默认游标、buffered 与 dictionary 怎么选连接搞定之后真正影响开发效率的是 Cursor 的行为。mysql-connector-python 的游标设计有它自己的脾气不摸清楚很容易写出偶尔报错的代码。4.1 默认游标的 unread result 陷阱官方驱动的默认游标是 unbuffered意思是执行SELECT后结果集并没有一次性拉到客户端内存而是由驱动从服务器逐个取行。这样做的好处是省内存适合读超大结果集。坏处是如果你还没读完上一批结果就同一个连接上执行下一条 SQL会直接报错。我见过最经典的错误写法是这样的cursor.execute(SELECT id FROM user WHERE level 10) row cursor.fetchone() # 拿到第一行后立刻执行下一条 SQL cursor.execute(UPDATE user SET status 1) # 报错报错信息是mysql.connector.errors.InternalError: Unread result found原因是第一次查询还有大量行没消费完同一连接又发起了新语句协议层面根本不允许。解决办法有三种用fetchall()或fetchmany()把结果取完。在execute()之后立刻cursor.close()。创建游标时指定bufferedTrue。4.2 buffered 和 dictionary 什么时候必须开bufferedTrue会把结果集一次性缓冲到客户端比较适合结果集不大、但又需要频繁切换操作的场景。代价是内存消耗我建议单次查询结果超过几万行时不要无脑开 buffered。dictionaryTrue则让每行返回 dict 而不是 tuple字段名访问更清晰。这两个参数可以同时开也可以单独开。游标配置返回形式结果集处理适合场景默认tuple流式取行大结果集、逐行处理bufferedTruetuple全部缓存小结果集、频繁穿插其他 SQLdictionaryTruedict流式取行字段名清晰、可读性优先bufferedTrue, dictionaryTruedict全部缓存常规业务查询我的习惯是日常业务 CRUD 用dictionaryTrue, bufferedTrue代码可读性好也不容易触发 unread result。跑大批量数据导出时用默认游标配合fetchmany(size)分批读内存可控。cursor cnx.cursor(dictionaryTrue, bufferedTrue) cursor.execute(SELECT id, name, created_at FROM t_user LIMIT 1000) for row in cursor: print(row[id], row[name])4.3 参数化查询是技术底线不是加分项这一节内容很简单但我还是想写因为见过太多人在这里省事。mysql-connector-python 的execute()支持参数占位符%s用法如下cursor.execute( SELECT * FROM user WHERE name %s AND age %s, (name, age) )注意占位符是%s不是 SQLite 的?也不是:name。如果你从其他数据库驱动转过来第一次写很容易搞混。永远不要用字符串拼接的方式去构造 SQL# 错误示范千万不要学 cursor.execute(fSELECT * FROM user WHERE name {name})哪怕业务方再三保证输入是合法的也一定不要拼 SQL。参数化不只是防 SQL 注入还能让驱动正确处理字符串转义、类型转换避免很多奇怪的字符集报错。这是技术底线不讨论例外。5. 从跑通到上线事务边界、批量写入、连接池与存储过程写完 CRUD 只是跑通真正上线还需要把事务、性能、连接复用这几个层面处理好。这一章的坑我基本都是踩过一遍才记住的。5.1 事务到底归谁管with 并不自动提交mysql-connector-python 默认autocommitFalse执行INSERT、UPDATE、DELETE之后必须主动调用cnx.commit()这些修改才会真正落库。很多人以为with cnx.cursor() as cur:会像 Python 打开文件一样自动管理事务这是一个很危险的误解。with cnx.cursor()只负责游标的创建和释放不会帮你 commit更不会帮你 rollback。如果代码在 with 块里抛了异常连接关闭时未提交的事务会被回滚但你可能根本不知道。正确的写法是显式控制事务边界try: cursor.execute(UPDATE account SET balance balance - 100 WHERE id 1) cursor.execute(UPDATE account SET balance balance 100 WHERE id 2) cnx.commit() except Exception as e: cnx.rollback() raise还有一点要注意MySQL 的 DDL 语句是隐式提交的。你无法在一个事务里创建表、插入数据、然后全部回滚。事务只对 DML 语句生效设计流程时要有这个预期。事务之外如果两个会话同时更新同一行InnoDB 的行锁会让后到的一方等待Python 端表现为Lock wait timeout exceeded。遇到这个错误大多数时候不是驱动问题而是业务事务太长、锁竞争太激烈优先优化 SQL 和事务范围。5.2 executemany 批量写入到底快多少写日志、埋点、批量同步这些场景都离不开批量插入。mysql-connector-python 的executemany()对 INSERT 语句有专门优化会把多条数据重写成一条批量多值 INSERT减少网络往返。我拿一张 6 个字段的测试表做过对比。插入 5 万行数据逐条execute()加单条 commit耗时约 34 秒改成executemany()加批量 commit耗时约 2.3 秒。同一个环境同一份数据差距超过一个数量级。代码写起来很简单data [ (2024-01-01 10:00:00, 1001, order, create), (2024-01-01 10:00:01, 1002, order, pay), # 更多数据... ] cursor.executemany( INSERT INTO event_log(occur_time, user_id, biz_type, action) VALUES (%s, %s, %s, %s), data ) cnx.commit()这里有个关键点批量数据不要一条一条 commit。你应该在executemany()之后做一次 commit否则性能优化会被频繁提交抵消。如果数据实在太大可以分批执行比如每 5000 行一组每组执行后 commit 一次避免单条事务太大影响 InnoDB 性能。5.3 官方连接池的用法与 wait_timeout 的坑短连接场景下每次请求都新建连接的开销不小连接池是必选项。官方驱动自带连接池不需要额外引入第三方库from mysql.connector import pooling pool pooling.MySQLConnectionPool( pool_nameapp_pool, pool_size5, host192.168.1.100, userapp_user, passwordyour_password, databaseapp_db, charsetutf8mb4, )使用方式也简单cnx pool.get_connection() try: cursor cnx.cursor() cursor.execute(SELECT COUNT(*) FROM user) print(cursor.fetchone()[0]) finally: cnx.close()这里的cnx.close()不是真的关闭底层连接而是把连接归还给连接池。归还之前驱动会尽量重置会话状态避免把上一个会话的变量带出来。连接池最大的坑是 MySQL 服务端的wait_timeout。服务端默认 8 小时清理空闲连接如果连接在池子里闲置过久下次get_connection()拿到的是一个已经被服务端断开的死连接执行第一条 SQL 时报Lost connection to MySQL server during query。我的处理方式是在获取连接后加一次重试机制捕获OperationalError后重建连接再试一次import mysql.connector def get_conn_with_retry(pool, retry2): for i in range(retry): try: cnx pool.get_connection() cnx.ping(reconnectTrue, attempts1, delay0) return cnx except mysql.connector.Error: continue raise RuntimeError(get connection failed)ping(reconnectTrue)会检测连接是否存活如果发现是死连接驱动会尝试重新建立底层连接。这个成本很低但能消除大量偶发的连接中断问题。5.4 存储过程调用callproc 与结果集MySQL 存储过程在 Python 驱动里的调用方式和普通 SQL 不太一样。用callproc()而不是cursor.execute(CALL ...)看一个最小例子result_params cursor.callproc(get_user_order_count, [1001, 0]) print(result_params[1]) # 第二个参数是 OUT 参数调用后返回结果如果存储过程还返回了结果集需要调用cursor.stored_results()来迭代cursor.callproc(get_user_recent_orders, [1001, 5]) for result in cursor.stored_results(): for row in result: print(row)这个用法和返回结果集的行为在官方文档里有描述但很多人会忽视。如果直接用execute(CALL ...), 可能拿不到存储过程产出的多个结果集只能看到最后一个状态。这个差异在接手别人项目代码时尤其容易踩中。6. 返回值类型、字符集与时区驱动里最不显眼的三个坑能正常连上数据库、能读写数据、能跑事务这已经满足大部分需求了。但生产环境里真正让人头疼的往往是数据返回类型和编码时区这些看起来没问题的细节。6.1 类型转换Decimal、datetime 和 JSONmysql-connector-python 的默认类型转换做得比较严谨这点我比较喜欢。MySQL 的DECIMAL字段返回的是 Python 的decimal.Decimal不是 float。很多人第一次拿到会愣一下但这个设计是对的。金额字段如果用 float 处理很容易出现精度丢失。比如 0.1 存进去再读出来float 可能变成 0.1000000000000000055而 Decimal 不会。需要参与数值计算时我记得先转成 Decimal 或者字符串再做运算。DATETIME、TIMESTAMP字段返回的是 Python 的datetime.datetime这一点很省心不需要手动解析字符串。TIME字段返回的是datetime.timedelta。BLOB返回bytesTEXT和VARCHAR返回str。JSON 字段值得单独说。MySQL 的 JSON 在协议层本质上是文本mysql-connector-python 在不同的版本里对 JSON 字段的处理不完全一致。有的版本会帮你自动json.loads成 dict有的版本直接返回字符串。我建议在代码里不要依赖驱动自动转换统一手动处理import json cursor.execute(SELECT payload FROM log_data WHERE id 1) row cursor.fetchone() payload json.loads(row[payload] if isinstance(row[payload], str) else json.dumps(row[payload]))这样写即使驱动升级导致返回类型变化业务代码也不会被影响。6.2 字符集不只是连接参数charsetutf8mb4写在连接参数里只是第一道门。真正要保证不出乱码需要连接、表、列三层的字符集一致。MySQL 8.0 的默认字符集是utf8mb4默认排序规则是utf8mb4_0900_ai_ci。但 5.7 时代很多表建的是utf8mb4_general_ci或者latin1。当 Python 应用用 utf8mb4 连接写入中文和 emoji 时如果目标表的列还是utf8mb3就会报Incorrect string value的错误。解决办法是连接参数和表结构一起调整ALTER TABLE t_user CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;注意大表执行这种 DDL 会锁表或引起主从延迟最好在维护窗口操作。另外utf8mb4_0900_ai_ci和utf8mb4_general_ci的排序规则对某些字符排序可能有差异索引路径也会受影响从 5.7 迁移到 8.0 时要留意这类隐藏变化。6.3 时区导致的一小时事故时区问题不是驱动独有的但在连接层可以提前规避。假设 MySQL 服务器在Asia/ShanghaiPython 应用容器跑在 UTC 时区。直接用 Python 读取TIMESTAMP字段驱动返回的是数据库会话时区解释的时间而 Python 进程里的datetime.utcnow()拿到的是 UTC 时间两边对比时天然差 8 小时。我踩过的一次事故是定时任务判断数据是否超过 30 分钟未更新因为时间比较基准不统一任务整整提前了一小时触发。现在的做法是连接时显式指定时区或者干脆全链路统一 UTCconfig { host: 192.168.1.100, user: app_user, password: your_password, database: app_db, charset: utf8mb4, time_zone: 00:00, }也可以在执行查询前发送SET time_zone 00:00。关键是整个团队的规范要一致要么全链路 UTC要么全链路本地时区不要让 Python 进程、MySQL 会话、定时任务各过各的时间。最后再分享一个小建议把 mysql-connector-python 的版本号写进服务日志或者 /debug 接口。排查连接类问题时第一条信息就是驱动版本。这个库的 API 表面上看和 PyMySQL 差不多但细节行为差异很多正式切换前拿一张核心表压测两天把游标、事务、字符集这些环节都过一遍后续上线会省心很多。
