mssql-django 常见问题解答

本文解答了mssql-django有关 Microsoft Fabric 中 SQL Server、Azure SQL 数据库、Azure SQL 托管实例 和 SQL 数据库的 Django 后端的常见问题。

General

什么是 mssql-django？

mssql-django包是由 Microsoft 维护的、用于 SQL Server 的 Django 数据库后端。 它允许 Django 应用程序连接到 SQL Server、Azure SQL 数据库、Azure SQL 托管实例 以及 Microsoft Fabric 中的 SQL 数据库。 2.0 版及更高版本通过 mssql-python 驱动（默认驱动）或 Microsoft 的 pyodbc 驱动连接。

使用 pip 安装：

pip install mssql-django

mssql-django 支持哪些版本的 Django？

mssql-django软件包版本2.0支持Django 5.2、6.0和6.1。 Django 3.2 到 5.1 版本的项目保持在 1.8.0 版本。 检查 支持生命周期 ，了解完整的兼容性矩阵。

支持哪些版本的Python？

mssql-django软件包版本 2.0 支持 Python 3.10 至 3.14。 具体的 Python 版本也必须兼容你的 Django 版本：Django 5.2 测试时可使用 Python 3.10 到 3.13，而 Django 6.0 和 6.1 则在 Python 3.12 到 3.14 上测试。 有关完整兼容性矩阵，请参阅 支持生命周期 。

mssql-django 使用哪款 Python 数据库驱动？

2.0 版及更高版本支持两种驱动程序，可为每个数据库别名选择其中一种。 pyodbc是默认配置，需要外部安装的 Microsoft ODBC 驱动 for SQL Server。 要改用 Microsoft 的 mssql-python 驱动程序（无需单独安装 ODBC 驱动程序），请将 OPTIONS 添加到该别名的 python_driver 字典中：

"OPTIONS": {
    "python_driver": "mssql_python",
},

未指定该选项的别名仍使用 pyodbc。 关于两条路径之间的行为差异，请参见 MSSQL-django 的“选择数据库驱动程序”。

mssql-django 是否由Microsoft维护？

是的。 包mssql-django由 Microsoft 维护，可在 PyPI 和 GitHub上使用。

Configuration

我在 settings.py 中使用的引擎值是什么？

在你的ENGINE配置中将"mssql"设置为DATABASES：

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>",
    },
}

应使用哪个 ODBC 驱动程序？

在默认的pyodbc路径中，使用用于 SQL Server 的 Microsoft ODBC Driver 18。 它是默认设置，如果没有安装版本18，后端会自动回退到ODBC驱动17。 仅当您需要将驱动固定到特定版本时，才在 OPTIONS 字典中显式指定该驱动，这也会关闭回退机制：

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
},

mssql-python 路径会忽略 driver 选项，并使用 pip 随附安装的 ODBC 驱动程序 18。

如何连接到Azure SQL 数据库？

使用完全限定的服务器名称和端口 1433：

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

如何使用Microsoft Entra身份验证？

在extra_params或OPTIONS设置中使用TOKEN。 TOKEN 设置可与任何 azure.identity 凭据配合使用，包括 DefaultAzureCredential 和 ManagedIdentityCredential。

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

"TOKEN": token,

有关所有受支持的方法，请参阅Microsoft Entra身份验证。

功能

mssql-django 是否支持 JSONField？

是的，SQL Server 2016 及更高版本支持 JSONField。 JSON 数据存储为 nvarchar（max），并使用SQL Server的 JSON 函数进行查询。 有关支持的查找方式及其限制，请参阅 JSONField 支持。

mssql-django 是否支持时区感知日期/时间？

是的。 当USE_TZ=True，Django 在 SQL Server 中使用 datetimeoffset 数据类型。 如果要迁移现有数据库，则需要更改现有的 datetime2 列。 请参阅 时区支持。

是否可以调用存储过程？

是的。 使用connection.cursor()和cursor.execute()来调用存储过程。 有关包括多个参数和结果集的示例，请参阅 存储过程 。

bulk_create是否返回 ID？

默认情况下，否。 选项 return_rows_bulk_insert 默认为 False. 在你的数据库 True 中将其设置为 OPTIONS，以便在批量插入后返回 ID。 对于具有触发器的表，此选项必须保留 False 。 请参阅 批量操作。

Troubleshooting

我收到“找不到 ODBC 驱动程序”。 如何解决问题？

安装 Microsoft ODBC Driver for SQL Server。 在 Linux 上，先添加 Microsoft APT 存储库，然后安装驱动程序：

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -fsSL https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
ACCEPT_EULA=Y sudo apt-get install -y msodbcsql18

在Windows，从Microsoft网站下载安装程序。 在 macOS 上，使用 Homebrew：

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18

有关特定于平台的完整说明，请参阅 “安装 ”。

为什么我的迁移失败并显示“无法更改 IDENTITY 列”？

SQL Server 不支持将列更改为或从 IDENTITY (AutoField) 列更改。 使用所需的字段类型创建新模型并手动迁移数据。 请参阅 mssql-django 中的限制和不支持的功能。

为什么 bulk_update 在处理可为空字段时会失败？

后端会自动处理所有值均为 NULL 的更新。 如果你需要控制占位符值，请在bulk_update中使用default参数，这样可使NULL不会出现在会导致 SQL Server 类型推断错误的CASE WHEN ... THEN NULL表达式中：

Product.objects.bulk_update(products, ["description"], default="")

有关详细信息，请参阅 批量操作 。

  • 上次更新时间为