Django5.1（119）—— 数据库（API参考）

数据库

Django 官方支持以下数据库：

• PostgreSQL
• MariaDB
• MySQL
• Oracle
• SQLite

还有一些第三方提供的 数据库后端。

Django 试图在所有数据库后端上支持尽可能多的功能。然而，并不是所有的数据库后端都是一样的，我们不得不在设计上决定支持哪些功能，以及我们可以安全地做出哪些假设。

该文件描述了一些可能与 Django 使用有关的功能。 它不能替代特定于服务器的文档或参考手册。

通用注意事项

持久连接

持久连接避免了在每个 HTTP 请求中重新建立与数据库的连接的开销。它们由 CONN_MAX_AGE 参数控制，该参数定义了连接的最大生命周期。它可以独立设置在每个数据库上。

默认值是 0，保留了每次请求结束时关闭数据库连接的历史行为。要启用持久连接，可将 CONN_MAX_AGE 设置为正整数秒。对于无限制的持久连接，将其设置为 None。

连接管理

当 Django 第一次进行数据库查询时，就会打开一个与数据库的连接。它保持这个连接的开放性，并在以后的请求中重复使用。一旦连接超过了 CONN_MAX_AGE 所定义的最大时长，或者当它不再可用时，Django 就会关闭这个连接。

详细来说，Django 每当需要连接数据库而又没有连接的时候，就会自动打开一个连接到数据库——或者是因为这是第一个连接，或者是因为之前的连接被关闭。

在每次请求开始时，如果连接已达到最大时长，Django 就会关闭连接。如果你的数据库在一段时间后终止了空闲的连接，你应该将 CONN_MAX_AGE 设置为一个较低的值，这样 Django 就不会尝试使用一个已经被数据库服务器终止的连接。（这个问题可能只影响到流量很低的网站。）

在每个请求结束时，如果连接已达到其最大寿命或处于不可恢复的错误状态，Django 将关闭连接。如果在处理请求时发生了任何数据库错误，Django 会检查连接是否仍然可用，如果不可用，将关闭连接。因此，数据库错误最多会影响每个应用程序工作线程的一个请求；如果连接变得无法使用，下一个请求将获得一个新的连接。

将 CONN_HEALTH_CHECKS 设置为 True 可以用于提高连接复用的健壮性，并防止在连接已被数据库服务器关闭且现在已准备好接受和提供新连接时发生错误，例如在数据库服务器重新启动后。健康检查只在每个请求中执行一次，只有在处理请求期间访问数据库时才会执行。

附加说明

由于每个线程都维护自己的连接，所以你的数据库必须支持至少与你的工作线程一样多的同时连接。

有时，数据库不会被大多数视图访问，例如因为它是外部系统的数据库，或者由于缓存的原因。在这种情况下，你应该将 CONN_MAX_AGE 设置为一个低值，甚至 0，因为维护一个不太可能被重复使用的连接是没有意义的。这将有助于保持这个数据库的同时连接数较少。

开发服务器每处理一个请求都会创建一个新的线程，消除了持久连接的影响。在开发过程中不要启用它们。

当 Django 建立与数据库的连接时，它会根据所使用的后端设置相应的参数。如果你启用了持久化连接，就不再每次请求都重复这种设置。如果你修改了连接的隔离级别或时区等参数，你应该在每次请求结束时恢复 Django 的默认值，在每次请求开始时强制设置一个合适的值，或者禁用持久连接。

If a connection is created in a long-running process, outside of Django’s request-response cycle, the connection will remain open until explicitly closed, or timeout occurs. You can use django.db.close_old_connections() to close all old or unusable connections.

编码

Django 假设所有的数据库都使用 UTF-8 编码。使用其他编码可能会导致意外的行为，比如数据库中的数据在 Django 中是有效的，却出现“value too long”的错误。