mssql-django 的限制與未支援功能

本文列出在 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 以及 Microsoft Fabric 中 SQL 資料庫中使用後端時的mssql-django限制。

Django 功能的限制

以下 Django 功能不支援或支援有限 mssql-django ：

Feature 狀態 詳細資訊
Avg 和 DurationField 不支援 聚合 Avg 在 上不適用 DurationField。
__regex 以及 __iregex 查詢 需要設定 在 SQL Server 或 Azure SQL 受控執行個體 安裝 CLR 組合後才會獲得支援。 Azure SQL Database 不支援 CLR 組合。 請參見 設定正則表達式查詢。
DISTINCT ON 不支援 SQL Server 不支援DISTINCT ON子句。 使用 .values().distinct() 或子查詢。
Subquery 在 ORDER BY 不支援 以子查詢表達式排序可能無法運作。
資料庫層級 CASCADE 受限 有些 SET NULL 操作 SET DEFAULT 需要手動遷移 SQL。
DB_CASCADE、DB_SET_NULL、DB_SET_DEFAULT 不支援 Django 6.1 新增的資料庫層級參照動作。 SQL Server 會拒絕同一表格中多條串聯路徑的外鍵圖（錯誤 1785），因此在任何 SQL Server 版本中都沒有原生路徑可達此功能。 使用其中一個值會提升 Django 系統檢查 fields.E324。 還是用標準的Django等級 on_delete 吧。
BitAnd、BitOr、BitXor 不支援 Django 6.1 新增了位元彙總。 SQL Server 沒有原生的位元彙總函數，後端也不會模擬它們，因此這些聚合會產生 NotSupportedError。
is_dst 在 Trunc/Extract 不支援 is_dst 參數（用於解決夏令時間過渡期間模糊時間）在 和 Extract()Trunc() 中不被支援。 在原始 SQL 中用於 AT TIME ZONE DST 感知查詢。
浮點註解 受限 浮點Avg聚合器相較於 PostgreSQL 可能會因 SQL Server 的浮點型態行為而失去精確度。 例如，平均 0.1 和 0.2 可能得到 0.1500000000000000222，而不是恰好 0.15。 用於 DecimalField 或 Cast(avg_expr, output_field=DecimalField()) 用於關鍵財務計算。
註解/存在於 ORDER BY 不支援 在 中 order_by 使用 annotate 或 exists（存在式）表達式可能無法行。
右手冪與日期時間算術 不支援 右手冪運算（例如， F('value') ** 2 work但 2 ** F('value') 失敗）和除 timedelta 法則不支援。
時區與時差 受限 時區和時差並不完全支援。 請參閱 mssql-django 中的時區支援。
QuerySet.iterator() 沒有火星 受限 mssql-python 路徑不會啟用多重主動結果集（MARS）。 在 pyodbc 路徑上，MARS 預設啟用時使用 Windows 的 Microsoft ODBC 驅動程式，且MARS_Connectionextra_params會不分大小寫地執行。 當 MARS 關閉時，先 QuerySet.iterator() 將整個結果緩衝在記憶體中，然後再讓出。 chunk_size 但這不會改變這種行為。
NthValue 視窗函數 不支援 SQL Server 不支援 NTH_VALUE()。 使用 FIRST_VALUE、或 LAST_VALUE子查詢。
ignore_conflicts 在 bulk_create 不支援 不支援 bulk_create(objs, ignore_conflicts=True)。 SQL Server 沒有 PostgreSQL ON CONFLICT DO NOTHING的對應功能。
JSONField contains lookup 不支援 改用金鑰路徑查找（例如， filter(metadata__color="blue")）。 請參閱 JSONField 限制。
select_for_update(of=(...)) 不支援 SQL Server 不支援鎖定特定資料表。 後端會升 NotSupportedError。 請參見交易管理。

移轉限制

限度 詳細資訊
祭壇 AutoField 無法將欄位改成或從（AutoField欄位）轉。IDENTITY 需要建立一個新的表格。
外鍵重命名 重新命名具有外鍵約束的欄位可能會失敗。 請使用 SeparateDatabaseAndState。
AddConstraint / RemoveConstraint 衝突 部分約束操作可能會相互衝突。 分開申請。
日期擷取操作 ExtractYear、、 ExtractMonth及類似操作支援有限 tzinfo 。

JSONField 限制

  • mssql-django地圖是JSONField的。 SQL Server 2025 引入了原生 json 型別，但 Microsoft ODBC 驅動程式 for SQL Server 並未公開此類型。
  • contains查詢功能不被支援。 改用金鑰路徑查找（例如， filter(metadata__color="blue")）。
  • 引號字串值會帶著額外的引號回傳（例如， '"value"' 取代 'value'）。
  • 有些巢狀查詢的行為可能和 PostgreSQL 不同。
  • 欲了解更多資訊，請參閱 SQL Server 的 JSONField。

InspectDB 的限制

  • 複合主鍵不會自動 unique_together 產生。
  • 某些 SQL Server 專屬的欄位類型可能會對應到通用的 Django 欄位。
  • 手動檢視並調整已產生的模型。
  • 欲了解更多資訊，請參閱 使用 inspectdb 的逆向工程模型。

SQL Server 參數限制

SQL Server 限制每個查詢最多 2,100 個參數。 此限制影響產生具大型值列表參數化查詢的 Django 操作：

