pymysql,一个纯粹的 Python 库

大家好，我是木木。

今天给大家分享一个纯粹的 Python 库，pymysql。

pymysql

同样是连接 MySQL/MariaDB，pymysql 的特点很明确：纯 Python、好安装、跨平台省心。它实现了 DB-API 2.0，很多同步项目可以用它替代需要 C 扩展的驱动。它不一定是性能最强的选择，但在脚本、内部工具、小中型同步服务、部署环境受限的机器上，常常是更轻松的那一个。

项目地址：https://github.com/PyMySQL/PyMySQL

官方文档：https://pymysql.readthedocs.io/

三大特点

纯 Python

安装时不依赖本机编译 MySQL C 客户端，Windows、Linux、容器环境都更容易落地。

接口兼容

遵循 DB-API 2.0，连接、游标、参数绑定等写法和常见数据库驱动接近。

配置清楚

字符集、超时、游标类型都能显式配置，适合脚本和服务端项目统一封装。

最佳实践

安装方式：pip install PyMySQL。

第一段代码解决的问题是：构造一份连接配置，并验证字符集、数据库名和游标类型。这里使用延迟连接，不会访问本机 MySQL。

importpymysqlfromimportlib.metadataimportversionfrompymysql.cursorsimportDictCursorconn=pymysql.connections.Connection(host="127.0.0.1",user="app",password="secret",database="shop",defer_connect=True,charset="utf8mb4",cursorclass=DictCursor,connect_timeout=3,)print("package:",version("PyMySQL"))print("target:",conn.host,conn.port)print("database:",conn.db.decode()ifisinstance(conn.db,bytes)elseconn.db)print("charset:",conn.charset)print("cursor:",conn.cursorclass.__name__)

第二段看转义工具。正式查询仍然应该交给参数化执行，但本地了解转义行为，可以帮助你排查字符串、引号和编码问题。

frompymysql.convertersimportescape_item,escape_string,encodersprint("name:",escape_string("O'Reilly"))print("city:",escape_string("Shenzhen"))print("number:",escape_item(42,"utf8mb4",encoders))

进阶场景看游标选择。列表页、导出任务和大结果集处理方式不同，提前选对 cursor，可以减少后续封装成本。

frompymysql.cursorsimportCursor,DictCursor,SSCursor,SSDictCursorforcursorin[Cursor,DictCursor,SSCursor,SSDictCursor]:print(cursor.__name__)

环境与版本信息

本文示例使用 Python 3.11，PyMySQL 版本为 1.1.3。当前包声明 Python 版本要求为 3.9 及以上，无需本地 C 编译环境。

适用场景

适合内部脚本、小型同步服务、部署环境不方便编译 C 扩展的项目，以及需要快速连接 MySQL/MariaDB 的 Python 工具。

不适用场景

如果服务非常重视同步驱动性能，可以对比 mysqlclient。若项目是 async 技术栈，应优先看异步 MySQL 驱动，而不是在事件循环里直接跑同步连接。

上线检查

1. 使用参数化查询，不要把用户输入拼进 SQL。
2. 设置连接、读取、写入超时，并使用连接池或统一连接管理。
3. 确认字符集使用 utf8mb4，避免表情和特殊字符写入失败。

总结

pymysql 的优势是轻和省心。它让 Python 项目连接 MySQL 更容易部署，但生产里依然要认真处理连接池、事务、超时和参数化查询。