PyMySQL数据库操作实战：从安装连接到事务与避坑完全指南

PyMySQL这名字，你在搜索引擎里一敲，满屏都是“快速入门”“基础教程”。说实话，这类文章我也看过不少，但大多要么是官方文档的机翻精简版，要么是只教你怎么跑通个select就没了下文。今天这篇，我不打算给你念API文档，而是以一个被我用来做过生产环境数据迁移、爬虫数据落地、甚至给公司临时报表系统当过存储层的实战者的角度，把PyMySQL从安装到事务处理、再到坑点排查，给你梳理出一条能直接照着做的路径。无论你是刚接触Python数据库编程的新手，还是用惯了SQLAlchemy想回头看看原生驱动到底怎么工作的老手，这篇文章都能让你少走弯路。先说清楚一件事：PyMySQL是一个纯Python实现的MySQL客户端库，它的存在意义就是你不需要在系统里装一堆复杂的MySQL C语言依赖，pip安装就能用。这一点，在某些不方便安装编译环境的服务器上，简直是救命的优势。

1. 连接数据库前的那些准备功夫

1.1 为什么选择纯Python实现的PyMySQL

早期Python操作MySQL，主流选择是MySQLdb，但这个东西在Python 3时代的安装过程堪称噩梦，需要编译，还得匹配一堆底层库版本。后来PyMySQL逐步成为了主流选择，关键就在于它用纯Python实现了MySQL通信协议。这意味着，只要你有个Python环境，pip install pymysql之后就能直接干活，完全绕开了复杂的编译环境兼容性问题。尤其在那些生产环境、精简容器或者内网离线机房，安装一个纯Python包比编译一个C扩展容易太多了。

PyMySQL的效率够不够用？大部分业务场景，尤其是爬虫数据存储、中小型Web应用后端、数据分析前置落库，它的性能完全够用。当然，如果你的业务是每日几亿写入、需要极端并发优化的场景，那可能得考虑使用异步库要么用C扩展类库，比如用mysqlclient或者走ORM加连接池方案。但在95%的日常场景里，PyMySQL的同步阻塞模型简单直接，也容易排查问题。

1.2 安装和环境准备细节

安装这块本来没什么好讲的，但我想强调一下虚拟环境的问题。我自己就曾经图省事，直接往系统Python环境里装了一堆包，结果有一次升级系统自带的Python版本，把整个环境搞崩了。从那以后，我所有项目都会新建虚拟环境再安装。

Python 3.7及以上版本直接执行：

bash复制python3 -m venv venv
source venv/bin/activate   # Windows下是 venv\Scripts\activate
pip install pymysql

如果你需要处理JSON类型字段或者使用认证插件，推荐安装较新版本。安装后验证一下版本：

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

这里有个常见的小问题：如果你之前安装过旧版PyMySQL，升级到新版后部分连接参数名有改动。比如老版本里charset参数写“utf8”，新版虽然还兼容，但MySQL 8.0及以上官方推荐的是“utf8mb4”，这不仅仅是字符集名称的变化，而是直接关系到你能不能存得下emoji表情和小众语言文字。这点下一节会展开说。

1.3 连接参数的逐个解读

建立连接看起来简单，就是传入主机、端口、用户名、密码、数据库名这五件套。但有几个参数在实际使用中特别容易被忽略，等出了问题才恍然大悟。

connect_timeout就是重灾区。默认情况下，这个值如果是10秒，一旦网络有波动或者数据库负载高，你的程序就可能在创建连接时直接卡住十几秒甚至报超时。我一般会配置为5秒，宁可快速失败走重试逻辑，也不要在连接上无限等待。

另外read_timeout和write_timeout这两个参数是MySQLdb时代大家不怎么关注的，但在PyMySQL里它们控制着一次读或写操作的超时时间。对于执行那种复杂报表查询，跑个几十秒很正常，这时候read_timeout不能设太短，否则SQL还没执行完，客户端就先放弃了。建议根据你最慢的那个查询耗时再上浮50%来设置。

