Flask连接MySQL与ORM增删改查实操指南

做了这么久的Flask后端开发，到第八篇终于轮到数据库了。前面几篇我们一直在处理路由、模板、Request对象这些“表面功夫”，但真正的后端开发，核心永远是对数据的操作。这一篇我就把Flask连接MySQL、用ORM做增删改查这件事一次性讲透，从环境准备到实际代码，再到我踩过的坑，全部整理出来。文章适合刚接触Flask不久、想在项目中落地数据库操作的开发者，也适合那些已经能跑通Hello World、但一遇到数据库就不知道怎么下手的同学。

1. 环境准备：先把MySQL和依赖库搞定

1.1 MySQL安装与数据库创建

连接MySQL的第一步，是你得先有一个能用的MySQL服务。很多人卡在这一步不是因为不会写代码，而是MySQL压根没装好。MySQL的安装其实不复杂，但有几个关键点必须注意，否则后面连接时会各种报错。

我建议直接去MySQL官网下载安装包，选择MySQL Community Server，这是免费版本，也是绝大多数项目的选择。版本方面，MySQL 5.7和8.0我都用过，如果没有特殊限制，直接上8.0。8.0在性能、JSON支持、窗口函数方面都比5.7强不少，而且现在新项目基本默认8.0起步。网上很多教程还在讲5.7，是因为它稳定、资料多，但对新手来说直接用8.0反而省得以后迁移。

安装过程中有一步是让你设置root密码，这一步不要跳过随便填，一定记住你设的密码。另外有个选项是选择字符集，强烈建议选utf8mb4，因为这个字符集支持完整的Unicode，包括中文、emoji等特殊字符。如果你用默认的latin1或者utf8mb3，后面插入中文数据经常会出现乱码或者“Data too long”之类的报错。

装完之后，Windows用户需要把MySQL的bin目录添加到系统环境变量PATH中，否则在命令行里敲mysql命令会提示找不到命令。Mac和Linux用户一般安装时自动配好了，但也不绝对，遇到提示找不到mysql命令时先检查环境变量。

接下来创建项目专用的数据库。登录MySQL之后，执行下面这条命令：

CREATE DATABASE flask_demo DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

这里我建了一个名为flask_demo的数据库，字符集指定utf8mb4。如果你只执行CREATE DATABASE flask_demo，MySQL会用默认字符集，但为了保险起见，建议每次都显式指定字符集和排序规则。这样建出来的库才能真正承载中文内容。

1.2 Flask相关依赖安装清单

数据库准备好了，接下来是Python环境这边要装的库。网上很多教程是装flask-mysqldb或者MySQLdb，但我要劝你直接用pymysql。理由很简单：MySQLdb在某些系统上需要编译C扩展，安装过程会遇到一堆依赖问题，而pymysql是纯Python实现，pip直接装上就能用，对新手极其友好。

需要安装的依赖总共就这么几个：

pip install flask pip install flask-sqlalchemy pip install pymysql

flask-sqlalchemy是Flask官方推荐的ORM扩展，它把SQLAlchemy和Flask做了整合，用起来比直接裸用SQLAlchemy方便很多。pymysql是驱动层，负责让Python能和MySQL通信。

装好之后，你可以先测试一下pymysql能不能正常导入，避免后面排查问题时多一个不确定性：

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

如果输出版本号，说明驱动没问题。这一步看起来多余，但结合我多年的经验，大部分连接异常都可以通过这种基础检查提前排除。

2. 为什么要用ORM？连接配置到底怎么写

2.1 ORM是什么，和裸SQL比优势在哪

ORM的全称是Object Relational Mapping，对象关系映射。我见过很多初学者第一次听到这个概念时一脸懵，觉得不如直接写SQL来得直接。我给你打个比方：裸SQL就像你去菜市场买菜，想买什么就亲自去挑，灵活但费劲；ORM就像你通过外卖平台下单，你告诉平台“我要一条鲈鱼”，平台帮你完成后面所有的采购、清洗、处理流程。

具体到代码层面，ORM让你可以这样操作数据库：定义一个Python类代表一张表，这个类的实例代表表中的一行记录，操作这个实例的方法和属性就被ORM自动翻译成SQL语句。你不需要手写INSERT、UPDATE、DELETE这些SQL，只需要操作对象即可。

