无法将Django连接至SQL Server，报错'mssql'非可用数据库后端

问题详情 #

执行项目启动命令 py manage.py runserver 时，出现以下错误：

django.core.exceptions.ImproperlyConfigured: 'mssql' isn't an available database backend or couldn't be imported. Check the above exception. To use one of the built-in backends, use 'django.db.backends.XXX', where XXX is one of:
'mysql', 'oracle', 'postgresql', 'sqlite3'

相关环境版本：

• Python：3.10.11
• Django：3.2.19

操作流程：

1. 创建Django项目

   django-admin startproject mysite
   

2. 修改mysite/mysite/settings.py中的数据库配置：

   DATABASES = {
       "default": {
           "ENGINE": "mssql",
           "NAME": "DATABASE_NAME",
           "USER": "USER_NAME",
           "PASSWORD": "PASSWORD",
           "HOST": "HOST_ADDRESS",
           "PORT": "1433",
           "OPTIONS": {"driver": "ODBC Driver 17 for SQL Server", 
           },
       },
   }
   

3. 运行项目触发报错

解决方法 #

原因说明 #

Django 3.2的内置数据库后端不包含SQL Server适配，必须安装第三方兼容包，并修正数据库引擎配置。

步骤 #

1. 安装SQL Server适配包
   在命令行执行以下命令安装兼容Django3.2的后端包：

   pip install django-mssql-backend==2.8.1
   

   （版本号可根据实际兼容情况调整，确保与Python3.10、Django3.2匹配）

2. 修正settings.py中的数据库配置
   将ENGINE字段值从"mssql"改为"sql_server.pyodbc"，修改后的配置如下：

   DATABASES = {
       "default": {
           "ENGINE": "sql_server.pyodbc",
           "NAME": "DATABASE_NAME",
           "USER": "USER_NAME",
           "PASSWORD": "PASSWORD",
           "HOST": "HOST_ADDRESS",
           "PORT": "1433",
           "OPTIONS": {
               "driver": "ODBC Driver 17 for SQL Server",
           },
       },
   }
   

3. 验证并启动项目
   先执行数据库迁移命令确认配置有效：

   py manage.py migrate
   

   再启动项目：

   py manage.py runserver
   

额外注意：确保Windows环境已安装ODBC Driver 17 for SQL Server，若未安装需先完成驱动安装。

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