autocommit这个参数我要特别提一下。PyMySQL默认autocommit是False，理解这一点非常重要。这直接关系到数据一致性。有些新手用它做insert之后，另一段代码立刻select却查不到数据，折腾半天发现是没commit。很多老手推荐在创建连接时显式开启autocommit=True，避免所有事务都要手动提交。但这个看场景。如果你用事务做复杂业务写入，特别是多条DML需要原子性时，建议还是手动控制。我个人的习惯是：简单场景开启autocommit，复杂业务逻辑里全手动控制事务。核心意图是，你要清楚你的数据在什么时刻变得可见。

端口号是3306，这一点不用多说了，但要注意：如果数据库跑在Docker容器里，你映射的宿主机端口很可能不是3306，而是33060这种随机映射。排查半天连接不上，最后发现是端口映射错了的情况我见过不少。

2. 核心操作里的门道和注意事项

2.1 连接管理和游标使用的最佳实践

看官方文档入门示例，大家很容易写成这样：每次查询就去connect一下，用完也不关连接。这在学习阶段没问题，可一旦上了生产环境就是灾难。MySQL服务端的最大连接数默认是151，每一个连接都会占用服务端内存，如果并发一上来，连接数瞬间被占满，数据库直接拒绝服务。

更好的做法是，把创建连接和关闭连接用上下文管理器包起来，确保连接必然被销毁。PyMySQL本身就支持with语法，连接对象和游标对象都可以作为上下文管理器使用。有一点要特别注意：Connection作为上下文管理器时，退出with块只会提交或回滚事务，但不会关闭连接。Cursor作为上下文管理器时，退出with块会关闭游标，但不会关闭连接。这个细节很多人不知道，误以为用with就一定不会有连接泄漏。

所以我的推荐模式是连接用with管理，游标也显式关闭，或者在连接关闭前确保游标全部被close掉。代码如下：

python复制import pymysql

config = {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "root",
    "password": "your_password",
    "database": "test_db",
    "charset": "utf8mb4",
    "connect_timeout": 5,
    "autocommit": False,
}

with pymysql.connect(**config) as conn:
    with conn.cursor() as cursor:
        cursor.execute("SELECT version()")
        result = cursor.fetchone()
        print(result[0])

注意，这个例子中conn的with块在退出时会自动提交事务，等效于调用了conn.commit()，但不会自动关闭连接。如果想要完全自动管理，还得再包裹一层try/finally或者在退出后手动conn.close()。我在下面的章节会给出一个更完整的封装。

2.2 参数化查询是底线，不是建议

我知道有些人习惯用f-string拼接SQL，比如：

python复制sql = f"SELECT * FROM users WHERE name = '{name}'"

这确实是很多新手教程里的写法，但这绝对是个必须改掉的坏习惯。如果你只是自己学习连的是一个本机测试库，那短时间看不出问题。但只要这个逻辑暴露在了任何用户可输入的入口，这就是一个标准SQL注入漏洞。别人输入一个' OR '1'='1，你整张表都给人看得干干净净，如果再加上多语句执行能力，拖库删库都是一瞬间的事。

PyMySQL官方推荐的写法是百分号占位符格式，注意不是Python字符串格式化，而是把参数作为第二个位置参数传给execute方法：

python复制sql = "SELECT * FROM users WHERE name = %s AND age > %s"
cursor.execute(sql, (name, age))

这样驱动会先对参数做转义，再拼接到SQL中发送给服务端，从机制上杜绝了注入问题。这里有个容易踩坑的地方：占位符使用的是%s，不管你的字段是字符串、整数还是浮点数，全部用%s。这一点和Python字符串格式化的%s是一样符号但完全不同逻辑，写错了类型基本不会报错，驱动会帮你处理好。

如果插入多条数据，也不必一条一条execute，executemany会更高效：

python复制data = [("张三", 25, "北京"), ("李四", 30, "上海")]
sql = "INSERT INTO users(name, age, city) VALUES (%s, %s, %s)"
cursor.executemany(sql, data)

executemany在底层实际上是将多条相同的SQL循环执行，只是省掉了Python层的多次调用开销，在数据量几千到几万条时可以明显感受到效率提升。

2.3 增删改查的细节处理和返回值

