Новые возможности mssql-django

В этой статье описываются новые функции, улучшения и изменения в каждой версии серверной mssql-django части базы данных Django.

Версия 2.0

Дата выхода: сентябрь 2026

Версия 2.0 добавляет драйвер Microsoft mssql-python в качестве альтернативы pyodbc для отдельных баз данных, обновляет матрицу поддерживаемых версий Python, Django и SQL Server, а также включает исправления, связанные с совместимостью и надёжностью. pyodbc остаётся драйвером по умолчанию.

Обзор матча

  • Поддержка драйвера mssql-python: Псевдоним базы данных подключается с помощью "python_driver": "mssql_python" в своём словаре OPTIONS. Драйвер поддерживает соединения, пул соединений, повторные попытки, транзакции и точки сохранения, значения datetimeoffset, интроспекцию и аутентификацию Microsoft Entra. Алиасы, в которых эта опция отсутствует, продолжают использовать pyodbc, так что ничего не меняется, пока вы не подпишетесь на неё. Для получения дополнительной информации см. Выберите драйвер базы данных для mssql-django.
  • Отдельной установки драйвера ODBC на пути mssql-python нет: псевдоним на mssql-python не требует внешне установленного драйвера Microsoft ODBC для SQL Server. Псевдонимы, которые остаются на pyodbc, по-прежнему остаются.
  • Модернизированная матрица поддержки: Python 3.10–3.14, Django 5.2–6.1 и SQL Server 2017–2025. Django 6.0 и более поздние версии требуют Python 3.12 или новее.

