Используйте драйвер mssql-odbc (Preview)

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

Provider Description Status
msodbcsql18 Microsoft драйвер ODBC 18 для SQL Server Default
mssql-odbc Драйвер ODBC на основе Rust Предварительный просмотр, согласие

mssql-python-rs Пакет 0.4.0 включает провайдер mssql-odbc.

Note

Используйте msodbcsql18 для производственных нагрузок. Прежде чем включить предварительную версию поставщика mssql-odbc, ознакомьтесь с известными проблемами.

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, который содержит mssql-odbc драйвер:

python -m pip install mssql-python

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

Выберите провайдера перед открытием первого соединения. Используйте один из следующих методов.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

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

Запустите этот пример с выбранным вами поставщиком:

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

Пример выводит 1.

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

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

Ошибки проверки строк соединения и отсутствующие пакеты провайдеров происходят до этого момента. Вы можете исправить эти ошибки и выбрать другого провайдера без перезапуска.

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

Чтобы вернуться в msodbcsql18, удалите MSSQL_PYTHON_NATIVE_PROVIDER и любое назначение native_provider из приложения, затем перезапустите Python.

Аварийное переключение для нескольких подсетей по умолчанию

Поставщик Rust по умолчанию включает MultiSubnetFailover для соответствующих соединений Transmission Control Protocol (TCP). Установите MultiSubnetFailover=no явно, чтобы запросить последовательные попытки подключения. Чтобы изменить значение по умолчанию для всего развертывания, установите MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT на true или false до первого использования родного драйвера. Ключевое слово connection-string переопределяет это по умолчанию.

Числовой SQL_COPT_SS_MULTISUBNET_FAILOVER атрибут (1248) также переопределяет ключевое слово, если он задан до подключения.

Драйвер не использует этот параметр по умолчанию для не-TCP-транспортов, зеркалирования базы данных, именованных экземпляров, требующих обнаружения браузера SQL Server, или локальных соединений Windows, в которых нет явного протокола и адреса. Явное включение MultiSubnetFailover для транспорта не TCP, зеркалирования базы данных или обнаружения SQL Server Browser вызывает ошибку соединения. Для получения дополнительной информации см. раздел «Высокая доступность и аварийное переключение».

Поддерживаемые функции

Поддерживаются следующие функции с учётом известных проблем.

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

Интегрированная аутентификация Microsoft Entra ID использует учетную запись Windows, в которую выполнен вход, в Windows. В Linux и macOS используется билет Kerberos для аутентификации на конечной точке службы федерации Active Directory (AD FS) (AD FS) клиента. Сведения о предварительных требованиях см. в Windows Integrated authentication.

Закрытие arrow_reader() отправляет SQLCancel, чтобы прервать текущую операцию получения. Этот вызов ждёт окончания очистки после отмены. Для получения дополнительной информации см. раздел интеграция Apache Arrow.

Типы данных

Драйвер возвращает значения xml, json и vector как объекты Pythonstr, при этом vector представлен как массив JavaScript Object Notation (JSON). Он возвращает типичные типы общеязыковой среды выполнения (CLR), такие как geometry, geography и hierarchyid, в виде объектов Pythonbytes. Для получения дополнительной информации см. Отображения типов данных и Известные проблемы.

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

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