select操作通过fetchone、fetchmany、fetchall三种方法获取结果。它们的使用场景是不同的。fetchall会一次性把所有记录加载到内存中，这在查询结果集比较小的场景下最方便。但如果你的查询返回几十万条记录，fetchall会把内存撑爆，此时正确的做法是使用fetchmany分批获取，每次取1000条处理完再取下一批。

delete和update是危险操作，我建议在开发阶段就养成一个习惯：写DML语句时先拿select确认一下影响范围。比如你要删除某个时间点之前的数据，先跑一遍select count(*)看看有多少条，确认无误之后再执行delete。这看着多一步，实际能避免的灾难比你想的大得多。

关于update和delete的影响行数，你可以通过cursor.rowcount属性获取。这个属性返回的是被修改的行数。但注意一个细节：MySQL默认驱动中，UPDATE语句如果更新后的值与原值相同，rowcount返回的是0而不是1。这在某些需要幂等操作的逻辑中会产生误导。如果你确实需要MySQL返回“匹配行数”而不是“变更行数”，可以在连接URL中设置client_flag参数，但一般不建议这么做，而是要在应用层理解这个行为。

执行完增删改之后，获取自增主键ID是另一个高频需求。比如插入一个用户之后，马上要用这个用户的ID去写入订单表。此时使用cursor.lastrowid即可获得：

python复制sql = "INSERT INTO users(name) VALUES (%s)"
cursor.execute(sql, ("王五",))
new_id = cursor.lastrowid

这里有一个隐含前提：表的主键字段必须是AUTO_INCREMENT，lastrowid返回的才是新插入的自增值。如果不是自增主键而是一个业务生成的ID，lastrowid拿到的是0或者不对的值，需要你自己捕捉生成的主键。

3. 让PyMySQL更顺手：封装与常用的进阶用法

3.1 一个可直接复用的数据库操作封装类

在实际项目中，我不可能每次用到数据库就写一大段连接代码。我会把数据库连接和基础操作封装成一个工具类，放到整个项目的utils模块里。下面这个封装类我用了很长时间，适合中小型项目直接抄作业：

python复制import pymysql
from pymysql.cursors import DictCursor

class DB:
    def __init__(self, **config):
        self.config = config
        self.conn = None

    def __enter__(self):
        self.conn = pymysql.connect(**self.config)
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        try:
            if exc_type:
                self.conn.rollback()
            else:
                self.conn.commit()
        finally:
            self.conn.close()

    def query(self, sql, args=None):
        with self.conn.cursor(DictCursor) as cursor:
            cursor.execute(sql, args)
            return cursor.fetchall()

    def query_one(self, sql, args=None):
        with self.conn.cursor(DictCursor) as cursor:
            cursor.execute(sql, args)
            return cursor.fetchone()

    def execute(self, sql, args=None):
        with self.conn.cursor() as cursor:
            affect_rows = cursor.execute(sql, args)
            return affect_rows, cursor.lastrowid

# 使用示例
config = {
    "host": "127.0.0.1",
    "user": "root",
    "password": "123456",
    "database": "test_db",
    "charset": "utf8mb4",
    "autocommit": False,
}

with DB(**config) as db:
    rows = db.query("SELECT * FROM users WHERE age > %s", (20,))
    print(rows)

这个封装的关键在于把“事务提交/回滚”和“连接关闭”放在了上下文管理器的退出逻辑里，业务代码不需要关心这些基础设施。但我必须提醒你，这个封装中的execute可以执行insert、update、delete和DDL语句。由于DDL语句在MySQL中会隐式提交事务，这意味着如果你在一个事务中先执行了create table再执行insert，然后后面某个update失败了触发rollback，你会发现DDL操作无法回滚，insert也正常提交了。这个行为是MySQL本身的设计，不是PyMySQL的问题。在实际项目中不要在一个手动事务里混用DDL和DML。

3.2 事务控制和隔离级别的实际经验

事务这块，很多教材都是概念讲得飞起，可真到了现场还是不知道该在什么时候commit、什么时候rollback。典型场景：一个转账操作，从A账户扣款，向B账户加款，这两个SQL必须打包成一个事务，要么全部成功，要么全部失败。

