Использование драйвера mssql-odbc (Предварительный просмотр)

mssql-python загружает один из двух нативных провайдеров ODBC:

Provider Что это такое Status
msodbcsql18 Microsoft ODBC Driver 18 for SQL Server, зарекомендовавший себя драйвер на C++ По умолчанию, без изменений
mssql-odbc Новый драйвер ODBC, написанный на Rust Предварительный просмотр, с предварительным согласием

В этой статье рассматривается mssql-odbcверсия 0.3.0, которая в настоящее время используется mssql-python, и чем она отличается от msodbcsql18.

Note

mssql-odbc находится в активной разработке и валидации. Это пока не полная замена Microsoft ODBC Driver 18. Пока что оставьте msodbcsql18 значением по умолчанию для продакшена. Команда разработчиков планирует устранить ограничения предварительной версии в предстоящих релизах, за исключением намеренных исключений, явно указанных в этой статье.

Availability

Драйвер поставляется внутри пакета mssql-python-rs в виде готовых wheel-пакетов для CPython 3.10 и более поздних версий:

Platform Architectures
Windows x64; ARM64 на CPython 3.11+
macOS universal2 (x86_64 + arm64), macOS 15 или более поздняя версия
Linux (glibc) x86_64, aarch64 — manylinux_2_28 и manylinux_2_34
Linux (musl) x86_64, aarch64 — musllinux_1_2

Включение драйвера

Пакет mssql-python зависит от mssql-python-rs, поэтому обычная установка приносит драйвер Rust:

pip install mssql-python

Если вы устанавливаете с --no-deps или из приватного индекса, явно установите также mssql-python-rs.

Выберите провайдера до первого соединения, например с помощью переменной среды:

PowerShell.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash или Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

или из Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Подключайтесь, используя существующую строка подключения вашего приложения. Оставьте включённую валидацию сертификата (Encrypt=yes;TrustServerCertificate=no). Для аутентификации и настройки сертификатов см. разделы «Строки соединения» и «Шифрование и сертификаты».

connection = mssql_python.connect(connection_string)

Драйвер применяет следующие правила при выборе поставщика:

  • Переменная среды MSSQL_PYTHON_NATIVE_PROVIDER имеет приоритет над native_provider. Конфликтующее присвоение атрибута выдает RuntimeWarning.
  • Выбор фиксируется после проверки строки подключения и непосредственно перед построением нативного соединения. Последующий сбой соединения не очищает выделение. Предыдущая ошибка разбора строки подключения или отсутствующий пакет провайдера не исправляют выбор. После того как выбор зафиксирован, изменение native_provider на другого провайдера вызывает RuntimeWarning и не имеет никакого эффекта. Перезапустите процесс, чтобы сменить провайдера.
  • Нераспознанное имя ValueErrorпровайдера вызывается; драйвер не возвращается к стандартному провайдеру. Неизвестное имя, назначенное native_provider, немедленно вызывает ошибку. Неизвестное имя в переменной среды вызывает ошибку при попытке подключения.
  • Установите native_provider в значение None, чтобы очистить выбор атрибута до того, как он станет фиксированным. Переменная окружения по-прежнему имеет приоритет.

Вызовите mssql_python.get_native_provider_info(), чтобы проверить выбранного поставщика, источник выбора и является ли выбор фиксированным. Перед подключением он сообщает о выборе, а не является доказательством того, что нативный драйвер был успешно загружен.

Чтобы вернуться назад, установите переменную в msodbcsql18, или сбросьте её и уберите любое native_provider присвоение из кода (или установите её на "msodbcsql18"). Затем запустите процесс заново.

Что работает сегодня

Драйвер mssql-python реализует каждую функцию ODBC, которую вызывает mssql-odbc, поэтому большинство приложений могут переключаться между провайдерами без изменений кода. Проверьте Известные проблемы, чтобы узнать об остальных различиях.

