Django4.0启动服务/执行makemigrations报explain_query属性错误

问题场景 #

使用Django 4.0框架，启动服务或运行makemigrations命令时触发报错，完整追踪堆栈如下：

Traceback (most recent call last):
  File "manage.py", line 24, in <module>
    execute_from_command_line(sys.argv)
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\core\management\__init__.py", line 446, in execute_from_command_line
    utility.execute()
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\core\management\__init__.py", line 440, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\core\management\base.py", line 414, in run_from_argv
    self.execute(*args, **cmd_options)
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\core\management\base.py", line 460, in execute
    output = self.handle(*args, **options)
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\core\management\base.py", line 98, in wrapped
    res = handle_func(*args, **kwargs)
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\core\management\commands\makemigrations.py", line 119, in handle
    loader.check_consistent_history(connection)
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\db\migrations\loader.py", line 313, in check_consistent_history
    applied = recorder.applied_migrations()
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\db\migrations\recorder.py", line 82, in applied_migrations
    return {
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\db\models\query.py", line 320, in __iter__
    self._fetch_all()
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\db\models\query.py", line 1507, in _fetch_all
    self._result_cache = list(self._iterable_class(self))
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\db\models\query.py", line 57, in __iter__
    results = compiler.execute_sql(
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\django\db\models\sql\compiler.py", line 1348, in execute_sql
    sql, params = self.as_sql()
  File "C:\Users\Administrator\AppData\Local\Programs\Python\Python38-32\lib\site-packages\sql_server\pyodbc\compiler.py", line 294, in as_sql
    if self.query.explain_query:
AttributeError: 'Query' object has no attribute 'explain_query'

报错原因 #

该错误由SQL Server数据库驱动与Django 4.0版本不兼容导致：

• 报错触发位置为第三方库sql_server.pyodbc的SQL编译逻辑，代码尝试读取Django ORM中Query对象的explain_query属性，但该属性在Django 4.0版本中已被重构移除，替换为explain_info属性，旧版驱动未做版本适配，因此抛出属性不存在的异常。
• 当前环境安装的django-pyodbc、django-pyodbc-azure或旧版django-sql-server驱动，最高仅兼容Django 3.2及更早版本，没有针对Django 4.0做适配调整。

修复方案 #

按需选择以下任意一种方案处理即可：

• 替换为官方维护的兼容Django 4.0的SQL Server驱动（生产环境推荐）
  1. 卸载环境中旧的不兼容驱动：

     pip uninstall -y django-pyodbc django-pyodbc-azure django-sql-server
     

  2. 安装适配Django 4.0的新版驱动：

     pip install mssql-django
     

  3. 修改项目settings.py中的数据库配置，将ENGINE字段值从原有的sql_server.pyodbc修改为mssql，其余HOST、NAME、USER、PASSWORD等连接参数保持原有配置不变。
• 降级Django版本匹配旧驱动
  如果项目必须使用旧版sql_server.pyodbc驱动，将Django降级到3.2 LTS版本即可：

  pip install "Django>=3.2,<4.0"
  

• 临时补丁（仅用于本地调试，不推荐生产环境使用）
  定位到Python环境下sql_server/pyodbc/compiler.py文件的第294行，将原有判断逻辑：

  if self.query.explain_query:
  

  修改为兼容新旧版本属性的写法：

  if getattr(self.query, 'explain_query', False) or getattr(self.query, 'explain_info', None):
  

  注意该修改仅能修复当前这一处报错，后续运行中仍可能触发其他Django 4.0相关的兼容问题。

内容的提问来源于stack exchange，提问作者Neil Faulkner