配置

配置键

在调用 SQLAlchemy.init_app() 时，配置会从 Flask app.config 中加载。之后不再读取配置。因此，所有配置都必须在初始化应用程序之前进行。

flask_sqlalchemy.config.SQLALCHEMY_DATABASE_URI

用于默认引擎的数据库连接 URI。它可以是字符串或 SQLAlchemy URL 实例。请参阅下方和 引擎配置 以获取示例。

此项和 SQLALCHEMY_BINDS 中至少一项必须设置。

在版本 3.0 中更改： 如果未设置，不再默认为内存中 SQLite 数据库。

flask_sqlalchemy.config.SQLALCHEMY_ENGINE_OPTIONS

要传递给 sqlalchemy.create_engine() 的参数字典，用于默认引擎。

这优先于 SQLAlchemy 的 engine_options 参数，该参数可用于为所有引擎设置默认选项。

在版本 3.0 中更改： 仅适用于默认绑定。

在版本 2.4 中新增。

flask_sqlalchemy.config.SQLALCHEMY_BINDS

将绑定键映射到引擎选项的字典。该值可以是字符串或 SQLAlchemy URL 实例。或者它可以是参数字典，包括 url 键，该键将传递给 sqlalchemy.create_engine()。 None 键可用于配置默认绑定，但 SQLALCHEMY_ENGINE_OPTIONS 和 SQLALCHEMY_DATABASE_URI 优先。

此项和 SQLALCHEMY_DATABASE_URI 必须至少设置一项。

0.12 版新增。

flask_sqlalchemy.config.SQLALCHEMY_ECHO

每个引擎的 echo 和 echo_pool 的默认值。这有助于快速调试 SQLAlchemy 发出的连接和查询。

3.0 版更改：除了 echo 之外，还设置 echo_pool。

flask_sqlalchemy.config.SQLALCHEMY_RECORD_QUERIES

如果启用，将在请求期间记录有关每个查询的信息。使用 get_recorded_queries() 获取在请求期间发出的查询列表。

3.0 版更改：不在调试或测试模式下自动启用。

flask_sqlalchemy.config.SQLALCHEMY_TRACK_MODIFICATIONS

如果启用，将记录模型上的所有 insert、update 和 delete 操作，然后在调用 session.commit() 时发送到 models_committed 和 before_models_committed 信号中。

这会给每个会话增加大量的开销。最好直接使用 SQLAlchemy 的 ORM 事件 来获取所需的确切信息。

版本 3.0 中已更改： 默认情况下已禁用。

版本 2.0 中的新增功能。

版本 3.1 中已更改： 已移除 SQLALCHEMY_COMMIT_ON_TEARDOWN。

版本 3.0 中已更改： 已移除 SQLALCHEMY_NATIVE_UNICODE、SQLALCHEMY_POOL_SIZE、SQLALCHEMY_POOL_TIMEOUT、SQLALCHEMY_POOL_RECYCLE 和 SQLALCHEMY_MAX_OVERFLOW。

连接 URL 格式

有关语法、方言和选项的完整说明，请参阅 SQLAlchemy 关于 引擎配置 的文档。

基本数据库连接 URL 使用以下格式。用户名、密码、主机和端口是可选的，具体取决于数据库类型和配置。

dialect://username:password@host:port/database

以下是一些示例连接字符串

# SQLite, relative to Flask instance path
sqlite:///project.db

# PostgreSQL
postgresql://scott:tiger@localhost/project

# MySQL / MariaDB
mysql://scott:tiger@localhost/project

SQLite 不使用用户或主机，因此其 URL 总是以三个斜杠开头，而不是两个。 dbname 值是一个文件路径。绝对路径以第四个斜杠开头（在 Linux 或 Mac 上）。相对路径相对于 Flask 应用程序的 instance_path。

默认驱动程序选项

为 SQLite 和 MySQL 引擎设置了一些默认选项，以便在 Web 应用程序中默认情况下更易于使用它们。

SQLite 相对文件路径相对于 Flask 实例路径，而不是当前工作目录。内存数据库使用静态池和 check_same_thread 在请求之间工作。

MySQL（和 MariaDB）服务器配置为断开空闲 8 小时的连接，这可能会导致类似 2013: Lost connection to MySQL server during query 的错误。默认 pool_recycle 值为 2 小时（7200 秒），用于在该超时之前重新创建连接。

引擎配置优先级

因为 Flask-SQLAlchemy 支持多个引擎，所以对于哪个配置覆盖其他配置，有规则可循。大多数应用程序只有一个数据库，只需要使用 SQLALCHEMY_DATABASE_URI 和 SQLALCHEMY_ENGINE_OPTIONS。

超时

某些数据库可能被配置为在一段时间后关闭非活动连接。MySQL 和 MariaDB 默认配置为此，但数据库服务也可能配置此类限制。这可能会导致类似 2013: Lost connection to MySQL server during query 的错误。

如果你遇到此错误，请尝试将引擎选项中的 pool_recycle 设置为小于数据库超时时间的某个值。

或者，如果你预计数据库经常关闭连接（例如，如果它在可能重启的容器中运行），则可以尝试设置 pool_pre_ping。

有关更多信息，请参阅 SQAlchemy 关于 处理断开连接 的文档。