PyMySQL事务控制的关键点是：不要在每次cursor.execute之后立刻commit，而是在所有业务操作成功结束后统一commit，一旦任意一环抛出异常就rollback。

python复制conn = pymysql.connect(**config)
try:
    with conn.cursor() as cursor:
        cursor.execute("UPDATE account SET balance = balance - 100 WHERE id = %s", (1,))
        cursor.execute("UPDATE account SET balance = balance + 100 WHERE id = %s", (2,))
    conn.commit()
except Exception as e:
    conn.rollback()
    raise e
finally:
    conn.close()

MySQL默认的事务隔离级别是Repeatable Read，这在绝大多数业务场景下都没问题。有一点必须清楚，在默认隔离级别下，同一个事务内两次相同的select查询，结果是一致的，即使期间其他事务已经提交了新的数据。这个特性保证了你做统计报表类操作时会得到一个一致性的快照。但也会带来一个小坑：如果你在一个长事务里先查询了数据，然后其他程序往表里插了新数据，你再次查询同条件数据，还是只能看到事务开始时的数据。如果业务逻辑依赖能看到最新数据，要么把隔离级别改成Read Committed，要么确保事务尽快结束，不要长时间占着连接。

3.3 批量数据写入的两种高效方案

我做过一个爬虫数据落库的项目，每天要写入约20万条数据。如果逐条insert，每条一次网络往返，最终耗时和数据库压力都不可接受。这时有两种推荐方案。

第一种是executemany批量写入。前面2.2节已经展示过用法，批量插入一万条记录只需要一个SQL模板和一次方法调用。PyMySQL底层虽然仍然是逐条发送，但它复用了预编译语句，Python层面的循环开销大幅减少。

第二种更狠，是用LOAD DATA LOCAL INFILE方式导入。这需要MySQL服务端开启local_infile选项。PyMySQL连接时可以传入local_infile=True参数。这种方式可以直接把一个本地数据文件批量灌进表里，速度比executemany还快一个数量级。通常适合做初始数据迁移或者大规模日志导入。

python复制conn = pymysql.connect(
    host="127.0.0.1", user="root", password="123456", database="test_db",
    local_infile=True
)
with conn.cursor() as cursor:
    sql = """LOAD DATA LOCAL INFILE '/tmp/data.txt'
             INTO TABLE users
             FIELDS TERMINATED BY ','
             ENCLOSED BY '"'
             LINES TERMINATED BY '\\n'
             (name, age, city)"""
    cursor.execute(sql)
conn.commit()

注意这个文件路径在Unix系统中是绝对路径，并且数据文件中的各字段顺序要和表字段列表保持一致。还有一个容易忽略的点：如果数据文件里含有中文，必须确保文件编码是utf-8，并且过程中连接使用的charset参数是utf8mb4，否则会出现乱码。这个方式非常依赖数据文件的格式，一个转义符处理不好就会把整体导入弄失败。

3.4 字典游标的妙用

默认游标返回的数据格式是元组，每行数据是一个元组，字段的值按select列的顺序排列。在查询字段少、结构固定的场景下这没什么问题。但如果你的表有二三十个字段，元组取值全靠下标记忆，代码可读性和可维护性会变得极差。比如result[5]到底是手机号还是邮箱，过两个月回看你自己的代码都得猜半天。

PyMySQL提供了DictCursor来返回字典格式的结果集，每行数据是一个字典，直接通过字段名取值，极大提升可读性。

python复制from pymysql.cursors import DictCursor

cursor = conn.cursor(DictCursor)
cursor.execute("SELECT name, age, city FROM users WHERE id = %s", (1,))
row = cursor.fetchone()
print(row["name"], row["age"], row["city"])

值得留意的是，字典游标返回的字典是无序的，虽然通常插入顺序和字段定义顺序一致，但这是一个实现细节，不要依赖字段顺序。此外还有SSDictCursor，SSCursor是服务端游标，适用于超大结果集的流式读取。但这两种游标有一个特点：它们会独占连接，在结果集没有读完之前，这个连接上不能执行其他SQL操作。如果忘记这一点，同时在同一个连接上执行新的查询，会抛出异常。

