API

扩展

class flask_sqlalchemy.SQLAlchemy(app=None, *, metadata=None, session_options=None, query_class=<class 'flask_sqlalchemy.query.Query'>, model_class=<class 'flask_sqlalchemy.model.Model'>, engine_options=None, add_models_to_shell=True, disable_autonaming=False)

将 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。在定义模型时，这会很方便。

参数:

  • app (Flask | None) – 立即在此 Flask 应用程序上调用 init_app()。

  • metadata (sa.MetaData | None) – 将此用作默认 sqlalchemy.schema.MetaData。对于设置命名约定很有用。

  • session_options (dict[str, t.Any] | None) – session 用于创建每个会话实例的参数。一个 scopefunc 键将传递给范围会话，而不是会话实例。有关参数列表，请参阅 sqlalchemy.orm.sessionmaker。

  • query_class (type[Query]) – 将此用作模型和动态关系的默认查询类。在 SQLAlchemy 中，查询接口被认为是过时的。

  • model_class (_FSA_MCT) – 在创建声明模型类 Model 时，将此用作模型基类。对于进一步的自定义，它也可以是一个完全创建的声明模型类。

  • engine_options (dict[str, t.Any] | None) – 创建每个引擎时使用的默认参数。这些优先级低于应用程序配置。有关参数列表，请参阅 sqlalchemy.create_engine()。

  • add_models_to_shell (bool) – 将 db 实例和所有模型类添加到 flask shell。

  • disable_autonaming (bool) –

在 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 参数。

Model

一个 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 参数传递给扩展来定制此模型。

Query

由 Model.query 和 lazy="dynamic" 关系使用的默认查询类。

警告

查询界面在 SQLAlchemy 中被视为传统。

通过将 query_class 参数传递给扩展来定制它。

Table

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

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

参数:

  • bind_key – 用于选择不同的元数据。

  • args – 传递给基类的参数。这些通常是表的名称、列和约束。

  • kwargs – 传递给基类的参数。

在 3.0 版中更改：这是 SQLAlchemy 的 Table 的子类，而不是一个函数。

create_all(bind_key='__all__')

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

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

参数:

bind_key (str | None | list[str | None]) – 要为其创建表的绑定键或键列表。默认为所有绑定。

返回类型:

无

在版本 3.0 中更改： 将 bind 参数重命名为 bind_key。删除了 app 参数。

在版本 0.12 中更改： 添加了 bind 和 app 参数。

drop_all(bind_key='__all__')

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

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

参数:

bind_key (str | None | list[str | None]) – 要从中删除表的绑定键或键列表。默认为所有绑定。

返回类型:

无

在版本 3.0 中更改： 将 bind 参数重命名为 bind_key。删除了 app 参数。

在版本 0.12 中更改： 添加了 bind 和 app 参数。

dynamic_loader(argument, **kwargs)

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

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

参数:

  • argument (Any) –

  • kwargs (Any) –

返回类型:

RelationshipProperty[Any]

属性 引擎: 引擎

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

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

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

属性 引擎: 映射[字符串 | 无, 引擎]

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

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

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

版本 3.0 中的新增内容。

first_or_404(statement, *, description=None)

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

参数:

  • statement (Select) – 要执行的 select 语句。

  • description (str | None) – 在错误页面上显示的自定义消息。

返回类型:

任意

版本 3.0 中的新增内容。

get_engine(bind_key=None, **kwargs)

获取当前应用程序给定绑定键的引擎。这需要激活 Flask 应用程序上下文。

参数:

  • bind_key (str | None) – 引擎的名称。

  • kwargs (Any) –

返回类型:

引擎

自版本 3.0 起弃用：将在 Flask-SQLAlchemy 3.2 中移除。请改用 engines[key]。

在版本 3.0 中更改： 将 bind 参数重命名为 bind_key。删除了 app 参数。

get_or_404(entity, ident, *, description=None, **kwargs)

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

参数:

  • entity (type[_O]) – 要查询的模型类。

  • ident (Any) – 要查询的主键。

  • description (str | None) – 在错误页面上显示的自定义消息。

  • kwargs (Any) – 传递给 session.get() 的额外参数。

返回类型:

_O

在版本 3.1 中更改： 将额外的关键字参数传递给 session.get()。

