将 SQLAlchemy 与 Flask 集成。这负责设置一个或多个引擎，将表和模型与特定引擎关联，并在每次请求后清理连接和会话。

只有引擎配置是特定于每个应用程序的，其他内容（如模型、表、元数据和会话）对于使用该扩展实例的所有应用程序都是共享的。调用 init_app() 以在应用程序上配置扩展。

创建扩展后，通过继承 Model 创建模型类，并通过 Table 创建表类。可以在调用 init_app() 之前访问这些类，从而可以将模型与应用程序分开定义。

访问 session 和 engine 需要一个活动的 Flask 应用程序上下文。这包括使用引擎的方法，例如 create_all() 。

此类还提供对 SQLAlchemy 中 sqlalchemy 和 sqlalchemy.orm 模块的名称的访问。例如，你可以使用 db.Column 和 db.relationship 而不是导入 sqlalchemy.Column 和 sqlalchemy.orm.relationship 。在定义模型时，这会很方便。

在 3.1.0 版本中更改： metadata 参数仍然可以与 SQLAlchemy 1.x 类一起使用，但在使用 SQLAlchemy 2.x 声明类样式时将被忽略。相反，在 Base 类上指定元数据。

在 3.1.0 版本中更改： 添加了 disable_autonaming 参数。

在 3.1.0 版本中更改： 将 model_class 参数更改为接受 SQLAlchemy 2.x 声明基本子类。

在 3.0 版本中更改： 始终需要一个活动的 Flask 应用程序上下文才能访问 session 和 engine 。

在 3.0 版本中更改： 每个绑定键都使用单独的 metadata 。

在 3.0 版本中更改： engine_options 参数在引擎前配置之前作为默认值应用。

在 3.0 版本中更改： 会话类可以在 session_options 中进行自定义。

在 3.0 版本中更改： 添加了 add_models_to_shell 参数。

在 3.0 版本中更改： 在调用 init_app 时创建引擎，而不是在首次访问它们时创建。

在 3.0 版本中更改： 除了 app 之外的所有参数都是关键字限定的。

在 3.0 版本中更改： 扩展实例直接存储为 app.extensions["sqlalchemy"] 。

在 3.0 版本中更改： 设置方法使用前导下划线重命名。它们被视为可能随时更改的内部接口。

在 3.0 版本中更改： 删除了 use_native_unicode 参数和配置。

在版本 2.4 中更改： 添加了 engine_options 参数。

在版本 2.1 中更改： 添加了 metadata 、 query_class 和 model_class 参数。

在版本 2.1 中更改： 在 session 、 Model.query 和 Query 中使用相同的查询类。

在版本 0.16 中更改： scopefunc 在 session_options 中被接受。

在版本 0.10 中更改： 添加了 session_options 参数。

一个 SQLAlchemy 声明模型类。子类化此类以定义数据库模型。

如果一个模型没有设置 __tablename__ ，它将通过将类名从 CamelCase 转换为 snake_case 来生成。如果模型看起来像使用单表继承，它将不会被生成。

如果一个模型或父类设置 __bind_key__ ，它将使用该元数据和数据库引擎。否则，它将使用默认的 metadata 和 engine 。如果模型设置 metadata 或 __table__ ，则忽略此设置。

对于使用 SQLAlchemy 1.x API 的代码，通过子类化 Model 并将 model_class 参数传递给扩展来定制此模型。一个完全创建的声明模型类也可以被传递，以使用自定义元类。

对于使用 SQLAlchemy 2.x API 的代码，通过子类化 sqlalchemy.orm.DeclarativeBase 或 sqlalchemy.orm.DeclarativeBaseNoMeta 并将 model_class 参数传递给扩展来定制此模型。

一个 sqlalchemy.schema.Table 类，它会自动选择元数据。

与基本 Table 不同， metadata 参数不是必需的。如果没有给出，则根据 bind_key 参数进行选择。

通过为所有或部分绑定键调用 metadata.create_all() 来创建数据库中不存在的表。这不会更新现有表，请为此使用迁移库。

这需要激活 Flask 应用程序上下文。

通过为所有或某些绑定键调用 metadata.drop_all() 来删除表。

这需要激活 Flask 应用程序上下文。

一个 sqlalchemy.orm.dynamic_loader() ，它将此扩展的 Query 类应用于关系和反向引用。

在版本 3.0 中更改： Query 类设置在 backref 中。

当前应用程序的默认 引擎 ，如果 会话 被 模型 或 表 查询时未设置绑定键，则使用此引擎。

要自定义，请设置 SQLALCHEMY_ENGINE_OPTIONS 配置，并通过将 engine_options 参数传递给扩展来设置默认值。