这样做的好处有几个。第一是安全性，ORM底层使用参数化查询，天然防止SQL注入攻击，新手写裸SQL时很容易犯字符串拼接的错误而埋下安全漏洞。第二是可维护性，业务代码里全是Python对象，没有SQL字符串夹杂，结构更清晰，重构也更方便。第三是可移植性，如果你哪天想把MySQL换成PostgreSQL，ORM框架下只需改一行连接配置，SQL基本不用动。

当然，ORM也不是万能钥匙。复杂查询、多表关联、批量更新等场景，ORM生成的SQL未必有手写SQL高效。但在绝大多数业务系统里，ORM的效率完全够用，而且开发效率远高于手写SQL。

2.2 连接串配置与引擎初始化

flask-sqlalchemy的配置核心是一个数据库连接串。这个连接串的格式是固定的，我来拆解一下：

mysql+pymysql://用户名:密码@主机地址:端口/数据库名?charset=utf8mb4

• mysql+pymysql表示使用MySQL数据库，通过pymysql驱动连接
• 用户名和密码是MySQL的登录账号信息
• 主机地址，本地开发写localhost即可
• 端口默认3306
• 数据库名就是你刚才创建的flask_demo
• charset=utf8mb4这个参数非常重要，不写的话中文很容易出问题

完整的代码写法如下：

from flask import Flask from flask_sqlalchemy import SQLAlchemy app = Flask(__name__) app.config['SQLALCHEMY_DATABASE_URI'] = 'mysql+pymysql://root:your_password@localhost:3306/flask_demo?charset=utf8mb4' app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False db = SQLAlchemy(app)

这里有个细节，SQLALCHEMY_TRACK_MODIFICATIONS这个配置项在旧版本中默认开启，会跟踪对象的修改并消耗额外内存，并且会有一条警告提示。显式设置为False可以消除警告，同时也是一种更合理的资源利用方式。

另外注意，flask-sqlalchemy 3.x版本中，连接配置项的key已经改成SQLALCHEMY_DATABASE_URI，而2.x版本用的是SQLALCHEMY_DATABASE_URI，写法上是一样的。如果你用的是2.x，配置key也是一样。但一些老项目中可能还存在SQLALCHEMY_DATABASE_URI和SQLALCHEMY_DATABASE_URI混用的记忆误区，建议以官方文档为准。

db = SQLAlchemy(app)这一步完成了flask-sqlalchemy与应用的绑定。绑定之后，你就可以在任意视图函数或业务代码中，通过db这个对象来操作数据库了。

3. 模型定义与数据库表初始化

3.1 用户表和文章表怎么定义字段

ORM的模型定义，本质上就是用Python类来描述数据库表的结构。我以一个典型的用户模型为例，讲解字段定义和约束。

假设我们要做一个小项目，有用户表和文章表。用户表包含ID、用户名、邮箱、创建时间等字段。模型定义如下：

from datetime import datetime class User(db.Model): __tablename__ = 'users' id = db.Column(db.Integer, primary_key=True) username = db.Column(db.String(80), unique=True, nullable=False) email = db.Column(db.String(120), unique=True, nullable=False) created_at = db.Column(db.DateTime, default=datetime.utcnow) def __repr__(self): return f'<User {self.username}>'

我来逐一解释这些字段的作用：

• __tablename__指定数据库中的表名。如果不写，SQLAlchemy会根据类名自动生成表名，比如User会变成user，但为了代码清晰和可控，最好显式指定。
• db.Integer对应MySQL的INT类型，primary_key=True表示主键，主键自动自增，不需要手动赋值。
• db.String对应VARCHAR类型，括号里的数字是长度上限。unique=True表示该字段的值不能重复，适合用户名、邮箱这类字段。
• nullable=False表示该字段不能为NULL，插入数据时必须有值。
• db.DateTime对应DATETIME类型，default=datetime.utcnow表示如果插入时没有显式赋值，就自动填充当前UTC时间。

文章表可以这样定义：

class Article(db.Model): __tablename__ = 'articles' id = db.Column(db.Integer, primary_key=True) title = db.Column(db.String(200), nullable=False) content = db.Column(db.Text, nullable=False) user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False) created_at = db.Column(db.DateTime, default=datetime.utcnow)

这里多了一个db.ForeignKey，表示文章的用户ID关联到users表的主键。这就是外键约束，用于维持表间的引用完整性。后续可以用relationship实现更高级的关联查询，但在这篇文章里我们先不过度展开，先把增删改查跑通。

3.2 建表与验证：三种常见的初始化方式