Area Notes
Жизненный цикл соединения Подключение, close(), with блоки, тайм-аут входа, диагностика и изменение текущей базы данных. Настройки строк соединения включают ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, и ConnectRetryCount / ConnectRetryInterval (устойчивость соединения в простое).
Authentication SQL-аутентификацию (UID / PWD); проверку подлинности Windows (Trusted_Connection=Yes, с использованием SSPI на Windows или Kerberos в Linux и macOS); а также Microsoft Entra — интерактивная аутентификация, код устройства, принципал сервиса, управляемое удостоверение, учетные данные по умолчанию и токен доступа. Интегрированные Entra и аутентификация по паролю не поддерживаются; см. Известные проблемы.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate и ServerCertificate.
Выполнение запросов Прямое и подготовленное выполнение, повторное использование подготовленного плана, параметры qmark и преобразование pyformat, выполняемое mssql-python.
Синтаксис escape-последовательностей ODBC Формы экранирования для функции, даты/времени, внешнего соединения, GUID, LIKE ... {escape ...}, интервала и {encrypt ...}.
Хранимые процедуры Вызовите их с помощью T-SQL или позиционного {call ...} синтаксиса через execute(), прочитайте наборы результатов и переходите к следующему результату с помощью nextset().
Входные параметры Скалярные параметры, SQL NULL, setinputsizes()и смешанные обычные/потоковые параметры.
Крупные параметры Крупные текстовые и двоичные параметры поступают на сервер по обычному пути связывания; Ограничения параметров XML и UDT приведены ниже.
executemany() Пакетная обработка с массивами параметров ODBC. Строки, содержащие потоковые значения, переключаются на построчное выполнение.
Выборка строк fetchone(), fetchmany(), fetchall(), итерация, fetchval(), типизированное преобразование и потоковая передача большого текста/двоичных данных.
Получение стрел arrow_batch(), arrow()и arrow_reader(). Требует использования pyarrow.
Несколько наборов результатов nextset(), включая результаты, создаваемые массивами параметров.
Транзакции Автокоммит, фиксация, откат, автоматическая фиксация (или откат, если произошла необработанная ошибка), которая происходит при завершении блока with connect(...), а также уровни изоляции read-uncommitted, read-committed, repeatable-read, serializable и snapshot.
Время ожидания запроса Установите Connection.timeout (в секундах) для ограничения операторов, выполняемых курсорами этого соединения; по истечении времени ожидания возникает OperationalError. 0 означает отсутствие тайм-аута. Эта настройка отделена от тайм-аута входа, передаваемого как connect(timeout=...).
Пулинг соединений Встроенный mssql-python пул, включая сброс соединения при получении из пула и отдельные пулы для каждого удостоверения Microsoft Entra.
API метаданных tables(), columns(), primaryKeys(), foreignKeys()statistics()rowIdColumns()rowVerColumns()procedures()и .getTypeInfo()
Кодирование и конвертеры Стандартные конвертеры широкосимвольной кодировки и вывода. Пользовательское узкосимвольное декодирование и преобразование параметров без Unicode имеют ограничения, указанные в разделе «Известные проблемы».

Типы данных

Вы можете читать все типы данных SQL Server, и драйвер поддерживает все типы параметров, которые связывает mssql-python. Драйвер возвращает значения xml, json и vector как str (vector в виде массива JSON), а также типы CLR, такие как geometry, geography и hierarchyid, как bytes. Для других сопоставлений Python см. Сопоставления типов данных. Сведения об ограничениях для конкретных типов см. в Известные проблемы.

Известные проблемы

Проверьте эти различия перед переключением рабочей нагрузки с msodbcsql18.