4. 老手也要踩的坑和故障排查清单

4.1 连接超时和连接断开的经典问题

服务端配置了wait_timeout和interactive_timeout，如果连接空闲太久没有活动，MySQL服务器会主动断开连接。使用连接池的应用程序会发现，从连接池拿出来一个连接，去执行SQL时突然报错：

code复制pymysql.err.OperationalError: (2013, 'Lost connection to MySQL server during query')

也可能报的是：

code复制pymysql.err.InterfaceError: (0, '')

原因是连接已经被服务端关了，但是客户端不知道。解决这个问题有几个常用思路。最简单粗暴的方式是每次使用前先ping一下，pymysql的Connection对象内置了ping方法，ping(reconnect=True)可以在断开时自动重连。不过这会导致每个请求都有一次额外的网络往返。

另一种思路是捕获异常后重试。我自己写过这样的辅助逻辑：拿连接执行SQL，如果遇到OperationalError且错误码是2013或2006，就关闭连接重新拿一个再执行一次，通常第二次都会成功。这种方案更优雅，会确保所有故障场景都能被覆盖。

4.2 字符集乱码问题的根源排查

我之前帮一个朋友排查线上数据乱码的问题，代码里明明在连接参数里写了charset=utf8，存进去的中文还是变成了问号。排查到最后发现两层问题。

第一层，连接参数的charset虽然标记了utf8，但MySQL的utf8字符集最多支持三个字节长度。emoji表情是四个字节的，会直接写入失败或者变成乱码。所以在新项目中存储用户生成内容时，一律使用utf8mb4字符集。utf8mb4是utf8的超集，完全向下兼容。

第二层，数据库表本身的字符集也要匹配。有些表在建表时就指定了默认字符集为latin1或者gbk，哪怕你用utf8mb4连接去写入，最终落库的编码还是不对。这种问题靠程序层改配置解不了，必须去修改表的字符集：

sql复制ALTER TABLE users CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

另外有一种比较隐蔽的情况，就是终端或者脚本文件本身的编码环境问题。Windows上Python默认的控制台编码是gbk，Python 3.7及以上版本用UTF-8模式运行，但在某些旧环境中，代码里的中文字符串直接打印就显示乱码，这跟数据库没关系，纯粹是展示终端的问题。排查时先分清数据本身有没有乱，再怀疑数据库存储，不然容易绕远路。

4.3 SQL执行报错的快速定位方法

PyMySQL报错信息里，最有价值的部分是错误码和错误消息。几个常见的错误码你最好心里有数。

错误码1062表示主键或唯一索引冲突。在你做insert或update时如果撞了唯一索引，就会抛这个错。业务上通常要捕获后做处理，比如提示用户“手机号已注册”，而不应该让整个程序崩溃。

错误码1146表示表不存在，通常是数据库选错了或者表名写错。错误码1054表示字段不存在，常见原因是SQL里写了某个表中不存在的列名。错误码1451是外键约束失败，在有外键关联的表上删除父表数据时，如果子表还有引用记录，就会报这个错。很多时候这种错误信息不够直观，定位问题时建议在try/except里将完整的SQL和执行参数一并记录下来：

python复制except pymysql.MySQLError as e:
    logger.error(f"SQL执行失败, code={e.args[0]}, msg={e.args[1]}, sql={sql}, args={args}")

pyMySQL的异常对象args元组中第一个元素是MySQL错误码，第二个是错误描述。记录SQL和参数对复现问题非常有帮助。

4.4 关于连接池的三个建议

PyMySQL本身不提供连接池功能，需要借助外部库DBUtils或者自己实现。网上推荐比较多的是DBUtils的PooledDB。但我在实际使用中发现，DBUtils对PyMySQL的适配有点历史包袱，用起来配置项较多。如果你使用的Web框架是Flask或Django，也可以考虑框架自身提供的数据库连接管理机制。

自己实现一个简单的连接池也并不复杂，Python的queue.Queue可以实现一个线程安全的先进先出容器。核心思路是：初始化时创建固定数量的连接放入队列，使用时从队列中取，用完后归还。要额外注意两条：一是连接使用前要检查是否还活着，二是归还前要把当前事务回滚掉，避免把未提交的事务状态带回池里。