模型定义好了，接下来要在MySQL里真正创建这些表。flask-sqlalchemy提供了db.create_all()方法，它会根据所有已定义的模型自动建表，非常方便。

但这里有一个很容易踩的坑：在调用db.create_all()之前，必须先确保应用上下文已经准备好。直接在一个独立的Python脚本里写db.create_all()，有可能会报错说“Working outside of application context”。解决方法是把建表操作放在app.app_context()里面，或者放在视图函数、应用启动代码中。

常见的写法有三种。

第一种，在建表的独立脚本里显式创建应用上下文：

with app.app_context(): db.create_all()

第二种，直接在应用启动入口处建表：

if __name__ == '__main__': with app.app_context(): db.create_all() app.run(debug=True)

第三种，通过flask shell来操作。在命令行里敲flask shell进入交互环境，然后执行db.create_all()。这种方式适合调试时使用。

建表之后，你可以用Navicat、MySQL Workbench或者命令行查看一下表结构，确认表已经生成。我用过的工具里，Navicat最方便，但它是收费的。MySQL Workbench是官方免费工具，功能虽重但完全够用。如果只是在命令行里查看，执行SHOW TABLES;就能看到当前库里有哪些表。

4. 增删改查的完整实操

4.1 新增数据与事务提交机制

增删改查四件事，新增是第一件。用ORM新增一条数据分三步：创建对象、加入会话、提交事务。

# 方法一：单独创建再提交 user = User(username='张三', email='zhangsan@example.com') db.session.add(user) db.session.commit()

为什么要分成add和commit两步？这里的db.session是SQLAlchemy的会话对象，它负责跟踪所有对象的状态变化。db.session.add(user)只是把对象加入会话的待处理列表，此时数据还没有真正写入数据库。只有调用db.session.commit()，所有在会话中积累的操作才会一次性提交到MySQL。

这种机制叫做工作单元模式。它的好处是：你可以把多个操作放在一个事务里，要么全部成功，要么全部失败，不会出现只插入一半数据的尴尬局面。比如注册用户时，要同时往用户表和日志表各插入一条记录，你可以在同一次commit中完成，其中任何一个失败都会触发回滚，数据库恢复到提交前的状态。

commit对应的事务提交，如果不想保留这次操作，可以调用db.session.rollback()来回滚。我个人建议在写代码时养成一个习惯：涉及写操作的地方，用try-except包起来，失败时调用rollback。我见过太多项目因为没处理异常，数据库里出现了一些半成品数据，排查起来特别痛苦。

4.2 查询的各种姿势：filter vs filter_by

查询是增删改查里用得最多的操作，也是新手最容易混淆的地方。flask-sqlalchemy提供了两个常用的条件查询方法：filter和filter_by。

# 查询所有用户 all_users = User.query.all() # 查询第一个用户 first_user = User.query.first() # 按主键查询 user = db.session.get(User, 1) # filter_by方式：等值条件 user = User.query.filter_by(username='张三').first() # filter方式：支持复杂条件 user = User.query.filter(User.username == '张三').first()

两者区别在于：filter_by只支持等值匹配，写法更简洁，接收关键字参数；filter支持任意比较运算符，包括大于、小于、不等于、模糊匹配等，并且需要写成User.username == '张三'这种形式。

再举几个filter的典型用法：

# 年龄大于18的用户 User.query.filter(User.age > 18).all() # 用户名不为空的用户 User.query.filter(User.username != None).all() # 模糊匹配，查找用户名包含"张"的用户 User.query.filter(User.username.like('%张%')).all() # 逻辑与条件 User.query.filter(User.username == '张三', User.email != '').all() # 逻辑或条件，需要显式导入or_ from sqlalchemy import or_ User.query.filter(or_(User.username == '张三', User.username == '李四')).all()

要注意，查询返回的结果是一个Query对象，并不是最终的列表。只有调用.all()才会真正执行SQL并得到所有满足条件的记录列表，.first()则返回第一条记录，如果没有记录则返回None。

还有一个细节：在flask-sqlalchemy 3.x版本中，Query.get()方法已被标记为废弃，推荐使用db.session.get(User, id)来按主键查询。旧教程里常见的User.query.get(1)写法虽然还能用，但会有DeprecationWarning，建议新代码统一使用db.session.get。

4.3 修改与删除：记住这一两个坑

修改数据在ORM里很简单：先查到要修改的对象，直接改它的属性，然后commit即可。

