mssql-django 常見問題

mssql-django 套件是由 Microsoft 維護、供 SQL Server 使用的 Django 資料庫後端。 它允許 Django 應用程式連接到 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 以及 Microsoft Fabric 中的 SQL 資料庫。 2.0 版及更新版本會透過 mssql-python 驅動程式（此為預設值）或 Microsoft 的 pyodbc 驅動程式連線。

用 PIP 安裝：

pip install mssql-django

mssql-django套件版本 2.0 支援 Django 5.2、6.0 和 6.1。 Django 3.2 到 5.1 的專案則維持在 1.8.0 版本。 請查看 支援生命週期 以了解完整的相容性矩陣。

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 測試。 完整相容性矩陣請參閱 支援生命週期 。

2.0 版本及後續版本支援兩個可為每個資料庫別名分別選擇的驅動程式。 pyodbc是預設，且需要外部安裝 Microsoft ODBC 驅動程式以支援 SQL Server。 若要改用 Microsoft mssql-python 的驅動程式，且不需要另外安裝 ODBC 驅動程式，請在該別名的OPTIONS字典中新增python_driver：

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

缺少該選項的別名繼續使用 pyodbc。 關於兩條路徑的行為差異，請參見 MSSQL-django 的「選擇資料庫驅動程式」。

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

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

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

在預設 pyodbc 路徑中，使用 Microsoft ODBC Driver 18 for SQL Server。 這是預設，如果沒有安裝版本 18，後端會自動回退到 ODBC Driver 17。 只有在您需要釘選特定版本時，才在 OPTIONS 字典中明確指定驅動程式，這也會關閉後援機制：

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

mssql-python 路徑會忽略 driver 選項，並使用隨 pip 一起安裝的 ODBC Driver 18。

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

在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 認證以了解所有支援的方法。

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

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

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

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

安裝 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

請參閱 安裝部分 以了解完整的平台專屬說明。

SQL Server 不支援將欄位變更為 IDENTITY（AutoField）欄位，或從 IDENTITY（AutoField）欄位變更。 建立一個符合所需欄位類型的新模型，並手動遷移資料。 請參見 mssql-django 中的限制與未支援功能。

後端會自動處理所有值皆為 NULL 的更新。 如果你需要控制佔位符值，請在 bulk_update 中使用 default 參數，讓 NULL 不會出現在 CASE WHEN ... THEN NULL 表達式中，以免導致 SQL Server 型別推論錯誤：

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

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