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 中的時區支援。
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
1.8.0 支援 Django 6.1。 查詢編譯器在 Django 6.1 上使用的 quote_name 。 外鍵內省會回傳 ON DELETE 規則。 資料庫層級的參照動作和位元聚合不支援。
1.7.4 修正 IndexError 於 GROUP BY 將逃逸 %% 字面值與實參數混合的查詢。 原始查詢中的NotImplementedError參數已固定。IntegerChoicesGROUP BY
1.7.3 對於除 FA001. 以外的模式則是固定Authentication=ActiveDirectoryMsi的。 固定 KeyError 在子 DatabaseWrapper 職業（從 1.7.1 回歸）。
1.7.2 固定時區處理，適用於 datetimeoffset，且 Now() 。USE_TZ=True 修正 .explain() 了 Django 4.0 及以後版本的相容性。
1.7.1 Fabric 中的 SQL 資料庫（EngineEdition 12）修正。 指數下降 AlterField 修正。
1.7 預設是 ODBC 驅動程式 18。 新增 Django 6.0、Python 3.14、SQL Server 2025 支援。
1.6 支援 Django 5.1 和 5.2。 強化的 JSON 功能。
1.5 AutoField、參數格式化及結構查詢的錯誤修正。
1.4 支援 Django 5.0。 db_comment 支援。
1.3 支援 Django 4.2。
1.2 支援 Django 4.1。 時區支援。 return_rows_bulk_insert 選項。 支援 SQL Server 2022。
1.1 支援 Django 3.2 和 4.0。

Django 版本專屬註解

Django 版本 Notes
5.1 inspectdb 可以檢查帶有複合主鍵的資料表，但無法產生完整的模型定義。
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 <your-database-name>

此指令執行以下步驟：

  1. 如果伺服器還沒啟用，則啟用 CLRsp_configure 'clr enabled', 1（）。
  2. Sets clr strict security to 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 \d+$")

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

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

Note

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

相關內容

  • Last updated on