Исправленные ошибки

  • Явно заданные параметры MARS учитываются: явно заданное значение MARS_Connection в extra_params сохраняется вместо замены значением Windows по умолчанию, а сравнение выполняется без учета регистра. Параметр MARS_Connection=no теперь работает с конечными точками, не поддерживающими MARS, включая Microsoft Fabric Warehouse. При отключённом MARS ORM буферизует результаты итерации перед их возвратом, чтобы вложенный запрос мог повторно использовать соединение, однако на больших наборах результатов это требует больше памяти. Это исправление соединения не добавляет полной поддержки Warehouse для миграций или других функций SQL Server.
  • Символы-шаблоны в квадратных скобках экранируются при поиске по выражениям: при поиске по шаблону, где два поля сравниваются с помощью выражения F(), например contains и startswith, экранируется символ-шаблон SQL Server [. Символы в квадратных скобках обрабатываются как данные, а не как синтаксис подстановочных знаков.
  • В именах схем inspectdb экранируются кавычки: одинарная кавычка в значении inspectdb --schema экранируется в запросе к метаданным, поэтому имена схем, содержащие кавычку, больше не приводят к формированию некорректного Transact-SQL (T-SQL).
  • Пустой HOST подключается к localhost при использовании mssql-python: Пропущенный HOST, который Django подставляет как пустую строку, преобразуется в localhost вместо того, чтобы не пройти валидацию при пустом значении SERVER=. Это поведение соответствует pyodbc значению по умолчанию для локальных экземпляров.

Improvements

  • pytz заменён на zoneinfo и tzdata: для обработки часовых поясов используется модуль стандартной библиотеки zoneinfo, а пакет tzdata предоставляет базу данных часовых поясов IANA в средах, где она не поставляется, например в Windows и минимальных образах контейнеров. Смещения остаются правильными в течение года для зон с отрицательным смещением летнего времени. pytz больше не является зависимостью.
  • Принимаются более новые версии SQL Server: основная версия SQL Server, которую бэкенд не распознаёт, использует последние возможности возможностей, о которых знает бэкенд, вместо того чтобы провалить проверку версии. Вы можете подключиться к новому релизу SQL Server до выхода соответствующего mssql-django релиза. Принятие соединения не объявляет непротестированные функции как поддерживаемые.

Кардинальные изменения

  • Python 3.8 и 3.9, а также Django 3.2–5.1 больше не поддерживаются. Код совместимости для ранних версий остаётся в силе, но эти комбинации не тестируются и не перечисляются.
  • mssql-python Версия 1.15.0 или более позднее является обязательной зависимостью, даже если псевдоним использует pyodbc. Установка ограничена платформами с совместимым mssql-python дистрибутивом, что исключает SUSE Linux на ARM64. Проекты на других платформах остаются на версии 1.8.0.
  • Заявленная поддержка SQL Server начинается с SQL Server 2017, а заявленная поддержка нативного подключения ограничена Microsoft ODBC Driver 17 и Microsoft ODBC Driver 18.

Версия 1.8.0

Дата выхода: август 2026

Версия 1.8.0 добавляет поддержку Django 6.1, продолжая поддерживать Django 3.2–6.0. Перенос проекта с Django 6.0 на 6.1 не требует изменений кода, если только вы не используете одну из двух функций Django 6.1, описанных в этом разделе.

Обзор матча

  • Поддержка Django 6.1: проверено на совместимость с Django 6.1 при сохранении поддержки Django с 3.2 по 6.0. Ограничение зависимостей расширяется от django>=3.2,<6.1 до django>=3.2,<6.2.
  • Компилятор запросов использует quote_name в Django 6.1: в Django 6.1 quote_name_unless_alias объявлен устаревшим. Бэкенд теперь вызывает SQLCompiler.quote_name в Django 6.1 и более поздних версиях; это зависит от версии, поэтому более ранние версии Django остаются без изменений. Запросы со срезом и смещением, такие как qs[a:b] и OFFSET ... FETCH, компилируются без предупреждений об устаревании.
  • При интроспекции внешнего ключа теперь возвращается правило ON DELETE: в Django 6.1 объект get_relations() был расширен и теперь включает правило ON DELETE на уровне базы данных. Бэкенд возвращает ожидаемую трёхчастную структуру и соответствующим образом сопоставляет внешние ключи SQL Server NO ACTION, поэтому inspectdb и интроспекция внешних ключей создают корректные модели.

Функции Django 6.1, которые не поддерживаются

Два дополнения к Django 6.1 недоступны на этом бэкенде по разным причинам:

  • Референтные действия на уровне базы данных (DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT): SQL Server отклоняет внешние графы ключей с несколькими каскадными путями к одной таблице (ошибка 1785), поэтому нет нативного пути для этой функции ни в одной версии SQL Server. Использование одного из этих значений повышает проверку fields.E324системы Django , которая указывает на стандартный уровень on_deleteDjango.
  • Битовые агрегаты (BitAnd, BitOr, BitXor): SQL Server не имеет нативной функции побитового агрегата, и бэкенд не эмулирует их, поэтому эти агрегаты повышают NotSupportedError.

Дополнительные сведения см. в разделе "Ограничения" и неподдерживаемые функции в mssql-django.

Версия 1.7.4

Дата выхода: июль 2026

Версия 1.7.4 — это обратно совместимый патч с двумя исправлениями для обработки необработанных и аннотированных GROUP BY запросов.

Исправленные ошибки

  • IndexError в запросах GROUP BY с экранированными %% и реальными параметрами: Ранее любой запрос с условием GROUP BY проходил этап переписывания заполнителей, на котором выполнялся поиск %\w+ и его замена на {}. Этот regex также совпадал с уходящими %% литералами, которые добавляли фантомные заполнятели и появлялись IndexError: Replacement index N out of range всякий раз, когда запрос комбинировал %%-escape с реальным %s параметром. Суженное регулярное выражение теперь затрагивает только %% (сохранённый без изменений) и %s (реальный плейсхолдер), и это единственный шаблон, который компилятор вообще когда-либо генерирует. То же исправление также предотвращает несвязанную тихую ошибку, из-за которой неэкранированный шаблон, такой как LIKE '%abc%', в запросе без параметров перезаписывался как LIKE '{}%' и возвращал неверные строки.
  • NotImplementedError для IntegerChoices в необработанных GROUP BY запросах: Ранее передача значения IntegerChoices в необработанный запрос, содержащий предложение GROUP BY, вызывала NotImplementedError: Not supported type <enum ...>. Вспомогательный код для типизации параметров использовал точные проверки типов (typ == int), и type(IntegerChoices_value) — это класс перечисления, а не int, поэтому управление дошло до raise, хотя значение является подклассом int. Проверки типов теперь используют isinstance, а bool ветвь оценивается перед ветвью int (поскольку bool сама int является подклассом). Варианты перечисления теперь привязываются правильно, bool по-прежнему привязывается к BIT, а обычный int не изменился.

Версия 1.7.3

Дата выпуска: июнь 2026 г.

Версия 1.7.3 — это выпуск исправлений с обратной совместимостью с двумя исправлениями подключения и среды выполнения.

Исправленные ошибки

  • FA001: Ранее серверная часть пропускала Authentication= только для ActiveDirectoryMsi. Другие режимы Entra, которые не предоставляют значение USER (например, ActiveDirectoryIntegrated, ActiveDirectoryDefault, ActiveDirectoryDeviceFlow), всё равно получали Trusted_Connection=yes, которое драйвер ODBC отклонял с ошибкой FA001 (Cannot use Authentication option with Integrated Security option). Исправление обнаруживает любое явно заданное значение Authentication= с учетом границ и без учета регистра, а также пропускает и Trusted_Connection, и Integrated Security=SSPI. Обработка паролей не изменилась: SqlPassword, ActiveDirectoryPassword и ActiveDirectoryServicePrincipal по-прежнему отправляют PWD, в то время как ActiveDirectoryInteractive по-прежнему его не передаёт.
  • KeyError для подклассов DatabaseWrapper: кэшируемые свойства sql_server_version и to_azure_sql_db зависели от интроспекции type(self).__dict__ объекта cached_property, из-за чего при первом обращении подкласса KeyError к ним возникало DatabaseWrapper (регрессия, внесённая в версии 1.7.1). Исправление использует явные словари класса (_known_versions, _known_azures), доступ к которым осуществляется через self., поэтому поиск разрешается по MRO, и обёртки подклассов работают корректно.

Версия 1.7.2

Дата выпуска: май 2026 г.

Версия 1.7.2 — это патч-релиз, сохраняющий обратную совместимость и содержащий исправления, связанные с часовыми поясами и совместимостью.

Исправленные ошибки

  • .explain() Совместимость с Django 4.0 и более поздними версиями: исправлена обработка компилятором метаданных explain в Django, поэтому .explain() больше не приводит к сбою с AttributeError в Django 4.0 и более поздних версиях. Серверная часть теперь использует соответствующие версии поля explain и при необходимости корректно генерирует NotSupportedError.
  • Обработка часового пояса datetimeoffset: исправлен разбор datetimeoffset, поэтому смещения часового пояса сохраняются, а не отбрасываются. Возвращаемые значения даты и времени теперь содержат информацию о часовом поясе там, где это ожидается.
  • Now() with USE_TZ=True: обновлена генерация SQL для Now(): теперь при включенной поддержке часовых поясов используется поведение с учётом часового пояса, что предотвращает смещение меток времени на хостах SQL Server, не использующих UTC.

Версия 1.7.1

Дата выпуска: апрель 2026 г.

Версия 1.7.1 — это обратно совместимый патч-релиз с исправлениями ошибок.

Исправленные ошибки

  • FieldDoesNotExist при изменении полей при убывающем порядке индексов: Исправлено _alter_field() в schema.py: теперь используется index.fields_orders вместо index.fields при определении имён полей индекса. Предыдущий код передавал необработанные строки полей с сортировкой (например, "-pub_date") в model._meta.get_field(), что вызывало FieldDoesNotExist. Теперь извлекается только имя поля, а суффикс сортировки корректно отбрасывается.
  • Поддержка базы данных SQL в Microsoft Fabric (EngineEdition 12): база данных SQL в Fabric распознается как редакция Azure (EngineEdition=12). Ранее редакция движка Fabric не распознавалась, из-за чего to_azure_sql_db возвращал False, а проверки флагов функций завершались сбоем. Исправление добавляет EDITION_AZURE_SQL_FABRIC=12 в _AZURE_EDITIONS и сопоставляет Fabric с последней поддерживаемой версией SQL Server. JSONField, хэш-функции, анализ параметров сортировки и очистка тестовой базы данных теперь работают правильно в Fabric.

Версия 1.7

Дата выпуска: март 2026 г.

Обзор матча

  • Поддержка Django 6.0: полная совместимость с Django 6.0, которая требует Python 3.12 или более поздней версии. Все изменения API 6.0 обрабатываются прозрачно серверной частью.
  • Частичная CompositePrimaryKey поддержка: Серверная часть добавляет частичную поддержку Django 5.2 CompositePrimaryKey. Для сравнения кортежей с подзапросами требуется Django версии 5.2.4 или новее, при этом некоторые крайние случаи со составными ключами и JSONField остаются. Django 5.2 впервые поддерживается в mssql-django 1.6.
  • поддержка SQL Server 2025: проверена на SQL Server 2025.
  • Драйвер ODBC 18 по умолчанию: серверная часть по умолчанию использует драйвер ODBC 18 для SQL Server, при этом автоматический возврат к ODBC Driver 17, если версия 18 не установлена.

Заметки для конкретной версии

Версия Django Примечания
Django 5.1 inspectdb может проверять таблицы с составными первичными ключами, но для них не создаются полные определения моделей.
Django 5.2 CompositePrimaryKey поддержка является частичной. Для сравнения кортежей с вложенными запросами требуется Django 5.2.4 или более поздней версии, а некоторые варианты миграции и JSONField пограничные варианты остаются.
Django 6.0 Требуется Python 3.12 или более поздней версии. Применяются все ограничения 5.2.

Версия 1.6

Дата выпуска: август 2025 г.

  • Добавлена поддержка Django 5.1 и 5.2.
  • Расширенная функциональность JSON и обратная совместимость.
  • Улучшенная инфраструктура конвейера.

Версия 1.5

Дата выпуска: апрель 2024 г.

  • Добавлен supports_comments флаг функции для db_comments.
  • Исправлены ошибки, связанные с AutoField, форматированием параметров и запросами к схеме.

Версия 1.4

Дата выпуска: январь 2024 г.

  • Добавлена поддержка Django 5.0.
  • Добавлена поддержка db_comment.
  • Исправления ошибок в преобразованиях даты/времени и пустых агрегатах.

Версия 1.3

Дата выпуска: май 2023 г.

  • Добавлена поддержка Django 4.2.
  • Добавлена поддержка Replace чувствительных к регистру функций.
  • Исправления ошибок для OFFSET обработки и левого заполнения.

Версия 1.2

Дата выпуска: декабрь 2022 г.

  • Добавлена поддержка Django 4.1.
  • Добавлена поддержка часовых поясов (datetimeoffset с USE_TZ=True).
  • Добавлен параметр return_rows_bulk_insert для получения идентификаторов при массовой вставке.
  • Добавлена поддержка SQL Server 2022.
  • Добавлена JSONField поддержка Управляемый экземпляр SQL Azure.

Версия 1.1

Дата выпуска: июль 2022 г.

  • Поддержка Django 3.2 и 4.0.
  • Поддерживаются SQL Server 2016 и более поздние версии, а также База данных SQL Azure.
  • Подключение на основе pyodbc.

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

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