简介mysql-connector-python-2.1.7.tar.gz 是 MySQL 官方推出的 Python 数据库适配器源码包面向需要在 Python 项目中访问和管理 MySQL 的开发者尤其适合使用 Python 2.x 或 3.x 进行数据交互、后端开发与脚本编写的中级学习者。该适配器遵循 DBAPIPEP 249规范提供连接管理、事务处理、游标操作、结果集处理、类型映射、连接池及错误异常处理等能力并支持多种认证插件便于在本地或远程环境中快速接入数据库。压缩包共 123 个文件约 11.24MB以 90 个 py 源码文件为主体另含 pem 证书、cnf 配置、h 与 c 底层实现文件及少量 txt、csv 说明数据结构完整便于阅读源码与二次编译安装。目前已有 364 人学习下载。通过该资源读者可获取 2.1.7 版本完整源码理解适配器内部实现与接口设计并借助示例代码完成连接、查询、批处理等常见数据库操作为项目排错与性能优化提供参考。1. 从 mysql-connector-python-2.1.7.tar.gz 说起一个老版本驱动包为什么还在被翻出来如果你在 Python 项目里连 MySQL大概率用过mysql-connector-python。但当你看到mysql-connector-python-2.1.7.tar.gz这个文件名时说明你面对的不是pip install mysql-connector-python就能搞定的场景——你手里是一个源码分发包需要自己解包、编译、安装而且版本锁定在 2.1.7。这个版本对应的是 MySQL Connector/Python 的早期 2.x 系列纯 Python 实现不依赖 MySQL 的 C 客户端库兼容 Python 2.7 和 Python 3.4 以上的环境。为什么现在还有人翻出这个包常见原因是内网离线环境、老系统迁移、CI 镜像里预置了固定版本或者某个遗留项目锁死了依赖树。这篇文章不讲泛泛的驱动介绍而是把mysql-connector-python-2.1.7.tar.gz从解包到跑通查询、再到参数调优和踩坑排查的完整路径拆开让你拿到这个 tar.gz 之后知道每一步该做什么、为什么这么做、哪里容易翻车。适合正在维护老 Python 项目、需要在隔离环境部署数据库连接、或者单纯想搞清楚源码包安装和 pip 安装差异的从业者。2. 解包与安装从 tar.gz 到可 import 的模块2.1 先看清包里的目录结构再动手拿到mysql-connector-python-2.1.7.tar.gz之后不要急着pip install。先解包看一眼顶层目录这一步能帮你判断这个包是纯源码还是带了预编译产物。执行tar -tzf mysql-connector-python-2.1.7.tar.gz | head -30你会看到类似mysql-connector-python-2.1.7/的顶层目录下面通常有setup.py、README.txt、LICENSE.txt以及mysql/connector/这个核心包目录。2.1.7 版本是纯 Python 实现mysql/connector/下会包含connection.py、cursor.py、protocol.py、conversion.py等模块没有.so或.pyd文件。这意味着安装过程不需要编译 C 扩展理论上任何有 Python 解释器的环境都能装。确认目录结构后解包到工作目录tar -xzf mysql-connector-python-2.1.7.tar.gz cd mysql-connector-python-2.1.7 ls -la此时你处在源码根目录下一步是选择安装方式。这里有一个关键分叉用python setup.py install还是pip install .。两者最终都会把mysql.connector包放进 site-packages但pip install .会生成.egg-info并记录依赖元数据后续pip list能看到版本号setup.py install在老版本 setuptools 下可能只复制文件不注册元数据。我一般优先用pip install .除非目标环境的 pip 版本太老不支持本地目录安装。2.2 用 pip 从源码目录安装并验证 import进入解包后的目录执行pip install .如果你需要装到指定 Python 解释器下把pip换成对应的pip3或python -m pip。安装完成后立刻验证import mysql.connector print(mysql.connector.__version__)预期输出2.1.7。如果报ModuleNotFoundError先检查pip show mysql-connector-python是否列出了安装路径再确认当前 Python 解释器和 pip 是否匹配。常见翻车场景是系统里有多个 Pythonpip装到了 Python 3.6 的 site-packages但你运行脚本用的是 Python 3.9。参数说明pip install .默认会尝试从 PyPI 拉取依赖但 2.1.7 版本本身没有强制外部依赖所以离线环境下加--no-index --no-build-isolation也能装pip install . --no-index --no-build-isolation--no-build-isolation让 pip 使用当前环境已有的 setuptools而不是临时创建隔离环境去下载构建依赖这在没有外网的内网机器上是必须的。--no-index禁止访问包索引避免 pip 因为找不到索引而超时。2.3 离线环境下的依赖检查与手动补齐虽然 2.1.7 是纯 Python 实现但setup.py里可能声明了protobuf之类的可选依赖用于某些特性。安装前先看一眼grep -i install_requires setup.py如果输出为空或只有注释说明没有强制依赖。如果有内容你需要提前把对应版本的 wheel 或 tar.gz 下载到本地用pip install xxx.whl先装好再装 connector。离线环境下不要指望 pip 自动解决依赖它只会报错然后回滚。另一个容易忽略的点是 Python 版本。2.1.7 官方支持 Python 2.7 和 3.4但在 Python 3.10 以上环境里setup.py里可能用了已被移除的distutils模块。如果你在较新 Python 上安装报ModuleNotFoundError: No module named distutils解决办法是安装对应 Python 版本的setuptools和wheel或者用python -m ensurepip修复基础环境。这不是 connector 本身的问题而是构建工具链的兼容性问题。3. 连接与查询2.1.7 版本的核心 API 怎么用3.1 建立连接时必须显式指定的四个参数mysql.connector.connect()在 2.1.7 里的参数签名和后续 8.x 版本有差异最明显的是auth_plugin和use_pure的默认值。一个能跑通的最小连接示例import mysql.connector config { host: 127.0.0.1, port: 3306, user: app_user, password: app_pass, database: app_db, charset: utf8mb4, use_unicode: True, connection_timeout: 10, } conn mysql.connector.connect(**config) print(conn.is_connected()) conn.close()逻辑说明host和port指定 MySQL 实例地址user和password是认证凭据database在连接时直接选中库省去后续USE语句charset设为utf8mb4是为了支持完整的 Unicode 字符集2.1.7 默认字符集可能是latin1不显式指定会在插入中文或 emoji 时出问题use_unicodeTrue确保返回的字符串是 Python 的str而不是bytesconnection_timeout单位是秒默认值在不同平台上不一致显式设置能避免连接阶段无限等待。参数怎么改如果 MySQL 服务端要求 SSL2.1.7 支持ssl_ca、ssl_cert、ssl_key三个参数但配置方式比较原始需要传入文件路径。如果服务端使用caching_sha2_password认证插件MySQL 8.0 默认2.1.7 版本可能不支持会报Authentication plugin caching_sha2_password is not supported。解决办法是在 MySQL 侧把该用户的认证插件改为mysql_native_password或者升级 connector 版本。这是 2.1.7 最典型的版本边界。3.2 用游标执行查询并处理结果集连接建立后所有 SQL 操作通过游标进行。2.1.7 支持普通游标和字典游标cursor conn.cursor(dictionaryTrue) cursor.execute(SELECT id, name, created_at FROM users WHERE status %s, (active,)) rows cursor.fetchall() for row in rows: print(row[id], row[name], row[created_at]) cursor.close()逻辑说明dictionaryTrue让每一行结果以字典形式返回键是列名值是对应数据比默认的元组形式可读性高很多。execute的第二个参数是一个元组用于填充 SQL 里的%s占位符。注意 2.1.7 只支持%s占位符不支持?或:name命名参数。fetchall()一次性取回所有结果如果结果集很大内存会飙升此时应该用fetchmany(size500)分批取。参数说明cursor.execute()返回的是受影响行数对SELECT语句来说这个值在 2.1.7 里可能不准确不要依赖它判断查询结果数量应该用fetchall()后的len(rows)。cursor.rowcount属性在SELECT后返回的是-1或实际行数取决于 MySQL 服务端版本和缓冲模式同样不建议依赖。3.3 事务提交与回滚在 2.1.7 里的默认行为2.1.7 默认autocommitFalse这意味着INSERT、UPDATE、DELETE之后必须显式调用conn.commit()否则数据不会落库连接关闭时自动回滚。这是一个高频翻车点try: cursor conn.cursor() cursor.execute(INSERT INTO logs (msg) VALUES (%s), (test,)) conn.commit() except mysql.connector.Error as err: conn.rollback() print(fError: {err}) finally: cursor.close() conn.close()逻辑说明try块里执行写操作后立即commit()如果中途抛异常except块捕获mysql.connector.Error并执行rollback()保证事务原子性finally块确保游标和连接被关闭避免连接泄漏。2.1.7 的Error类是所有 connector 异常的基类捕获它就能覆盖连接错误、SQL 语法错误、权限错误等。参数说明如果你希望每条语句自动提交可以在连接配置里加autocommit: True但这样会失去事务回滚能力只适合日志类写入场景。对于业务数据保持autocommitFalse并手动管理事务是更稳妥的做法。4. 避坑与排查2.1.7 版本特有的五个高频问题4.1 现象连接时报 “2003: Cant connect to MySQL server”原因网络不通、MySQL 未启动、端口被防火墙拦截或者host填了localhost但 MySQL 只监听 Unix socket 而非 TCP。2.1.7 在localhost场景下会优先尝试 Unix socket如果 socket 文件路径不对就会报 2003。解决先用telnet 127.0.0.1 3306或nc -zv 127.0.0.1 3306确认 TCP 可达。如果可达把连接配置里的host从localhost改成127.0.0.1强制走 TCP。如果 MySQL 只开了 socket找到my.cnf里的socket路径在连接参数里加unix_socket/var/lib/mysql/mysql.sock。4.2 现象插入中文后查询出来是乱码或问号原因连接字符集、数据库字符集、表字符集三者不一致。2.1.7 默认连接字符集可能是latin1即使数据库是utf8mb4驱动层也会把中文按 latin1 编码发送导致存储乱码。解决连接配置里显式写charset: utf8mb4同时确认数据库和表的字符集SHOW CREATE DATABASE app_db;和SHOW CREATE TABLE users;。如果表还是latin1需要ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;。三处统一之后乱码问题消失。4.3 现象cursor.execute()执行带%的 LIKE 语句报格式化错误原因2.1.7 的execute()会把 SQL 里的%当作参数占位符处理如果你写WHERE name LIKE %abc%驱动会认为有两个%s占位符但没提供参数抛出IndexError或TypeError。解决把%转义为%%写成WHERE name LIKE %%abc%%或者用参数化方式cursor.execute(SELECT * FROM users WHERE name LIKE %s, (%abc%,))。推荐后者既避免转义问题又防止 SQL 注入。4.4 现象长时间空闲后连接失效报 “MySQL Connection not available”原因MySQL 服务端的wait_timeout默认 8 小时连接池或长连接超过这个时间没活动服务端会主动断开。2.1.7 没有内置连接池的自动重连机制连接断开后再次使用就会报错。解决在连接配置里加connection_timeout: 10和autocommit: True不能解决这个问题。正确做法是捕获异常后重建连接或者用conn.ping(reconnectTrue)在每次使用前探测try: conn.ping(reconnectTrue, attempts3, delay1) except mysql.connector.Error: conn mysql.connector.connect(**config)ping(reconnectTrue)会尝试重连attempts指定重试次数delay是每次重试间隔秒数。注意这个调用本身有开销不要在高频循环里每次都用。4.5 现象安装时setup.py报SyntaxError或InvalidRequirement原因2.1.7 的setup.py里可能用了老式 setuptools 语法在新版 setuptools60下解析失败。或者 Python 版本太新setup.py里的print语句没有加括号Python 2 风格。解决先确认 Python 版本python --version。如果是 Python 3.10尝试降级 setuptools 到 50.x 以下pip install setuptools49.6.0。如果还不行直接绕过setup.py手动把mysql/connector/目录复制到 site-packages 下python -c import site; print(site.getsitepackages()[0]) cp -r mysql/connector /usr/lib/python3.x/site-packages/mysql/手动复制不会注册包元数据pip list看不到但import mysql.connector能正常工作。这是离线环境下的后悔药不到万不得已不用。5. 进阶技巧用 2.1.7 跑批量写入和连接复用的具体参数5.1 批量插入时executemany的批大小怎么定2.1.7 支持cursor.executemany()但它的实现是逐条拼接 SQL 再一次性发送不是真正的批量协议。这意味着批大小太大反而会撑爆max_allowed_packet。我一般把批大小控制在 500 到 1000 条之间data [(fuser_{i}, i) for i in range(10000)] cursor conn.cursor() batch_size 500 for i in range(0, len(data), batch_size): batch data[i:i batch_size] cursor.executemany(INSERT INTO users (name, age) VALUES (%s, %s), batch) conn.commit() cursor.close()逻辑说明把 10000 条数据切成 500 条一批每批执行一次executemany并提交。这样单次 SQL 包大小可控不会触发max_allowed_packet错误同时每批提交一次减少事务日志压力。参数怎么改如果单条数据字段多、体积大把batch_size降到 200如果字段少且都是短字符串可以提到 2000。观察 MySQL 的max_allowed_packet值SHOW VARIABLES LIKE max_allowed_packet;确保单批数据量不超过这个值的 80%。5.2 连接复用的正确姿势与验证方法2.1.7 没有连接池但你可以自己维护一个长连接对象在每次操作前ping一次。验证连接是否真正复用可以在 MySQL 侧查SHOW PROCESSLIST;看连接 ID 是否保持不变import mysql.connector import time config {host: 127.0.0.1, user: app_user, password: app_pass, database: app_db} conn mysql.connector.connect(**config) for i in range(3): conn.ping(reconnectTrue) cursor conn.cursor() cursor.execute(SELECT CONNECTION_ID()) cid cursor.fetchone()[0] print(fRound {i}, connection id: {cid}) cursor.close() time.sleep(2) conn.close()如果三次输出的connection id相同说明连接被复用如果不同说明ping触发了重连。ping(reconnectTrue)在连接可用时不会重建只有检测到断开才重连。这个验证方法比看日志更直接。5.3 一个我踩过的坑use_pure参数在 2.1.7 里没有实际效果2.1.7 是纯 Python 实现没有 C 扩展版本所以use_pure参数无论设True还是False都走同一套代码路径。我在一个项目里花了半小时排查为什么设了use_pureFalse性能没变化后来翻源码才发现这个版本根本没有 C 扩展。如果你需要 C 扩展的性能得换到mysql-connector-python的 8.x 版本并安装mysql-connector-python-rf或使用PyMySQLcryptography的组合。2.1.7 的定位就是纯 Python、跨平台、零编译依赖性能不是它的强项。希望帮到你。本文还有配套的精品资源点击获取