这需要激活 Flask 应用程序上下文。

当前应用程序的绑定键到 sqlalchemy.engine.Engine 实例的映射。 无 键引用默认引擎，并可用作 引擎 。

要自定义，请设置 SQLALCHEMY_BINDS 配置，并通过将 engine_options 参数传递给扩展来设置默认值。

这需要激活 Flask 应用程序上下文。

版本 3.0 中的新增内容。

类似于 Result.scalar() ，但会中止并显示 404 Not Found 错误，而不是返回 None 。

类似于 session.get() ，但会中止并显示 404 Not Found 错误，而不是返回 None 。

使用此扩展实例初始化 Flask 应用程序。在使用应用程序访问数据库引擎或会话之前，必须调用此方法。

这会设置默认配置值，然后在应用程序上配置扩展并为每个绑定键创建引擎。因此，必须在应用程序配置之后调用此方法。此调用之后对应用程序配置的更改不会反映出来。

使用 app.config 中的以下键

将绑定键映射到 sqlalchemy.schema.MetaData 实例。 None 键引用默认元数据，并作为 metadata 提供。

通过将 metadata 参数传递给扩展来定制默认元数据。这可用于设置命名约定。当为另一个绑定键创建元数据时，它会复制默认的命名约定。

版本 3.0 中的新增内容。

类似于 Result.scalar_one() ，但会中止，并显示 404 Not Found 错误，而不是引发 NoResultFound 或 MultipleResultsFound 。

根据当前页和每页项目数对选择语句应用偏移和限制，返回一个 Pagination 对象。

该语句应选择一个模型类，如 select(User) 。这会对结果应用 unique() 和 scalars() 修饰符，因此复合选择不会返回预期结果。

通过对所有或部分绑定键调用 metadata.reflect() 来从数据库加载表定义。

这需要激活 Flask 应用程序上下文。

一个 sqlalchemy.orm.relationship() ，它应用此扩展的 Query 类，用于动态关系和反向引用。

在版本 3.0 中更改： Query 类设置在 backref 中。

一个 sqlalchemy.orm.scoping.scoped_session ，用于创建 Session 的实例，该实例的作用域限定为当前 Flask 应用程序上下文。当应用程序上下文退出时，将移除会话，并将引擎连接返回到池中。

通过将 session_options 传递给扩展来对其进行自定义。

这需要激活 Flask 应用程序上下文。

在版本 3.0 中更改： 会话的作用域限定为当前应用程序上下文。

声明模型类 SQLAlchemy.Model 的基类。

要定义模型，请将 db.Model 子类化，而不是这个。要自定义 db.Model ，请将其子类化并将其作为 model_class 传递给 SQLAlchemy 。要在元类级别自定义 db.Model ，请将已创建的声明模型类作为 model_class 传递。

使用此绑定键来选择要与此模型的表关联的元数据和引擎。如果设置了 metadata 或 __table__ ，则忽略此设置。如果没有给出，则使用默认键 None 。

模型的 SQLAlchemy 查询。等效于 db.session.query(Model) 。可以通过覆盖 query_class 来针对每个模型进行自定义。

查询界面在 SQLAlchemy 中被认为是过时的。最好使用 session.execute(select()) 。

元类 mixin（SQLAlchemy 1.x） ¶

如果你的代码使用 SQLAlchemy 1.x API（未指定 model_class 的代码的默认值），则这些 mixin 将自动应用于 Model 类。

提供 __bind_key__ 和 __tablename__ 支持的 SQLAlchemy 声明元类。

基于其 __bind_key__ 设置模型的 metadata 的元类 mixin。

如果模型直接设置 metadata 或 __table__ ，则忽略 __bind_key__ 。如果 metadata 与父模型相同，则不会直接在子模型上设置它。

通过将 CamelCase 类名转换为 snake_case 来设置模型的 __tablename__ 的元类 mixin。为未定义 __tablename__ 的非抽象模型设置名称。如果模型未定义主键，则它不会生成名称或 __table__ ，用于单表继承。

SQLAlchemy 会话 类，根据与要查询的事物关联的元数据关联的绑定键选择要使用的引擎。

要自定义 db.session ，请对其进行子类化，并将其作为 class_ 键传递给 SQLAlchemy 中的 session_options 。

3.0 版中已更改： 已从 SignallingSession 重命名。

根据要查询的模型或表的元数据关联的 bind_key 选择一个引擎。如果未设置绑定键，则使用默认绑定。

3.0.3 版中已更改： 修复了为联接继承模型查找绑定的问题。

版本 3.0 中更改： 实现更接近于基本 SQLAlchemy 实现。

