選擇 mssql-django 的資料庫驅動程式

從 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 支援與生命週期。

行為差異

這兩個驅動程式建立不同的連接字串，並暴露不同的連接關鍵字。 在切換別名之前，請先閱讀本節。

連線設定

逾時、重試、隔離等級、定序及 return_rows_bulk_insert 在兩種路徑中的行為都相同。

額外的連接參數

mssql-python 1.15 會根據允許清單驗證 extra_params，並拒絕清單之外的任何內容。 支援的關鍵字包括 Authentication、Encrypt、TrustServerCertificate、ServerCertificate、KeepAlive、KeepAliveInterval、IpAddressPreference、HostnameInCertificate、MultiSubnetFailover、PacketSize、ServerSPN、ApplicationIntent、ConnectRetryCount 以及 ConnectRetryInterval。

驅動程式會拒絕 DRIVER、DSN、MARS_Connection 和 SERVERNAME，以及 pyodbc 專用關鍵字，例如 APP、Description、Current Language、Network Library、ColumnEncryption、AnsiNPW、Connect Timeout、WSID、QuotedId、Regional、UseFMTONLY 和 LongAsMax。 在切換別名前先移除這些關鍵字，並用該 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 它仍然是預設，並且完全支援。 當你真的要移轉時，一次只切換一個別名，並先對其執行測試套件，再移轉其餘別名。

相關內容

• mssql-django 的連線選項
• MSSQL-Django 配置參考
• mssql-django 中的連線池
• 使用 mssql-django 的 Microsoft Entra 驗證
• SQL Server 的 mssql-python 驅動程式