Ограничения и неподдерживаемые функции в mssql-django

В этой статье приводятся ограничения mssql-django бэкенда при использовании с SQL Server, База данных SQL Azure, Управляемый экземпляр SQL Azure и SQL Database в Microsoft Fabric.

Ограничения по функциям Django

Следующие функции Django не поддерживаются или имеют ограниченную поддержку бэкенда mssql-django :

Feature Статус Details
Avg с DurationField Не поддерживаются Агрегат Avg не работает на DurationField.
__regex и __iregex поисковые запросы Требуется настройка Поддерживается после установки ассемблера CLR на SQL Server или Управляемый экземпляр SQL Azure. База данных SQL Azure не поддерживает CLR-ассембли. См. Настроить поиск в регулярных выражениях.
DISTINCT ON Не поддерживаются SQL Server не поддерживает DISTINCT ON клаузы. Используйте .values().distinct() или отправляйте подзапросы.
Subquery в ORDER BY. Не поддерживаются Упорядочение по выражениям подзапроса может не сработать.
Уровень базы данных CASCADE Limited Некоторые SET NULL операции SET DEFAULT могут требовать ручной миграции SQL.
DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT Не поддерживаются Референтные действия на уровне базы данных, добавленные в Django 6.1. SQL Server отклоняет внешние ключевые графы с несколькими каскадными путями к одной таблице (ошибка 1785), поэтому нет нативного пути для этой функции ни в одной версии SQL Server. Использование одного из этих значений повышает проверку fields.E324системы Django . Используйте стандартный уровень on_delete Django.
BitAnd, BitOr, BitXor Не поддерживаются Побитовые агрегаты добавлены в Django 6.1. SQL Server не имеет нативной функции побитового агрегата, и бэкенд их не эмулирует, поэтому эти агрегаты повышают NotSupportedError.
is_dst в Trunc/Extract Не поддерживаются is_dst параметр (используется для разрешения неоднозначных времен во время перехода на летнее время) в Extract() и Trunc() не поддерживается. Используйте AT TIME ZONE в исходном SQL для запросов с учётом цифрового времени (DST).
Аннотация с плавающей запятой Limited Агрегаты с плавающей запятой Avg могут терять точность по сравнению с PostgreSQL из-за поведения float type SQL Server. Например, среднее значение 0.1 и 0.2 может давать 0.15000000000000000222 вместо ровно 0.15. Используйте DecimalField или Cast(avg_expr, output_field=DecimalField()) для критически важных финансовых расчетов.
Аннотация/существует в ORDER BY Не поддерживаются Использование аннотаций или выражений order_by в может не сработать.
Арифметика степени правой руки и времени времени даты Не поддерживаются Правые силовые операции (например, F('value') ** 2 работает, но 2 ** F('value') не работают) и деление с timedelta не поддерживаются.
Часовые пояса и временные дельты Limited Часовые пояса и временные дельты полностью не поддерживаются. См. Поддержка часовых поясов в mssql-django.
QuerySet.iterator() без MARS Limited Путь mssql-python не включает Multiple Active Result Sets (MARS). На пути pyodbc MARS по умолчанию активирован с драйвером Microsoft ODBC на Windows, и MARS_Connection в extra_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 не имеет аналога PostgreSQLON CONFLICT DO NOTHING.
Поиск в JSONField contains Не поддерживаются Используйте поиск по пути ключей (например, filter(metadata__color="blue")). См. ограничения JSONField.
select_for_update(of=(...)) Не поддерживаются SQL Server не поддерживает блокировку конкретных таблиц. Бэкенд повышает NotSupportedError. См. Управление транзакциями.

Ограничения миграции

Limitation Details
Альтер AutoField Нельзя изменить поле в или из AutoField (IDENTITY столбца). Требуется создание новой таблицы.
Переименование с внешними ключами Переименование столбца с ограничениями внешнего ключа может не получиться. Используйте SeparateDatabaseAndState.
AddConstraint / RemoveConstraint Конфликты Некоторые операции с ограничением могут конфликтовать. Подавайте заявки в отдельных миграциях.
Операции извлечения дат ExtractYear, ExtractMonth, и подобные операции имеют ограниченную tzinfo поддержку.

Ограничения JSONField

  • mssql-djangoКарты JSONField на Нварчар (макс). SQL Server 2025 представил нативный тип json, но драйвер Microsoft ODBC для SQL Server его не показывает.
  • contains Поиск не поддерживается. Используйте поиск по пути ключей (например, filter(metadata__color="blue")).
  • Цитируемые значения строк возвращаются с дополнительными кавычками (например, '"value"' вместо 'value').
  • Некоторые вложенные поиски могут вести себя иначе, чем в PostgreSQL.
  • Для получения дополнительной информации см. JSONField с SQL Server.