版本 2.1 中更改： 支持加入外部事务。

查询中所有项的切片，通过基于当前页和每页项数应用偏移量和限制获得。

不要手动创建分页对象。它们由 SQLAlchemy.paginate() 和 Query.paginate() 创建。

版本 3.0 中更改： 迭代分页对象会迭代其项。

版本 3.0 中更改： 手动创建实例不是公开 API。

为分页小部件生成页码。边缘和中间之间的跳过页由 None 表示。

例如，如果有 20 页，当前页为 7，则生成以下值。

1, 2, None, 5, 6, 7, 8, 9, 10, 11, None, 19, 20
left_edge (int) – 从第一页开始显示多少页。
left_current (int) – 在当前页左侧显示多少页。
right_current (int) – 在当前页右侧显示多少页。
right_edge (int) – 从最后一页开始显示多少页。
返回类型:
Iterator[int | None]
3.0 版中已更改： 提高了计算生成内容的效率。
3.0 版中更改：right_current 边界包含在内。
3.0 版中更改：所有参数都是关键字专用。
class flask_sqlalchemy.query.Query(entities, session=None)¶
SQLAlchemy Query 子类，其中包含一些在 Web 应用程序中进行查询时有用的额外方法。
这是 Model.query 的默认查询类。
3.0 版中更改：从 BaseQuery 重命名为 Query。
entities (Union[_ColumnsClauseArgument[Any], Sequence[_ColumnsClauseArgument[Any]]]) – 
session (Optional[Session]) – 
first_or_404(description=None)¶
类似于 first()，但会中止并显示 404 Not Found 错误，而不是返回 None。
description (str | None) – 在错误页面上显示的自定义消息。
返回类型:
get_or_404(ident, description=None)¶
类似于 get()，但会中止并显示 404 Not Found 错误，而不是返回 None。
ident (Any) – 要查询的主键。
description (str | None) – 在错误页面上显示的自定义消息。
返回类型:
one_or_404(description=None)¶
类似于 one()，但会中止并显示 404 Not Found 错误，而不是引发 NoResultFound 或 MultipleResultsFound。
description (str | None) – 在错误页面上显示的自定义消息。
返回类型:
版本 3.0 中的新增内容。
paginate(*, page=None, per_page=None, max_per_page=None, error_out=True, count=True)¶
根据当前页和每页的项目数应用偏移量和限制，返回一个 Pagination 对象。
page (int | None) – 当前页，用于计算偏移。在请求期间默认为 page 查询参数，否则为 1。
per_page (int | None) – 一页上的最大项目数，用于计算偏移和限制。在请求期间默认为 per_page 查询参数，否则为 20。
max_per_page (int | None) – per_page 的最大允许值，用于限制用户提供的值。对于没有限制，使用 None。默认为 100。
error_out (bool) – 如果没有返回任何项目且page不为 1，或者如果page或per_page小于 1，或者如果它们都不是整数，则中止并显示404 Not Found错误。
count (bool) – 通过发出额外的计数查询来计算值的总数。对于非常复杂的查询，这可能不准确或速度较慢，因此可以禁用它并在必要时手动设置。
返回类型:
3.0 版中更改：所有参数都是关键字专用。
在版本 3.0 中已更改： count查询更高效。
3.0 版中已更改： max_per_page 默认为 100。
flask_sqlalchemy.record_queries.get_recorded_queries()¶
获取当前会话的已记录查询信息列表。如果启用了配置 SQLALCHEMY_RECORD_QUERIES，则记录查询。
每个查询信息对象具有以下属性
statement
SQLAlchemy 生成的 SQL 字符串，其中包含参数占位符。
parameters
随 SQL 语句一起发送的参数。
start_time / end_time
有关查询何时开始执行以及何时返回结果的时间信息。准确性和值取决于操作系统。
duration
查询花费的时间（以秒为单位）。
location
有关查询在应用程序代码中何处执行的字符串描述。这可能无法计算，并且格式不稳定。
3.0 版中已更改： 已从 get_debug_queries 重命名。
3.0 版中已更改： 信息对象是一个数据类，而不是元组。
3.0 版中已更改： 信息对象属性 context 已重命名为 location。
3.0 版中已更改： 不会在调试或测试模式下自动启用。
返回类型:
list[_QueryInfo]
flask_sqlalchemy.track_modifications.models_committed¶
如果会话中有更改的模型，则在会话提交后发送此 Blinker 信号。
发送方是发出更改的应用程序。接收方会收到 changes 参数，其中包含形式为 (instance, operation) 的元组列表。操作包括 "insert"、"update" 和 "delete"。