快速入门

Flask-SQLAlchemy 通过自动处理创建、使用和清理通常会使用的 SQLAlchemy 对象，从而简化了 SQLAlchemy 的使用。它添加了一些有用的功能，但仍然像 SQLAlchemy 一样工作。

此页面将引导您了解 Flask-SQLAlchemy 的基本用法。有关完整功能和自定义，请参阅这些文档的其余部分，包括 SQLAlchemy 对象的 API 文档。

查看 SQLAlchemy 文档

Flask-SQLAlchemy 是 SQLAlchemy 的包装器。您应该按照 SQLAlchemy 教程 来了解如何使用它，并查阅其文档以获取有关其功能的详细信息。这些文档展示了如何设置 Flask-SQLAlchemy 本身，而不是如何使用 SQLAlchemy。Flask-SQLAlchemy 会自动设置引擎和作用域会话，因此您可以跳过 SQLAlchemy 教程中的那些部分。

本指南假定您使用的是 SQLAlchemy 2.x，它具有用于定义模型的新 API，并更好地支持 Python 类型提示和数据类。如果您使用的是 SQLAlchemy 1.x，请参阅 传统快速入门。

安装

Flask-SQLAlchemy 可在 PyPI 上获得，可以使用各种 Python 工具进行安装。例如，要使用 pip 安装或更新最新版本

$ pip install -U Flask-SQLAlchemy

初始化扩展

首先使用 SQLAlchemy 构造函数创建 db 对象。

将 DeclarativeBase 或 DeclarativeBaseNoMeta 的子类传递给构造函数。

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
  pass

db = SQLAlchemy(model_class=Base)

在 模型和表 中了解有关自定义基本模型类的更多信息。

关于 SQLAlchemy 对象

构造后，db 对象将允许您访问 db.Model 类以定义模型，以及 db.session 以执行查询。

SQLAlchemy 对象还可以采用其他参数来定制其管理的对象。

配置扩展

下一步是将扩展连接到 Flask 应用程序。唯一必需的 Flask 应用程序配置是 SQLALCHEMY_DATABASE_URI 键。这是一个连接字符串，它告诉 SQLAlchemy 要连接到哪个数据库。

创建 Flask 应用程序对象，加载任何配置，然后通过调用 db.init_app 使用应用程序初始化 SQLAlchemy 扩展类。此示例连接到 SQLite 数据库，该数据库存储在应用程序的实例文件夹中。

# create the app
app = Flask(__name__)
# configure the SQLite database, relative to the app instance folder
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///project.db"
# initialize the app with the extension
db.init_app(app)

请参阅 配置 以了解连接字符串以及使用的其他配置键。

定义模型

子类化 db.Model 以定义模型类。该模型将通过将 CamelCase 类名转换为 snake_case 来生成表名。

from sqlalchemy import Integer, String
from sqlalchemy.orm import Mapped, mapped_column

class User(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    username: Mapped[str] = mapped_column(unique=True)
    email: Mapped[str]

请参阅 模型和表 以获取有关定义和创建模型和表的更多信息。

创建表

在定义所有模型和表之后，调用 SQLAlchemy.create_all() 在数据库中创建表架构。这需要一个应用程序上下文。由于你现在不在请求中，请手动创建一个。

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

如果你在其他模块中定义模型，则必须在调用 create_all 之前导入它们，否则 SQLAlchemy 将不知道它们。

create_all 不会更新数据库中已存在的表。如果你更改模型的列，请使用 Alembic 和 Flask-Alembic 或 Flask-Migrate 等迁移库来生成更新数据库架构的迁移。

查询数据

在 Flask 视图或 CLI 命令中，可以使用 db.session 执行查询并修改模型数据。

SQLAlchemy 会自动为每个模型定义一个 __init__ 方法，该方法将任何关键字参数分配给相应的数据库列和其他属性。

db.session.add(obj) 将一个对象添加到会话中，以便插入。修改对象的属性会更新该对象。 db.session.delete(obj) 删除一个对象。请记住在修改、添加或删除任何数据后调用 db.session.commit()。

db.session.execute(db.select(...)) 构造一个查询以从数据库中选择数据。构建查询是 SQLAlchemy 的主要功能，因此您需要阅读其 关于选择内容的教程 以全面了解它。您通常会使用 Result.scalars() 方法来获取结果列表，或使用 Result.scalar() 方法来获取单个结果。

@app.route("/users")
def user_list():
    users = db.session.execute(db.select(User).order_by(User.username)).scalars()
    return render_template("user/list.html", users=users)

@app.route("/users/create", methods=["GET", "POST"])
def user_create():
    if request.method == "POST":
        user = User(
            username=request.form["username"],
            email=request.form["email"],
        )
        db.session.add(user)
        db.session.commit()
        return redirect(url_for("user_detail", id=user.id))

    return render_template("user/create.html")

@app.route("/user/<int:id>")
def user_detail(id):
    user = db.get_or_404(User, id)
    return render_template("user/detail.html", user=user)

@app.route("/user/<int:id>/delete", methods=["GET", "POST"])
def user_delete(id):
    user = db.get_or_404(User, id)

    if request.method == "POST":
        db.session.delete(user)
        db.session.commit()
        return redirect(url_for("user_list"))

    return render_template("user/delete.html", user=user)

您可能会看到使用 Model.query 来构建查询。这是一个用于查询的较旧接口，在 SQLAlchemy 中被认为是过时的。最好使用 db.session.execute(db.select(...))。

请参阅 修改和查询数据 以获取有关查询的更多信息。

需要记住的内容

在大多数情况下，您应该像往常一样使用 SQLAlchemy。 SQLAlchemy 扩展实例创建、配置并提供对以下内容的访问