从 2.0 版本开始，mssql-django可通过两个 Python 数据库驱动程序中的任意一个进行连接：
- pyodbc 配备了外部安装的 Microsoft ODBC SQL Server 驱动。 这个驱动是默认的。
- mssql-python，Microsoft 的 Python 驱动，不需要单独安装 ODBC 驱动。
你为每个数据库别名选择驱动程序。 一个别名可以使用mssql-python，而项目的其余部分则继续使用pyodbc。
ENGINE值在这两种情况下都保持"mssql"不变。
在 mssql-python 中选择别名
在该别名的python_driver字典中设置OPTIONS选项：
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "<database>",
"USER": "<user_id>",
"PASSWORD": "<password>",
"HOST": "<server>.database.windows.net",
"PORT": "1433",
"OPTIONS": {
"python_driver": "mssql_python",
"extra_params": "Encrypt=yes",
},
},
}
后端接受 "mssql_python"、"mssql-python" 和 "python"，并且比较时不区分大小写。 省略 python_driver、留空，或者设置为 "pyodbc" 保留默认驱动。 因为设置是按别名设置的，你可以通过移除这个选项，一次回滚一个数据库。
仅当某个别名选择了 mssql-python 模块时，才会导入该模块。 如果安装的版本早于 1.15.0，后端会抛出 ImproperlyConfigured，并指明所需版本。
安装要求
pip install mssql-django 安装两个驱动程序。 该 mssql-python 路径没有单独安装ODBC驱动。 仅安装 --no-deps，或者使用不镜像 mssql-python 的私有索引，都会导致该软件包缺失，并使该别名在导入时失效。
安装 mssql-python的平台前置条件，包括macOS上的OpenSSL和Linux上的必要库。
由于 mssql-python 是必需的依赖， mssql-django 2.0 版本只安装在兼容 mssql-python 发行版的平台上。 关于平台列表，请参见 mssql-django 支持和生命周期。
行为差异
这两个驱动程序构建不同的连接字符串，并暴露不同的连接关键词。 在更换别名之前，请先阅读本节。
连接设置
| 设置 | pyodbc | mssql-python |
|---|---|---|
HOST 和 PORT |
根据驱动程序和 PORT，输出为 host_is_server、SERVER 或 SERVERNAME 加 SERVER。 |
始终以 SERVER=<host>,<port> 的形式输出。 空 HOST 变为 localhost。 |
driver |
选择 ODBC 驱动程序。 默认使用适用于 SQL Server 的 Microsoft ODBC Driver 18，并自动回退到 Driver 17。 | 已忽略。 没有 Driver 17 回退。 |
dsn |
支持. | 已忽略。 |
host_is_server |
支持FreeTDS。 | 已忽略。 |
unicode_results |
支持. | 已忽略。 |
TOKEN |
支持. | 支持. 提供Authentication，但不带TOKEN、PASSWORD或USER关键字。 你的应用程序会获取并续订令牌。 |
DATABASE_CONNECTION_POOLING |
适用。 | 适用。 |
超时、重试、隔离级别、排序规则和 return_rows_bulk_insert 在两条路径上的行为相同。
额外的连接参数
mssql-python 1.15 会 extra_params 对准允许列表进行验证，并拒绝允许列表以外的任何内容。 支持的关键词包括 Authentication， Encrypt， TrustServerCertificate， PacketSizeIpAddressPreferenceKeepAliveIntervalKeepAliveConnectRetryIntervalApplicationIntentServerSPNConnectRetryCountHostnameInCertificateServerCertificateMultiSubnetFailover。
驱动程序会拒绝 APP、LongAsMax、Description 和 AnsiNPW，以及 pyodbc 专用关键字，例如 QuotedId、WSID、Regional、Current Language、Network Library、ColumnEncryption、Connect Timeout、UseFMTONLY、MARS_Connection、SERVERNAME、DSN 和 DRIVER。 在切换别名之前先移除这些关键词，并用该 connection_timeout 选项代替 Connect Timeout。
当 extra_params 设置一个后端也生成的关键词时，显式值获胜。
多重活动结果集
在 pyodbc 路径中，当别名在 Windows 上使用 Microsoft ODBC 驱动程序时，后端会添加 MARS_Connection=yes。
extra_params 中的显式 MARS_Connection 值会改为被采用，且匹配忽略大小写。
mssql-python路径从未启用MARS系统，且拒绝MARS_Connection关键词，因此你无法为该别名开启MARS。
在没有 MARS 的情况下，QuerySet.iterator() 会先将整个结果集读入内存，然后才返回各行，以便嵌套查询能够重用该连接，而 chunk_size 也不会改变这一点。 将大型查询集的内存开销考虑在内。
对于拒绝MARS的终端，如Microsoft Fabric Warehouse，请参见禁用MARS。
编码配置
两个驱动程序都接受 setencoding 和 setdecoding，每个条目都映射到所选驱动程序的连接方式。 每个 setdecoding 条目在两条路径中都需要有一个 sqltype 键，并且同一个条目在任一驱动程序上都适用。 一个区别是： mssql-python 接受 -99 ， SQL_WMETADATA拒绝 pyodbc 。
在驱动程序之间进行选择
对于新的开发，请使用 mssql-python。 它移除了容器镜像和应用服务部署中 ODBC 驱动安装步骤。
当你的部署依赖于命名的 DSN、FreeTDS、通过 pyodbc 关键字启用的 Always Encrypted、由你自行管理的 ODBC 驱动程序版本或 MARS 时，请使用 ColumnEncryption。 关于MARS在每条路径上的要求，请参见 多重活跃结果集。
现有项目可以继续。pyodbc 它仍然是默认设置，并且得到了全面支持。 进行迁移时，每次只切换一个别名，并先针对它运行测试套件，再迁移其余别名。