Django 6.1 升级避坑：数据库版本不兼容怎么解决？

升级 Django 时，很多人只盯着 pip install 是否成功，却忽略了生产数据库版本。Django 6.1 RC1 已经提高多种数据库的最低要求：旧项目即使代码没有报错，也可能在连接数据库时才发现版本不受支持。

这次变化影响最明显的是仍在使用 MySQL 8.0、PostgreSQL 14 或 MariaDB 10.6 的项目。本文把官方支持矩阵转成一个可执行检查，并给出不把"框架升级"和"数据库升级"混成一次豪赌的迁移顺序。

Django 6.1 当前仍是候选版本，本文用于提前评估和预演。生产环境升级前，请再次核对最终版发布说明与所用数据库驱动。

先看结论：最低版本变了

根据 Django 6.1 发布说明，主要数据库最低版本如下：

数据库	Django 6.1 最低版本	常见不兼容版本
PostgreSQL	15	14 及以下
MySQL	8.4	8.0、8.1、8.2、8.3
MariaDB	10.11	10.6 及以下
SQLite	3.37	3.31 等旧版本

这并不是 Django 随意"砍版本"。官方说明指出，上游数据库自身的维护周期已经变化：MySQL 8.0 的上游支持在 2026 年 4 月结束，MariaDB 10.6 在 2026 年 7 月结束，PostgreSQL 14 也将在 2026 年 11 月结束。

我把版本矩阵做成了检查器

升级前最怕靠记忆判断。可以把最低版本固化到脚本或持续集成中：

python 复制代码

MINIMUMS = {
    "PostgreSQL": (15,),
    "MySQL": (8, 4),
    "MariaDB": (10, 11),
    "SQLite": (3, 37),
}

def supported(current: str, minimum: tuple[int, ...]) -> bool:
    value = tuple(int(part) for part in current.split("."))
    return value >= minimum

我对新旧版本各选了几个样本，结果如下：

数据库	样本版本	检查结果
PostgreSQL	14 / 15 / 18	不通过 / 通过 / 通过
MySQL	8.0 / 8.4 / 9.0	不通过 / 通过 / 通过
MariaDB	10.6 / 10.11 / 11.4	不通过 / 通过 / 通过
SQLite	3.31 / 3.37 / 3.49	不通过 / 通过 / 通过

这个脚本只验证版本矩阵，不会假装替代真实连接测试。数据库驱动、字符集、扩展、排序规则和 SQL 行为仍需要在目标环境中验证。

为什么 `pip install` 成功仍可能上线失败

Python 包管理器只负责安装 Django 和数据库驱动，它通常不知道生产服务器运行的是哪个数据库版本。以下场景都可能在部署阶段才暴露：

开发环境使用新版 SQLite，生产仍是旧 MySQL；
持续集成只运行 SQLite，没有覆盖 PostgreSQL；
应用容器升级了，托管数据库没有升级；
数据库驱动能安装，但连接后被 Django 的版本检查拒绝；
测试通过，却依赖某个数据库特有行为。

因此，升级评估必须同时记录四个版本：Python、Django、数据库驱动和数据库服务端。

最稳妥的升级顺序

第一步：建立真实资产清单

不要只看 settings.py。先在开发、测试、预发布和生产环境分别执行数据库版本查询：

sql 复制代码

-- PostgreSQL
SELECT version();

-- MySQL / MariaDB
SELECT VERSION();

-- SQLite
SELECT sqlite_version();

同时记录连接驱动版本，例如 psycopg 或 mysqlclient。如果使用云数据库，还要核对实例允许升级到哪些主版本、停机窗口和回滚限制。

第二步：先让现有 Django 连接新数据库

不要在同一时间同时升级 Django 和数据库。更安全的路径是：

保持当前 Django 版本；
在克隆数据或预发布环境升级数据库；
运行完整测试和关键查询；
确认现有应用与新数据库兼容；
再升级 Django 6.1。