運算 如何達到極限
filter(field__in=large_list) 每個清單項目都成為一個參數。 後端會自動優化超過 2,048 個項目到暫存表中。
prefetch_related() 每個父物件 ID 都會成為相關查詢 WHERE IN 子句中的一個參數。 自動優化，就像 filter(field__in=...) 超過 2,048 個 ID 時一樣。
bulk_create() 每個物件的每個場都成為一個參數。 一個包含 10 個欄位和 250 個物件的模型會產生 2,500 個參數。
bulk_update() 每個欄位為每個物件使用兩個參數（一個用於 PK 匹配，一個用於數值）。
Q() 但有許多條件 鏈狀 Q 物件中的每個值都成為一個參數。

設定 batch_size 為批量操作和區塊大 IN 查詢。 請參見 效能調校 以獲取解決方案。

散裝作業的限制

  • bulk_create 但 return_rows_bulk_insert=False 不會回傳身分證。 有觸發器的表格必須使用。 請參考 mssql-django 的 Bulk 操作。

測試框架限制

--keepdb 在使用管理身份驗證ActiveDirectoryMsi（）時是必須的，因為測試執行者無法用該認證方法建立或銷毀資料庫。

欲了解更多資訊，請參閱使用 SQL Server 測試 Django 應用程式。

版本專屬註解

MSSQL-django 版本 Notes
2.0 支援 Python 3.10 至 3.14、Django 5.2、6.0 和 6.1，SQL Server 2017、2019、2022 和 2025，Azure SQL Database、Azure SQL 受控執行個體，以及 Microsoft Fabric 中的 SQL 資料庫。 新增 mssql-python 驅動路徑，同時保留 pyodbc 作為預設。 欲了解更多資訊，請參閱 MSSQL-django 的選擇資料庫驅動程式。
1.8.0 這個版本適合需要 Python 3.8、Python 3.9 或 Django 5.2 之前版本的專案。

測試過的 mssql-django 2.0 組合包括 Django 5.2（搭配 Python 3.10 至 3.13），以及 Django 6.0 或 6.1（搭配 Python 3.12 到 3.14）。 如果後端連接到未被識別的較新 SQL Server 主要版本，它會使用已知的最新能力集，而不是失敗版本驗證。 這種行為並不會宣告支援未經測試的功能。

Django 版本專屬註解

Django 版本 Notes
5.2 CompositePrimaryKey 支援程度有限。 inspectdb 仍然需要手動修正，元組與子查詢的比較需要 Django 5.2.4 及更新版本，還有一些遷移以及 JSONField bulk/CASE WHEN 更新路徑仍有測試排除。 欲了解更多資訊，請參閱 GitHub 倉庫。
6.0 需要 Python 3.12 及更新版本。 所有 5.2 的限制都適用。 後端會透明處理所有 6.0 API 變更。
6.1 需要 Python 3.12 及更新版本。 所有 6.0 限制皆適用。 需要 mssql-django 1.8.0 及更新版本。 資料庫層級的參照動作（DB_CASCADE， ， ） DB_SET_DEFAULT與位元彙總（BitOrBitAnd， ， BitXor） DB_SET_NULL不被支援。

設定正則式查詢

mssql-django後端支援 Django __regex 和__iregex查詢，但需要一次性設定。 後端附帶一個 CLR 組合regex_clr.dll（），提供 dbo.REGEXP_LIKE SQL Server 函式。

先決條件

  • 一個支援 CLR 整合的 SQL Server 實例。 本地 SQL Server 與 Azure SQL 受控執行個體 支援 CLR。 Azure SQL Database 不支援 CLR assemblies，所以 __regex__iregex Azure SQL Database 無法提供查詢功能。
  • 連接使用者必須擁有 sysadmin or ALTER SETTINGS 權限。 管理指令會自動啟用 CLR。
  • mssql應用程式必須在 INSTALLED_APPS.

安裝 CLR 組件

執行管理指令，傳遞你的資料庫名稱：

python manage.py install_regex_clr <database>

此指令執行以下步驟：

  1. 如果伺服器還沒啟用，則啟用 CLRsp_configure 'clr enabled', 1（）。
  2. Setclr strict security為0（SQL Server 2017及更新版本的組合語言必須SAFE使用）。
  3. 從捆綁的 DLL 建立 regex_clr 組裝檔。
  4. 創造 dbo.REGEXP_LIKE 純量函數。

謹慎

設定 clr strict security 為 0 允許未簽署的 CLR 組件載入。 這是必須的，因為捆 regex_clr.dll 綁包沒有簽名。 在執行該指令前，請先與你的資料庫管理員討論這個變更。 這個設定適用於整個伺服器，而不是針對每個資料庫。

使用正則表達式查詢

安裝組件後，請在查詢集中使用 __regex 和 __iregex ：

# Case-sensitive regex
products = Product.objects.filter(name__regex=r"^Widget\s\d+$")

# Case-insensitive regex
products = Product.objects.filter(name__iregex=r"^widget\s\d+$")

後端會將這些查詢轉換成 dbo.REGEXP_LIKE(column, pattern, case_flag) = 1。

Important

dbo.REGEXP_LIKE 忽略圖案中的字面空白。 像這樣的模式會 ^Widget \d+$ 匹配，就像它是 ^Widget\d+$一樣，因此它不會回傳任何對值 Widget 42的列數。 將空格寫成 \s 或寫成字元類別，例如 [ ]。 什麼都沒升起，所以空的結果看起來像是資料問題。

Note

你必須在每個資料庫執行一次指令 install_regex_clr 。 如果資料庫被丟棄並重新建立（例如測試期間），請再次執行該指令。

相關內容

  • Last updated on