Ограничения inspectDB

  • Составные первичные ключи не генерируются так unique_together автоматически.
  • Некоторые типы столбцов, специфичные для SQL Server, могут соответствовать общим полям Django.
  • Проверяйте и корректируйте сгенерированные модели вручную.
  • Для получения дополнительной информации см. раздел Reverse-engineering models with inspectdb.

Ограничение параметров SQL Server

SQL Server ограничивает каждый запрос максимум 2 100 параметрами. Это ограничение затрагивает операции Django, которые генерируют параметризованные запросы с большими списками значений:

Операция Как он достигает предела
filter(field__in=large_list) Каждый элемент списка становится параметром. Бэкенд автоматически оптимизирует перечисление более 2048 элементов в временную таблицу.
prefetch_related() Каждый идентификатор родительского объекта становится параметром в клаузе соответствующего запроса WHERE IN . Автоматическая оптимизация, например filter(field__in=...) , когда более 2 048 ID.
bulk_create() Каждое поле каждого объекта становится параметром. Модель с 10 полями и 250 объектами генерирует 2 500 параметров.
bulk_update() Каждое поле использует два параметра на объект (один для совпадения PK, один для значения).
Q() с множеством условий Каждое значение в цепочных Q объектах становится параметром.

Назначайте batch_size массовые операции и разделяйте крупные IN запросы. См. раздел «Настройка производительности » для решений.

Ограничения по оптовым операциям

Ограничения тестовой структуры

--keepdb требуется при использовании управляемой идентификационной аутентификации (ActiveDirectoryMsi), поскольку тестовый раннер не может создавать или уничтожать базы данных с помощью этого метода аутентификации.

Для получения дополнительной информации см. Тест приложений Django с SQL Server.

Примечания по версии

Версия mssql-django Примечания
2.0 Поддерживает Python 3.10–3.14, Django 5.2, 6.0 и 6.1, SQL Server 2017, 2019, 2022 и 2025, База данных SQL Azure, Управляемый экземпляр SQL Azure и SQL Database в Microsoft Fabric. Добавляет путь драйверов 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

Версия Джанго Примечания
5,2 CompositePrimaryKey Поддержка частичная. inspectdb всё ещё требуются ручные исправления, сравнение кортежей с подзапросами требует версий Django 5.2.4 и более поздних, а некоторые пути обновления для передвижения и JSONField bulk/CASE WHEN всё ещё имеют исключения тестов. Для получения дополнительной информации смотрите репозиторий GitHub.
6.0 Требуется Python 3.12 и более поздние версии. Действуют все ограничения 5.2. Бэкенд прозрачно обрабатывает все изменения API 6.0.
6.1 Требуется Python 3.12 и более поздние версии. Действуют все ограничения 6.0. Требуется mssql-django версия 1.8.0 и более поздние. Референтные действия на уровне базы данных (DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT) и битовые агрегаты (BitAnd, BitOr, BitXor) не поддерживаются.

Настройте поиск в регулярных выражениях

mssql-django Бэкенд поддерживает Django __regex и __iregex поиски, но для этого требуется одноразовая настройка. Бэкенд поставляет CLR-ассемблер (regex_clr.dll), который предоставляет dbo.REGEXP_LIKE функцию SQL Server.

Необходимые условия

  • Экземпляр SQL Server, поддерживающий интеграцию с CLR. Локальные SQL Server и Управляемый экземпляр SQL Azure поддерживают CLR. База данных SQL Azure не поддерживает CLR-сборки, а __regex__iregex поиски недоступны в База данных SQL Azure.
  • Пользователь должен иметь sysadmin разрешение ALTER SETTINGS . Команда управления автоматически включает CLR.
  • mssql Приложение должно быть в INSTALLED_APPS.

Установка сборки CLR

Выполните команду управления, передав имя вашей базы данных:

python manage.py install_regex_clr <database>

Эта команда выполняет следующие шаги:

  1. Включает CLR на сервере (sp_configure 'clr enabled', 1), если он ещё не включён.
  2. Устанавливает clr strict security (0требуется для SAFE ассемблеров на SQL Server 2017 и более поздних версиях).
  3. Создаёт regex_clr сборку из комплектированного DLL.
  4. Создаёт dbo.REGEXP_LIKE скалярную функцию.

Caution

Настройка clr strict security позволяет 0 загружать неподписанные CLR-сборки. Это необходимо, потому что пакет regex_clr.dll не подписан. Обсудите это изменение с вашим DBA перед запуском команды на продакшн-серверах. Настройка применяется на уровне всего сервера, а не для каждой базы данных.

Используйте поиск в регулярных выражениях

После установки сборки используйте __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 один раз на каждую базу данных. Если база данных отбрасывается и воссоздаётся заново (например, во время тестирования), выполните команду снова.

Связанный контент

  • Последнее обновление: