mssql-django 常見問題

本文回答關於 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 以及 Microsoft Fabric 中 SQL 資料庫的 mssql-django Django 後端常見問題。

General

什麼是 mssql-django？

mssql-django 套件是由 Microsoft 維護、供 SQL Server 使用的 Django 資料庫後端。 它允許 Django 應用程式使用 pyodbc 驅動程式連接 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 以及 Microsoft Fabric 中的 SQL 資料庫。

用 PIP 安裝：

pip install mssql-django

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

該 mssql-django 套件 v1.7 支援 Django 3.2、4.0、4.1、4.2、5.0、5.1、5.2 及 6.0。 請查看 支援生命週期 以了解完整的相容性矩陣。

支援哪些版本的 Python？

此mssql-django套件支援 Python 3.8 及更新版本。 特定的 Python 版本也必須與你的 Django 版本相容。 例如，Django 5.0 需要 Python 3.10 及以上版本，而 Django 6.0 則需要 Python 3.12 及以上版本。 完整相容性矩陣請參閱 支援生命週期 。

mssql-django 是由 Microsoft 維護的嗎？

Yes. 該mssql-django套件由 Microsoft 維護，並可在 PyPI 和 GitHub 上取得。

設定

settings.py 裡我該用什麼 ENGINE 值？

在你的ENGINE設定中設定"mssql"為DATABASES：

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

我應該使用哪一款 ODBC 驅動程式？

使用 Microsoft ODBC Driver 18 for SQL Server。 這是 1.7 及以後的預設 mssql-django ，如果沒安裝 18 版，後端會自動回退到 ODBC Driver 17。 只有在需要釘選特定版本時，才在 OPTIONS 字典中明確指定驅動程式：

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

我要如何連接到 Azure SQL Database？

使用完整限定的伺服器名稱，埠號為 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 認證？

在OPTIONS或TOKEN設定中使用extra_params。 該 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 認證以了解所有支援的方法。

Features

mssql-django 支援 JSONField 嗎？

是的，JSONField支援 SQL Server 2016 及以後版本。 JSON 資料以 nvarchar（max） 格式儲存，並使用 SQL Server 的 JSON 函式查詢。 請參閱 JSONField 支援 以了解支援的查找與限制。

mssql-django 是否支援時區感知日期時間？

Yes. 當 USE_TZ=True時，Django 使用 SQL Server 中的 datetimeoffset 資料型別。 如果你要遷移現有資料庫，就需要修改現有的 datetime2 欄位。 請參閱 時區支援。

我可以呼叫預存程序嗎？

Yes. 使用 connection.cursor() 搭配 cursor.execute() 來呼叫預存程序。 請參見 儲存程序 ，包含多個參數與結果集的範例。

bulk_create會退回身分證嗎？

預設情況下，不會。 return_rows_bulk_insert選項預設為 False。 將它在您的資料庫 OPTIONS 中設為 True，以啟用在大量插入後傳回 ID。 此選項必須保留 False 在有觸發器的表格中。 詳見 散裝作業。

Troubleshooting

我看到「ODBC 驅動程式找不到」。 如何修正此問題？

安裝 Microsoft 的 SQL Server ODBC 驅動程式。 在 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）欄位，或從 IDENTITY（AutoField）欄位變更。 建立一個符合所需欄位類型的新模型，並手動遷移資料。 請參見 mssql-django 中的限制與未支援功能。

為什麼 bulk_update 在遇到可為 Null 的欄位時會失敗？

在 1.7 版本 mssql-django 中，後端會自動處理所有 NULL 的更新。 在早期版本中，請使用default參數 in bulk_update 以避免 NULL in CASE WHEN ... THEN NULL 表達式，因為這會導致 SQL Server 型別推論錯誤：

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

詳情請參見 「大宗作業 」。

  • Last updated on