# 修改用户名 user = db.session.get(User, 1) if user: user.username = '王五' db.session.commit()

这里有个必须注意的坑：如果你改了对象的属性但没有调用commit，修改只体现在当前会话的缓存里，MySQL里的数据并没有变。后续如果你做了其他查询，可能会发现数据还是旧值，然后一脸疑惑。记住一条原则：ORM里任何改动都要显式调用commit才会真正落库。

删除数据同样比较直接，但要注意顺序：先查出对象，再delete，再commit。

# 删除用户 user = db.session.get(User, 1) if user: db.session.delete(user) db.session.commit()

如果删除的对象与其他表存在外键关联，而外键字段又没有设置ON DELETE CASCADE之类的级联规则，删除时可能会报外键约束错误。这也是新手容易困惑的地方：明明是一句简简单单的delete，怎么就报错了？遇到这种情况，要么先删除关联的子记录，要么在模型里配置级联删除。

为了更直观地展示增删改查的完整业务场景，我写一个简单的用户管理接口，把这些操作串在一起：

from flask import request, jsonify @app.route('/users', methods=['GET']) def get_users(): users = User.query.all() return jsonify([{'id': u.id, 'username': u.username, 'email': u.email} for u in users]) @app.route('/users', methods=['POST']) def add_user(): data = request.get_json() user = User(username=data['username'], email=data['email']) db.session.add(user) db.session.commit() return jsonify({'id': user.id}), 201 @app.route('/users/<int:user_id>', methods=['PUT']) def update_user(user_id): user = db.session.get(User, user_id) if not user: return jsonify({'error': 'User not found'}), 404 data = request.get_json() user.username = data.get('username', user.username) user.email = data.get('email', user.email) db.session.commit() return jsonify({'id': user.id, 'username': user.username, 'email': user.email}) @app.route('/users/<int:user_id>', methods=['DELETE']) def delete_user(user_id): user = db.session.get(User, user_id) if not user: return jsonify({'error': 'User not found'}), 404 db.session.delete(user) db.session.commit() return jsonify({'message': 'User deleted'})

这套接口跑起来之后，你就能通过POST、GET、PUT、DELETE四个HTTP方法对用户数据做完整的增删改查了。用Postman或者curl测试时，注意POST和PUT要传JSON格式的数据，并且请求头要加Content-Type: application/json。

5. 常用查询技巧与进阶玩法

5.1 对查询结果排序、分页与模糊搜索

实际项目中，查询很少像基础增删改查那样简单。我把几个高频的查询场景单独拎出来讲，这些代码我几乎每个项目都会用到。

排序很常用，使用order_by：

# 按创建时间倒序排列 articles = Article.query.order_by(Article.created_at.desc()).all() # 按创建时间正序排列 articles = Article.query.order_by(Article.created_at.asc()).all() # 多个条件排序 articles = Article.query.order_by(Article.created_at.desc(), Article.id.desc()).all()

分页有一个非常方便的paginate方法：

# 每页10条，取第2页的数据 page = 2 paginate_obj = Article.query.paginate(page=page, per_page=10) # 当前页的文章列表 articles = paginate_obj.items # 总页数 total_pages = paginate_obj.pages # 是否有上一页 has_prev = paginate_obj.has_prev # 是否有下一页 has_next = paginate_obj.has_next

paginate返回的对象包含了分页后的数据以及分页相关的元信息，处理前端的分页展示特别顺手。

模糊搜索用的是like加通配符：

# 搜索标题里包含"Flask"的文章 articles = Article.query.filter(Article.title.like('%Flask%')).all()

这里有个小技巧：在MySQL中，百分号%表示任意多个字符，下划线_表示单个字符。如果你要搜索的字符串本身包含百分号或下划线，需要用escape转义，但这属于少数情况，平时都直接用%包裹关键词就行。

5.2 常用查询技巧速查表

我把日常开发中最高频的一些查询写法整理成一个表格，方便以后直接查阅：

这些写法可以组合使用，比如filter加order_by再加limit，SQLAlchemy会自动拼成正确的SQL语句。

5.3 默认值设置与类型检查

项目中经常遇到字段要设置默认值的情况，比如用户积分默认0、文章状态默认“草稿”。在模型里可以直接用default参数：

class User(db.Model): __tablename__ = 'users' id = db.Column(db.Integer, primary_key=True) username = db.Column(db.String(80), unique=True, nullable=False) points = db.Column(db.Integer, default=0) status = db.Column(db.String(20), default='inactive')

