PyMySQL从入门到实战：连接、游标、事务与报错排查全解析-代码聚汇网

PyMySQL从入门到实战：连接、游标、事务与报错排查全解析

吴思扬·2026-09-06·阅读 123 GEO检测（免费）

PyMySQLPython MySQL数据库连接

|难度：普通|阅读约 48 分钟

跑通一个demo只需要五分钟，真正理解PyMySQL，可能要反复踩几天的坑。这不是吓唬你，而是我见过太多人在本地跑通示例后，一遇到真实业务就卡住：明明代码看着没问题，就是报错；明明查询结果就在那里，就是取不出来；明明insert执行成功了，数据就是没写进表里。这些问题十有八九都出在连接参数、游标机制、事务提交这些“看起来简单”的地方。

这篇教程的目的，就是把PyMySQL从连接到增删改查的完整路径走一遍，然后把每个关键API背后的运行原理讲清楚。顺手把新手最容易遇到的报错和坑提前列出来，你能少走很多弯路。内容适合刚学Python、需要操作MySQL写作业或做小系统的同学，也适合那些用了一段时间但总感觉“哪里没搞明白”的开发者。

1. 为什么第一门MySQL客户端库我推荐PyMySQL

在开始写代码之前，先花点时间说说选型问题。很多人上来就问“Python连MySQL用什么库”，结果搜出来一堆名字：PyMySQL、MySQLdb、mysql-connector-python、SQLAlchemy……容易看晕。

1.1 PyMySQL和几个常见方案的对比

我个人的结论很直接：如果你是初学者，或者项目规模不大，直接用PyMySQL就对了。

先看一个横向对比表格：

选项	实现方式	安装体验	API风格	适用场景
PyMySQL	纯Python	pip直接装，零依赖	简洁直观	入门学习、中小项目、脚本工具
MySQLdb	C扩展	需要编译，Windows上容易出问题	老派但成熟	维护老项目、追求极致性能
mysql-connector-python	官方提供	pip可装但包比较大	参数命名偏官方风格	需要官方支持、特殊功能
SQLAlchemy	ORM（也含Core）	pip安装	两个层面，学习曲线陡	大型项目、需要对象映射

MySQLdb在Python 2时代确实是主流，但它依赖C扩展编译，你在Windows上装它可能需要先解决编译器的问题。我自己早年就被这个折腾过，后来转投PyMySQL，体验瞬间清爽——pip install pymysql一条命令搞定，不需要编译任何东西，跨平台表现一致。

mysql-connector-python虽然顶着“官方”的名头，但它的安装包更大，而且API风格和Python社区的习惯略有出入。不是说它不好，而是在“快速上手”这个目标下，PyMySQL的写法更顺手。

SQLAlchemy是另一回事，它是个ORM框架，可以直接写SQL用它的Core部分，但那套Session、Engine的抽象对新手来说有点重。如果你只是想快速操作MySQL，这种重量级武器反而增加了心智负担。

1.2 什么场景适合直接选PyMySQL

PyMySQL最适合下面几类场景：

本地脚本、数据分析脚本需要读MySQL数据
Flask、Django、FastAPI等Web项目要用MySQL，又不想上重型ORM
写运维自动化工具，需要批量更新数据库
学习阶段想搞懂SQL语句本身，而不是被对象映射掩盖掉SQL细节

另外提一句，Tornado等异步框架里还有aiomysql这类异步库，但那是异步入门之后的事了。先把PyMySQL这个同步库玩明白，异步库的很多概念也能迁移。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备：从零跑到第一段可执行代码

选好了库，下面进入实际操作。这一步很多人会跳过去直接抄代码，但我的建议是，花几分钟把环境一次性弄干净，后面会顺畅很多。

2.1 安装与版本确认

Python版本建议3.7以上，PyMySQL新版本对3.8、3.9、3.10、3.11、3.12都做了兼容。安装很简单：

bash复制pip install pymysql

如果是在国内网络环境，可以用镜像源加速：

bash复制pip install pymysql -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后验证一下：

bash复制python -c "import pymysql; print(pymysql.__version__)"

正常会输出一个版本号，比如1.1.0。如果这里抛了ModuleNotFoundError，大概率是pip和python不是同一个环境。这种情况在macOS和Linux上很常见，两个python在系统中并存，pip装给了其中一个，命令行跑的是另一个。解决办法是用python -m pip install pymysql，保证装的模块和执行的解释器是同一个环境。

2.2 准备数据库和表结构

在写Python代码之前，先确保MySQL服务本身是能连上的。你可以用任何你习惯的客户端，先建一个库和一张表，用来做后面的测试。我这里用MySQL命令行演示：

sql复制CREATE DATABASE IF NOT EXISTS demo_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

USE demo_db;

CREATE TABLE IF NOT EXISTS users (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL UNIQUE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

注意字符集一定要用utf8mb4，而不是utf8。utf8在MySQL里实际上是utf8mb3，存不了emoji，也容易在一些生僻字上报错。这个细节在你第一次处理用户输入带表情符号的数据时就会体现出来。

2.3 第一个可运行Demo

环境都准备好了，写一段最小可运行demo：

python复制import pymysql

# 建立连接
conn = pymysql.connect(
    host='127.0.0.1',
    port=3306,
    user='root',
    password='your_password',
    database='demo_db'
)

try:
    # 创建游标
    cursor = conn.cursor()

    # 执行SQL
    cursor.execute("SELECT VERSION() AS version")
    row = cursor.fetchone()

    # 获取结果
    print("MySQL版本:", row[0])

    # 关闭游标
    cursor.close()
finally:
    # 关闭连接
    conn.close()

这段代码虽然简单，但它包含了所有PyMySQL程序的基本骨架：建立连接、创建游标、执行SQL、获取结果、关闭游标、关闭连接。

我见过不少新手只写连接和查询，不关闭连接，在脚本里跑一次没问题，但如果是