Issue Details Workaround
Встроенная проверка подлинности Microsoft Entra Authentication=ActiveDirectoryIntegrated не поддерживается. Проверка подлинности Windows (Trusted_Connection=Yes) не изменяется. Используйте другой метод Microsoft Entra или оставьте msodbcsql18.
Проверка подлинности паролей Microsoft Entra Authentication=ActiveDirectoryPassword не поддерживается, и поддержка не планируется, потому что этот метод не может обеспечить MFA. Аутентификация SQL (UID / PWD) не затрагивается. Используйте другой метод Microsoft Entra, например субъект-службу, управляемое удостоверение или маркер доступа.
attrs_before Параметры Аутентификацию, назначение приложения и автоматический переход при отказе для нескольких подсетей нельзя задавать как числовые атрибуты. Атрибуты оператора, кроме тайм-аута запроса, отклоняются. Используйте эквивалентные ключевые слова строки подключения.
Тайм-аут операции соединения set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) принимает и сохраняет значение, но не обеспечивает тайм-аут в версии 0.3.0. Используйте connect(timeout=...) для входа и Connection.timeout для SQL-запросов; ни один из них не является общим дедлайном операции соединения.
Многоадресные хосты msodbcsql18 по умолчанию включает Transparent Network IP Resolution (TNIR); mssql-odbc не поддерживает это. mssql-python отклоняет TransparentNetworkIPResolution ключевое слово connection-string с любым из провайдеров. Без MultiSubnetFailover=Yes, адреса пробуются по одному, поэтому недоступный адрес может задержать соединение. Серверное кэширование DNS и улучшенная маршрутизация не согласовываются. Настройте MultiSubnetFailover=Yes для прослушивателей групп доступности и других многоадресных хостов.
Временные сбои DNS Если DNS-поиск не удаётся, драйвер не переключается на последний успешный адрес. (#457) Повторите попытку подключения.
Классификация данных Метаданные по классификации чувствительности недоступны, и SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) не поддерживаются. Запрос sys.sensitivity_classifications.
Многопоточность Многопоточное использование не было проверено. Оставьте msodbcsql18 для многопоточных нагрузок.
fork() После подключения В Linux процесс, форкнувшийся после подключения родителя, может зависать при использовании драйвера, даже при новом соединении. При активном пулировании родительский процесс тоже может зависнуть. (#566) Используйте метод запуска spawn и подключайтесь внутри каждого воркера.
Отмена выполняющегося оператора Выполняющийся запрос или извлечение нельзя прервать. Например, закрытие arrow_reader() не останавливает чтение, выполняющееся в другом потоке. Используйте Connection.timeout для ограничения длительно выполняющихся операторов.
Непрочитанные результаты Закрытие курсора или запуск другой инструкции читает и отбрасывает оставшиеся результаты вместо их отмены, что может быть медленным. Закрытие курсора, использовавшего подготовленный запрос, игнорирует Connection.timeout и может зависнуть, если сервер перестанет отвечать. (#546) Получите только те записи, которые вам нужны, например, с помощью TOP.
Большие xml и параметры UDT Значения, связанные как SQL_SS_XML или SQL_SS_UDT через setinputsizes(), буферизируются в памяти, а не передаются потоково. Привязывайте значения xml как обычные строки.
Пустые image значения Пустое значение SQL Server, не равное NULL, возвращается как None вместо b"". Читайте CAST(image_column AS varbinary(max)), или используйте msodbcsql18, когда важно различие между пустым значением и NULL.
Строковые параметры, отличные от Unicode Строки, связанные как char / varchar по setinputsizes() включительно, могут быть некорректно закодированы для кодовой страницы 437, кодовой страницы 850 и UTF-8. Используйте стандартную привязку строкового типа.
Декодирование устаревших кодовых страниц на Windows С помощью setdecoding(SQL_CHAR, encoding="cp1252") или другой устаревшей кодовой страницы текст может быть некорректно декодирован или возвращён как char, потому что драйвер возвращает данные / varcharbytes как UTF-8. Используйте значение по умолчанию: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME возвращает строку подключения UID, а не пользователя базы данных. Она пуста, когда до драйвера не доходит ни один UID. Некоторые значения возможностей и лимиты, основанные на размере пакета, отличаются от msodbcsql18. Используйте SELECT USER_NAME() в качестве пользователя базы данных.
Сбои из-за нехватки памяти Некоторые сбои при выделении драйверов завершают процесс Python вместо того, чтобы возбуждать исключение MemoryError. (#484) Ограничьте размер значений, которые вы отправляете и получаете.
Производительность чтения при больших значениях В одном из бенчмарков чтение данных varchar(max) / nvarchar(max) блоками было немного медленнее, чем с msodbcsql18. (#473) Оцените производительность своей нагрузки.

Этот список не является исчерпывающим.

Извещение о проблемах

Если вы столкнулись со сбоем, выберите msodbcsql18, перезапустите процесс и проверьте, сохраняется ли это поведение. Также уберите любые конфликтующие назначения провайдера на стороне Python. Сравнение помогает выявить проблему; оно само по себе не устанавливает её причину. Включите вывод mssql_python.get_native_provider_info(), вашей платформы и SQL-запрос, приводящий к сбою, или сообщение об ошибке:

Для диагностики драйвера Rust установите эти переменные перед запуском Python и воспроизведите проблему, выбрав mssql-odbc. Например, в PowerShell выполните следующую команду:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "warn,mssqlodbc=debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"

MSSQL_TDS_TRACE Включает трассировку, MSSQL_TDS_TRACE_LEVEL выбирает фильтр журналов и MSSQL_TDS_TRACE_DIR записывает файлы по процессу вместо stderr. Перезагрузите Python после изменения этих настроек. Трассировки могут содержать SQL-текст и значения параметров. Просматривайте и скрывайте чувствительные данные перед тем, как делиться соответствующими выдержками, и отключайте отслеживание после диагностики.

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

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