Issue Details Workaround
Аутентификация пароля Microsoft Entra ID Authentication=ActiveDirectoryPassword не поддерживается. Этот метод не поддерживает многофакторную аутентификацию (MFA). Аутентификация SQL (UID / PWD) не затрагивается. Используйте другой метод Microsoft Entra ID, например субъект-службу, управляемое удостоверение или маркер доступа.
attrs_before Параметры Режим аутентификации Microsoft Entra ID и намерение приложения нельзя задавать как числовые атрибуты соединения. Используйте ключевые слова строки подключения Authentication и ApplicationIntent.
Тайм-аут операции соединения SQL_ATTR_CONNECTION_TIMEOUT управляет очисткой при отмене. Он не применяет тайм-аут при сбросе подключения из пула. Запрос на соединение может оставаться заблокированным, если сервер перестаёт отвечать во время сброса. Тайм-аут сброса пула недоступен. Настройте connect(timeout=...) для входа и Connection.timeout для выписок.
Многоадресные хосты msodbcsql18 по умолчанию включает Transparent Network IP Resolution (TNIR); mssql-odbc не поддерживает это. mssql-python отклоняет TransparentNetworkIPResolution ключевое слово connection-string с любым из провайдеров. Используйте MultiSubnetFailover=yes для прослушивателей групп доступности и других многоадресных хостов. Значения по умолчанию см. в разделе Значения по умолчанию для переключения при отказе в многоподсетевой конфигурации.
Классификация данных Метаданные по классификации чувствительности недоступны, и SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) не поддерживаются. Запрос sys.sensitivity_classifications.
fork() После подключения В Linux процесс, форкнувшийся после подключения родителя, может зависать при использовании драйвера, даже при новом соединении. При активном пулировании родительский процесс тоже может зависнуть. (#566) Используйте метод запуска spawn и подключайтесь внутри каждого воркера.
Нативное трассирование в Linux При включённой нативной трассировке Python может аварийно завершиться во время очистки драйвера при выходе из процесса. Оставьте MSSQL_TDS_TRACE неустановленным на Linux.
Непрочитанные результаты Закрытие курсора или запуск другой инструкции читает и отбрасывает оставшиеся результаты вместо их отмены, что может быть медленным. Очистка подготовленного оператора использует тайм-аут запроса оператора, но нулевой тайм-аут оставляет эту очистку неограниченной. Получите только нужные строки, например с TOP, и установите Connection.timeout перед созданием курсора.
Пользовательское декодирование узких символов Собственный драйвер использует кодовую страницу ANSI в Windows и кодовую страницу локали процесса в Linux и macOS для однобайтового текста. Явное декодирование Python, не совпадающее с этой кодовой страницей, может привести к неправильному тексту или bytes. Используйте стандартное широкосимволное декодирование: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Некоторые значения возможностей и лимиты, основанные на размере пакета, отличаются от msodbcsql18. SQL_USER_NAME сообщает о субъекте-пользователе базы данных, а не о строке подключения UID. Запрашивайте конкретные метаданные сервера, когда заявленная возможность или лимит имеют значение для вашего приложения.
Сбои из-за нехватки памяти Некоторые сбои при выделении драйверов завершают процесс Python вместо того, чтобы возбуждать исключение MemoryError. (#484) Ограничьте размер значений, которые вы отправляете и получаете.
Производительность чтения при больших значениях Фрагментированные считывания данных varchar(max) и nvarchar(max) могут быть медленнее, чем с msodbcsql18. (#473) Оцените производительность своей нагрузки.

Сообщить о проблемах

Если вы столкнулись с ошибкой, воспроизведите её с помощью msodbcsql18 и запишите, возникает ли она с обоими провайдерами. Для получения инструкций по включению см. Включение драйвера.

Включите в отчёт вывод mssql_python.get_native_provider_info() вашей операционной системы, версии Python и драйверов, а также неудачный пакет T-SQL и сообщение об ошибке:

В Windows задайте эти переменные в PowerShell перед запуском Python, чтобы собрать нативную диагностику драйверов. Воспроизведите проблему с выбранным mssql-odbc:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE позволяет отслеживать, MSSQL_TDS_TRACE_LEVEL выбирает уровень журнала и MSSQL_TDS_TRACE_DIR выбирает каталог для файлов трассировки для каждого процесса из нативного драйвера ODBC вместо стандартного потока ошибок (stderr). Пакет-компаньон Rust также создаёт лог-файлы под mssql_python_logs в текущей директории.

Трассы могут содержать текст T-SQL и значения параметров. Скройте конфиденциальные данные перед тем, как делиться отрывками. После диагностики удалите эти переменные и перезапустите Python, чтобы отключить трассировку.

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

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