Выберите драйвер базы данных для mssql-django

Начиная с версии 2.0, mssql-django подключается через один из двух драйверов базы данных Python:

  • pyodbc с установленным внешним драйвером Microsoft ODBC для SQL Server. Этот драйвер — по умолчанию.
  • mssql-python — драйвер Python от Microsoft, который не требует отдельно установленного драйвера 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, включая OpenSSL на macOS и необходимые библиотеки на Linux.

Поскольку mssql-python это обязательная зависимость, mssql-django версия 2.0 устанавливается только на платформах с совместимым mssql-python дистрибутивом. Для списка платформ см. поддержку и жизненный цикл mssql-django.

Отличия в поведении

Два драйвера создают разные строки соединения и открывают разные ключевые слова соединения. Ознакомьтесь с этим разделом, прежде чем менять псевдоним.

Параметры подключения

Setting pyodbc mssql-python
HOST и PORT. Выводится как SERVER, SERVER или PORT плюс host_is_server, в зависимости от драйвера и SERVERNAME. Всегда выводится как SERVER=<host>,<port>. Пустое HOST становится localhost.
driver Выбирает драйвер ODBC. По умолчанию установлен Microsoft ODBC Driver 18 для SQL Server, с автоматическим переходом к Driver 17. Проигнорировано. Резервный вариант для Driver 17 не предусмотрен.
dsn Supported. Проигнорировано.
host_is_server Поддержка FreeTDS. Проигнорировано.
unicode_results Supported. Проигнорировано.
TOKEN Supported. Supported. Укажите TOKEN без USER, PASSWORD или Authentication ключевого слова. Ваше приложение приобретает и обновляет токен.
DATABASE_CONNECTION_POOLING Применимо. Применимо.

Тайм-ауты, повторные попытки, уровень изоляции, правила сортировки и return_rows_bulk_insert работают одинаково в обоих вариантах.

Дополнительные параметры соединения

mssql-python 1.15 валидирует extra_params по списку разрешений и отклоняет всё, что вне его. Поддерживаемые ключевые слова включают Authentication, Encrypt, TrustServerCertificate, HostnameInCertificate, ServerCertificate, MultiSubnetFailover, IpAddressPreference, ServerSPN, ConnectRetryCount, PacketSize, ApplicationIntent, ConnectRetryInterval, KeepAlive и KeepAliveInterval.

Драйвер отвергает MARS_Connection, APP, LongAsMax и QuotedId, а также ключевые слова, используемые только в pyodbc, такие как WSID, AnsiNPW, ColumnEncryption, Regional, UseFMTONLY, Connect Timeout, Description, Network Library, Current Language, SERVERNAME, DSN и DRIVER. Удалите эти ключевые слова перед переключением псевдоним и используйте connection_timeout опцию вместо Connect Timeout.

Когда extra_params задаётся ключевое слово, которое также генерирует бэкенд, побеждает явное значение.

Несколько активных результирующих наборов данных

В пути pyodbc бэкенд добавляет MARS_Connection=yes, когда для псевдонима используется драйвер Microsoft ODBC в Windows. Вместо этого учитывается явное значение MARS_Connection в extra_params, а совпадение игнорирует регистр.

Путь 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 из образов контейнеров и развертывания сервисов приложений.

Используйте pyodbc, если ваше развертывание зависит от именованного DSN, FreeTDS, Always Encrypted с использованием ключевого слова ColumnEncryption, версии драйвера ODBC, которой вы управляете самостоятельно, или MARS. Для того, что требует MARS на каждом пути, см. раздел Multiple Active Result Sets.

Существующие проекты могут оставаться на pyodbc. Она остаётся стандартной и полностью поддерживается. Когда всё же будете выполнять перенос, переключайте по одному алиасу за раз и прогоняйте на нём свой набор тестов, прежде чем переносить остальные.

Связанные материалы

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