这样发生错误时，排查范围只有一层。若框架和数据库同时改变，迁移失败、SQL 差异和驱动问题会混在一起。

第三步：让持续集成覆盖生产数据库

RuyiBookCourse 的 Django 实践建议可以保留 SQLite 作为快速单元测试数据库，同时在持续集成中增加 PostgreSQL 或 MySQL。这里的重点不是二选一，而是分层：

SQLite：快速反馈、基础逻辑；
生产同款数据库：迁移、约束、锁、事务和数据库特性；
预发布环境：真实连接参数、数据量和部署流程。

只使用 SQLite 的测试，无法证明生产数据库升级安全。

第四步：升级框架但暂不启用全部新特性

先安装 Django 6.1 RC1 到独立分支或实验环境，运行：

bash 复制代码

python manage.py check
python manage.py makemigrations --check --dry-run
python manage.py migrate --plan
python manage.py test

然后检查弃用警告和第三方包兼容性。不要一边升级框架，一边重写 ORM、切换缓存、替换任务队列。

第五步：准备备份、停机与回滚

数据库大版本升级不是普通代码发布。至少要准备：

可恢复的完整备份；
恢复演练结果；
允许写入暂停的维护窗口；
应用版本与数据库版本的兼容表；
升级失败后的回滚或前滚方案；
数据校验查询和关键业务抽样。

如果云服务不支持原地降级，就不能把"把版本号改回去"当作回滚方案。

MySQL 8.0 项目怎么处理

MySQL 8.0 是这次最容易踩坑的版本，因为它长期普及，而 Django 6.1 的最低要求提高到了 8.4。建议按下面顺序处理：

检查操作系统或云平台是否支持 MySQL 8.4；
核对 mysqlclient 与 Python 版本；
在副本或预发布实例上升级；
检查字符集、排序规则和 SQL 模式；
运行迁移与关键 ORM 查询；
验证备份恢复和复制链路；
最后再让 Django 6.1 连接。

如果短期无法升级数据库，就继续使用受支持的 Django 版本，不要通过修改 Django 源码或屏蔽版本检查强行上线。

PostgreSQL 14 项目怎么处理

PostgreSQL 14 到 15 是主版本升级。除了应用测试，还要检查扩展版本、统计信息、连接池和备份工具。使用 pg_upgrade、逻辑复制还是云服务原地升级，应根据数据规模和停机要求选择，不能只给出一条通用命令。

对于依赖 PostgreSQL 特有功能的项目，持续集成最好直接运行 PostgreSQL，而不是只依赖 SQLite 模拟。

三个危险做法

1. 修改源码强行跳过版本检测

能够建立连接不等于获得官方支持。屏蔽检查会把已知不兼容变成运行期随机错误，也会让后续排障失去可靠基线。

2. 直接在唯一生产实例试升级

没有副本、备份验证和回滚路径的数据库升级，本质上是在拿生产数据做实验。

3. 把开发环境通过当成完成

开发机的 SQLite 或 Docker 数据库，与生产托管实例的版本、扩展、字符集和数据量都可能不同。验收必须覆盖生产同款环境。

升级前检查表

Python 版本在 Django 6.1 支持范围内；
数据库服务端达到最低版本；
数据库驱动支持 Python、Django 和服务端；
现有 Django 已在新数据库上跑过完整测试；
持续集成包含生产同款数据库；
迁移计划、关键 SQL 和第三方包已经核验；
备份可以真实恢复；
回滚或前滚路径已经演练；
最终版 Django 6.1 发布说明已重新核对。

Django 升级失败，很多时候不是框架代码写错，而是环境矩阵没有被当成一个整体。把版本要求变成机器可执行的检查，把数据库升级和框架升级拆成两个可验证步骤，才是老项目平稳迁移的关键。

Django 6.1 升级避坑：数据库版本不兼容怎么解决？