版本 3.0 中的新增内容。

init_app(app)

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

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

使用 app.config 中的以下键

参数:

app (Flask) – 要初始化的 Flask 应用程序。

返回类型:

无

property metadata: MetaData

如果未设置绑定键，则 Model 和 Table 使用的默认元数据。

metadatas: dict[str | None, MetaData]

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

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

版本 3.0 中的新增内容。

one_or_404(statement, *, description=None)

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

参数:

  • statement (Select) – 要执行的 select 语句。

  • description (str | None) – 在错误页面上显示的自定义消息。

返回类型:

任意

版本 3.0 中的新增内容。

paginate(select, *, page=None, per_page=None, max_per_page=None, error_out=True, count=True)

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

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

参数:

  • select (Select) – 要分页的 select 语句。

  • 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 中已更改： count查询更高效。

版本 3.0 中的新增内容。

reflect(bind_key='__all__')

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

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

参数:

bind_key (str | None | list[str | None]) – 用于反映表的绑定键或键列表。默认为所有绑定。

返回类型:

无

在版本 3.0 中更改： 将 bind 参数重命名为 bind_key。删除了 app 参数。

在版本 0.12 中更改： 添加了 bind 和 app 参数。

relationship(*args, **kwargs)

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

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

参数:

  • args (Any) –

  • kwargs (Any) –

返回类型:

RelationshipProperty[Any]

session

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

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

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

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

Model

class flask_sqlalchemy.model.Model

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

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

__bind_key__

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

__tablename__

数据库中的表名。这是 SQLAlchemy 所需的；但是，如果模型定义了主键，Flask-SQLAlchemy 将自动设置它。如果 __table__ 或 __tablename__ 显式设置，则将使用它们。

query: t.ClassVar[Query]

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

警告

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

query_class

由 query 使用的查询类。默认为 SQLAlchemy.Query，它默认为 Query。

Query 的别名

元类 mixin（SQLAlchemy 1.x）

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

类 flask_sqlalchemy.model.DefaultMeta(名称, 基础, d, **kwargs)

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

参数:
类 flask_sqlalchemy.model.BindMetaMixin(名称, 基础, d, **kwargs)

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

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

参数:
类 flask_sqlalchemy.model.NameMetaMixin(名称, 基础, d, **kwargs)

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

参数:

会话

类 flask_sqlalchemy.session.会话(db, **kwargs)

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

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

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

参数:
get_bind(mapper=无, clause=无, bind=无, **kwargs)

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

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

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

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

参数:
返回类型:

Engine | Connection

分页

class flask_sqlalchemy.pagination.Pagination

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

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

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

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

page: int

当前页。

per_page: int

一页上的最大项目数。

items: list[Any]

当前页上的项目。遍历分页对象等效于遍历项目。

total: int | None

所有页面的项目总数。

property first: int

页面上第一个项目的编号，从 1 开始，如果没有项目则为 0。

版本 3.0 中的新增内容。

property last: int

页面上最后一个项目的编号，从 1 开始（包含），如果没有项目则为 0。

版本 3.0 中的新增内容。

property pages: int

总页数。

属性 has_prev: bool

True 如果这不是第一页。

属性 prev_num: int | None

上一页的页码，如果这是第一页，则为 None。

prev(*, error_out=False)

查询 Pagination 对象的上一页。

参数:

error_out (bool) – 如果没有返回任何项目且page不为 1，或者如果page或per_page小于 1，或者如果它们都不是整数，则中止并显示404 Not Found错误。

返回类型:

分页

属性 has_next: bool

True 如果这不是最后一页。

属性 next_num: int | None

下一页的页码，如果这是最后一页，则为 None。

next(*, error_out=False)

查询 Pagination 对象的下一页。

参数:

error_out (bool) – 如果没有返回任何项目且page不为 1，或者如果page或per_page小于 1，或者如果它们都不是整数，则中止并显示404 Not Found错误。

返回类型:

分页

iter_pages(*, left_edge=2, left_current=2, right_current=4, right_edge=2)

为分页小部件生成页码。边缘和中间之间的跳过页由 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"。

flask_sqlalchemy.track_modifications.before_models_committed

此信号的工作方式与 models_committed 完全相同，但会在提交发生之前发出。