我使用连接池时的经验是：

• 连接池大小不要太大，一般5到10个连接就能满足几百个并发请求下的数据库操作需求，毕竟连接是复用而不是每个请求新建。
• 获取连接时设置超时时间，假如5秒内拿不到连接就直接报错，不要无限等待。
• 定期清理池中无效连接，避免池里堆着一堆死连接被取出来报错。

说实话，对小型项目我反而建议连连接池都不要上，用前面那个上下文管理器封装就够了。连接池是解决高并发问题的手段，而不是装点门面的工具，盲目增加连接数量反而会拖垮数据库。

4.5 一个完整的错误排查流程示例

假设你现在遇到了一个诡异问题：同样的Python代码，在A机器上运行正常，在B机器上运行查询结果为空，手工在MySQL客户端执行同样的SQL却能看到数据。

排查步骤建议这样走：

1. 先确认B机器连接的数据库实例和A机器是不是同一个，连到不同的测试库是最常见原因。
2. 查看连接参数，确认database配置正确。
3. 确认B机器上的PyMySQL版本是否和A机器一致，老版本驱动程序在prepare语句处理上有一些差异性bug。
4. 在代码里打印出当前连接上下文，确认连接后是否执行过use database操作。
5. 如果以上都正常，开启PyMySQL的调试日志，把底层发送的实际SQL语句打印出来，人工比对SQL的差异。

我之前遇到过几次所谓“诡异问题”，最后定位出来要么是环境变量中数据库连接串被覆盖，要么是系统hosts文件解析到了错误的数据库IP。这类问题靠肉眼看代码很难察觉得出来。

5. 整理了一份快速排查速查表

遇到了报错直接从这里对着看：

这个速查表覆盖了我在工作里遇到的大部分日常问题。排查数据库问题时有一个心法：先确认问题和代码无关，再怀疑驱动，最后才考虑数据库本身。很多时候因为代码里的一个连接没关闭，后面所有的操作都在排队等连接，表象看起来像数据库卡死，实际却是连接资源被占满了。

PyMySQL的底层通信是同步阻塞的，也就是说在同一个线程里，一个SQL没有执行完成之前，你没法在同一个连接上发出下一个SQL。这一点在一些需要并发查询的场景里会限制你的设计思路。例如从不同表查询统计数据，如果用多线程，就需要每个线程都持有独立连接。如果只有一个连接，并发查询会退化成排队查询。

对于这些场景，可以考虑使用PyMySQL的异步版本aiomysql，它在异步编程模型里能更好地利用单线程处理并发IO。

我在实战中有一个深刻的体会：处理MySQL事务时，要格外小心long transaction的影响。长事务意味着持锁时间长，一旦另一个会话需要更新同一行数据，就会一直等待。某个凌晨的批处理任务，循环更新几十万条记录，每条都在一个独立的小事务里执行，但整批跑下来花了很久，中间多次出现锁等待超时，最后把整个批处理时间又拖慢了。分析下来就是因为单条记录循环处理之间提交太慢，持锁太久。优化方案是改成批量提交，每1000条commit一次，问题立刻解决。

PyMySQL算不上一个“难”的库，它没有复杂的学习曲线，核心就连接、游标、事务这三板斧。但正因为简单，很多人会忽视它背后的种种细节。所有看似随机的问题，几乎都可以追溯到连接管理不当、字符集配置错误、事务边界不明、异常处理缺失这几个根因。

最后再分享一个我早期处理数据时用过的调试技巧：排查问题时可以在代码中临时开启general log，但线上环境不要这么做，否则会产生巨大的日志文件拖慢整个数据库。更轻量级的做法是在Python侧打好日志，记录每一次execute的SQL和参数，基本能应付绝大多数排查场景。

希望这篇从头写下来的PyMySQL入门内容能够帮你避开我当年踩过的坑。读完之后，照着文中代码自己操作一遍，连接、增删改查、事务、批量写，完整跑通一遍后你应该已经掌握了PyMySQL日常应用的八成场景。剩下的坑，等你实际项目里遇到了，再回来看看第4节的速查表就行。