Flask-SQLAlchemy 数据操作与查询指南

Flask-SQLAlchemy 数据操作与查询指南

flask-sqlalchemy 项目地址: https://gitcode.com/gh_mirrors/fla/flask-sqlalchemy

概述

Flask-SQLAlchemy 作为 Flask 框架的 SQLAlchemy 集成扩展，提供了便捷的数据库操作方式。本文将详细介绍如何使用 Flask-SQLAlchemy 进行数据的增删改查操作，以及一些实用的查询技巧。

数据修改操作

插入数据

在 Flask-SQLAlchemy 中插入新记录非常简单：

# 创建模型实例
user = User(name='张三', email='zhangsan@example.com')

# 添加到会话
db.session.add(user)

# 提交到数据库
db.session.commit()

关键点：

• 必须先调用 add() 方法将对象添加到会话
• 必须调用 commit() 方法才会真正写入数据库
• 如果忘记提交，请求结束时所有修改将丢失

更新数据

更新现有记录只需要修改对象属性并提交：

# 获取用户
user = User.query.get(1)

# 修改属性
user.email = 'new_email@example.com'

# 提交更改
db.session.commit()

删除数据

删除记录使用 delete() 方法：

# 获取要删除的用户
user = User.query.get(1)

# 从会话中删除
db.session.delete(user)

# 提交更改
db.session.commit()

数据查询操作

基本查询

Flask-SQLAlchemy 2.x 推荐使用 SQLAlchemy 2.0 风格的查询语法：

# 查询单个用户
user = db.session.execute(db.select(User).filter_by(username='张三')).scalar_one()

# 查询多个用户并按用户名排序
users = db.session.execute(db.select(User).order_by(User.username)).scalars()

说明：

• scalar_one() 确保查询返回且只返回一个结果
• scalars() 返回所有匹配结果的生成器

常用查询方法

1. 获取单个对象：

   # 获取主键为1的用户
   user = db.get_or_404(User, 1)
   

2. 条件查询：

   # 查询所有管理员用户
   admins = db.session.execute(db.select(User).where(User.is_admin == True)).scalars()
   

3. 排序和分页：

   # 获取按创建时间降序排列的第2页数据(每页10条)
   users = db.session.execute(
       db.select(User)
       .order_by(User.created_at.desc())
       .offset(10)
       .limit(10)
   ).scalars()
   

视图中的便捷查询方法

Flask-SQLAlchemy 为视图函数提供了几个特别有用的查询方法：

1. get_or_404 - 根据主键查找，找不到返回404

   @app.route('/users/<int:id>')
   def show_user(id):
       user = db.get_or_404(User, id)
       return render_template('user.html', user=user)
   

2. first_or_404 - 返回查询的第一个结果，没有结果返回404

   @app.route('/active-users')
   def active_users():
       user = db.first_or_404(db.select(User).where(User.is_active == True))
       return render_template('user.html', user=user)
   

3. one_or_404 - 确保查询返回且只返回一个结果，否则返回404

   @app.route('/user-by-email/<email>')
   def user_by_email(email):
       user = db.one_or_404(db.select(User).filter_by(email=email))
       return render_template('user.html', user=user)
   

自定义404消息：

user = db.one_or_404(
    db.select(User).filter_by(username=username),
    description=f"找不到用户名为 '{username}' 的用户"
)

新旧查询接口对比

在较新版本的 SQLAlchemy 中，传统的 Model.query 接口已被标记为遗留接口，推荐使用新的 session.execute(select(...)) 方式：

传统方式(不推荐)：

users = User.query.filter_by(is_active=True).all()

现代方式(推荐)：

users = db.session.execute(db.select(User).where(User.is_active == True)).scalars()

最佳实践

1. 总是处理事务：确保在修改数据后调用 commit() 或 rollback()
2. 使用上下文管理器：可以利用 Flask 的请求生命周期自动处理会话
3. 批量操作优化：对于大量插入，考虑使用 bulk_save_objects() 方法
4. 错误处理：适当捕获 NoResultFound 和 MultipleResultsFound 异常

通过掌握这些 Flask-SQLAlchemy 的数据操作技巧，你可以更高效地在 Flask 应用中进行数据库交互，同时编写出更健壮的代码。

flask-sqlalchemy 项目地址: https://gitcode.com/gh_mirrors/fla/flask-sqlalchemy