这里的default只是Python层面的默认值，也就是说当你创建User对象没有传入points时，Python会自动填入0。但如果有人绕过ORM直接往表里插数据，就不会有这个默认效果。想要MySQL层面也有默认值，可以加server_default参数，但这属于进阶用法，普通项目用default就足够。

另外，我在调试接口时经常会打印客户端传的数据类型。可以用type()方法查看，Flask的request对象里，form和args的数据都是字符串，查询参数即使传的是数字，也要先转换成int才能真正参与数值比较。这是后端开发中很常见的类型坑，多留意一下就能少踩很多雷。

6. 高频报错与排查记录

6.1 连接报错、编码报错、字段报错

这部分是我最想分享的，因为学习中遇到的绝大多数“卡住”，其实都卡在这些报错上。我把高频报错整理成了速查表。

第一个错误是新手最常遇到的。因为你明明装了pymysql，但flask-sqlalchemy默认会找MySQLdb，如果不做任何处理，就会报No module named 'MySQLdb'。解决办法是在代码里加上一句：

import pymysql pymysql.install_as_MySQLdb()

这句代码的作用是把pymysql伪装成MySQLdb，这样SQLAlchemy在查找默认驱动时就能找到。

6.2 排查思路与避坑清单

排查数据库连接类的报错，我的固定思路是分层排查：先确认MySQL服务本身是否正常，再用命令行登录测试账号密码，然后写一个独立的Python脚本测试pymysql连接，最后才检查Flask应用里的配置。逐层收窄，很快就能定位问题具体出在哪一层。很多初学者一出问题就盯着Flask配置反复改，实际上问题根本不在那一层。

避坑清单方面，我再分享几个实际项目里非常有价值的经验：

第一，数据库密码不要写死在代码里，尤其是准备提交到Git仓库的项目。我建议用环境变量来保存敏感信息，配合dotenv之类的配置管理方式。哪怕现在只是在本地练习，也应该养成这个习惯。

第二，commit的时机要把握好，尽量让每个业务操作对应一个逻辑事务。不要在一个循环里每改一条数据就commit一次，性能会很差。正确的做法是在循环里拼接操作，全做完了最后统一commit。

第三，查询结果集转成字典很方便，但不要直接把ORM对象返回给前端做JSON序列化，因为ORM对象里包含很多内部状态信息，而且默认没有json序列化能力。正确的做法是手动构建一个字典，只包含需要的字段，就像我前面接口示例里那样。

第四，开发阶段建议开启Flask的debug模式，并且把SQLAlchemy的echo设为True，这样SQLAlchemy会打印出所有执行的原生SQL语句，对理解和排查问题非常有帮助。

app.config['SQLALCHEMY_ECHO'] = True

开启这个选项后，每次查询、插入、更新操作都会在控制台输出对应的SQL原文。我靠着这个日志，排查过无数个“为什么数据没更新”、“为什么查不到数据”的问题。等熟悉了ORM之后，再把它关掉。

第五，删除和修改操作一定要先确认对象存在，再执行操作。像我前面接口示例里那样，先用db.session.get查询，如果返回None就返回404响应。很多数据库错都是在“对不存在的数据做修改”或者“重复插入相同数据”时出现的。

另外，关于外键和关联，初学者经常会问要不要在表里建外键。我的建议是，正式项目表多、关系复杂的阶段，外键能建就建，它对数据完整性的保护是实打实的。但在做海量数据写入或高并发的场景下，外键会带来额外性能开销，有些团队会选择在应用层维护关联关系而不建外键。这个属于架构层面的取舍问题，等你遇到对应场景再深入也不迟。

关于后续的扩展方向，这篇已经把连接和增删改查讲完了，还有几个话题非常适合接着深入：models的relationship关联查询、数据库迁移工具Alembic、多表联查、事务隔离级别等。我后面的文章会接着写relationship的一对多和多对多玩法，那才是ORM真正发挥威力的地方。在实际操作中，我的体会是ORM的学习曲线比裸SQL要缓得多，千万不要因为一开始要理解session、filter这些概念就觉得麻烦，代码写多了就会自然习惯。最后分享一个小经验：遇到任何数据库操作的问题，先确认你的数据到底有没有提交成功，再去看代码逻辑。十次有七次是忘了commit，剩下三次是查询条件写错了。