Что нового в MSSQL-Python

Каждый релиз драйвера mssql-python вводит новые функции, улучшения производительности и исправления ошибок. Следующие разделы подробно описывают каждую версию.

MSSQL-Python 1.12.0

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

Усовершенствования

Отдельный mssql-python-odbc сопутствующий пакет

Бинарные файлы драйвера ODBC, необходимые mssql-python во время выполнения, теперь также публикуются как отдельный сопутствующий пакет, содержащий только данные: mssql-python-odbc (имя импорта — mssql_python_odbc, в настоящее время зафиксировано на версии 18.6.2). Пакет mssql-python объявляет mssql-python-odbc==18.6.2 в install_requires, поэтому pip install mssql-python прозрачно устанавливает сопутствующий пакет вместе с ним. Никаких изменений кода не требуется.

Нативный загрузчик предпочитает внешний пакет mssql_python_odbc, если он доступен, а в противном случае использует бинарные файлы ODBC, которые по-прежнему входят в состав колеса mssql-python. Запасной вариант безопасен с Python Global Interpreter Lock (GIL) и работает на дистрибутивах Linux на базе musl, таких как Alpine.

Это разделение позволяет фиксировать или обновлять двоичные файлы драйвера независимо от кода Python, со временем обеспечивая распространителям меньший по размеру пакет wheel mssql-python, и позволяет избежать проблем с дублированием владения из-за включённых в пакет файлов ODBC.

Это важно

Этот сплит выходит без изменений. В одном из будущих крупных релизов (v2.0.0) встроенное дерево libs/ может быть удалено; в этом случае mssql-python-odbc станет обязательной зависимостью времени выполнения.

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

cursor.bulkcopy() теперь используется тайм-аут соединения родительского соединения

Операция массового копирования открывает отдельное соединение через нативное mssql_py_core расширение. Ранее эта операция всегда использовала жёстко закодированный 15-секундный тайм-аут соединения без возможности переопределить его из Python. Если вы установите тайм-аут соединения на родительском соединении (connect(..., timeout=<seconds>)), bulkcopy() теперь пересылает это значение во внутреннее соединение. Настройка timeout=0 сохраняет поведение без переопределения и сохраняет внутренний 15-секундный режим по умолчанию. Для этой операции используется значение тайм-аута курсора на момент вызова bulkcopy(), поэтому последующие изменения родительского соединения не влияют на уже выполняемое массовое копирование.

Следующий пример использует Production.Culture таблицу поиска из примерной базы данных AdventureWorks . Настройте строка подключения и имя базы данных для вашей среды:

import mssql_python
from datetime import datetime

# The 60-second timeout applies to both the initial connection and
# the internal connection that bulkcopy() opens.
conn = mssql_python.connect(
    "Server=<server>;"
    "Database=AdventureWorks2022;"
    "Encrypt=yes",
    timeout=60,
)
conn.autocommit = True
cursor = conn.cursor()

# Bulk-copy two rows into Production.Culture (CultureID, Name, ModifiedDate).
now = datetime.now()
rows = [
    ("xx", "Demo culture 1", now),
    ("yy", "Demo culture 2", now),
]
result = cursor.bulkcopy("Production.Culture", rows)
print(f"Copied {result['rows_copied']} rows")

# Remove the demo rows so the sample is re-runnable.
cursor.execute("DELETE FROM Production.Culture WHERE CultureID IN ('xx','yy')")

cursor.bulkcopy() поддерживает пользовательские столбцы типов CLR

Ранее cursor.bulkcopy() завершался сбоем с Protocol Error: Unsupported TDS type for bulk copy: 0xF0 для любого целевого столбца, использующего пользовательский тип CLR (Common Language Runtime), включая встроенные типы geography, geometry и hierarchyid, а также любой пользовательский тип CLR UDT, зарегистрированный в сборке. Собственный путь протокола mssql_py_core не имел обработчика для токена типа UDT (0xF0) и выдавал ошибку при записи метаданных столбцов до отправки каких-либо строк. Столбцы CLR UDT теперь передаются как varbinary(max), а передаваемые байты передаются потоком как полезная нагрузка UDT IBinarySerialize, что соответствует тому, как pyodbc и python-tds загружают столбцы UDT. SQL Server материализует UDT при вставке. Реализовано через mssql_py_core обновление с 0.1.6 до 0.1.7.

Следующий пример архивирует столбец org-chart из HumanResources.Employee в новую таблицу (столбец типа hierarchyid, одного из встроенных типов CLR UDT в SQL Server). В реальном рабочем процессе байты UDT могут поступать из другого экземпляра SQL Server, сериализованного файла или из выходных данных типа CLR IBinarySerialize.Write(); в этом примере они считываются из существующего столбца с помощью CAST(... AS varbinary(max)), чтобы пример был самодостаточным. Основная копия включает строку, которая OrganizationNode равна NULL:

import mssql_python

conn = mssql_python.connect(
    "Server=<server>;"
    "Database=AdventureWorks2022;"
    "Encrypt=yes",
)
conn.autocommit = True  # bulkcopy uses a separate connection; the destination must be visible
cursor = conn.cursor()

cursor.execute(
    "IF OBJECT_ID('dbo.EmployeeOrgArchive','U') IS NOT NULL "
    "DROP TABLE dbo.EmployeeOrgArchive;"
    "CREATE TABLE dbo.EmployeeOrgArchive (BusinessEntityID int, OrganizationNode hierarchyid);"
)

# Casting a hierarchyid column to varbinary(max) yields the UDT's
# serialized IBinarySerialize payload.
cursor.execute(
    "SELECT BusinessEntityID, CAST(OrganizationNode AS varbinary(max)) "
    "FROM HumanResources.Employee;"
)
rows = cursor.fetchall()

# Stream the (id, bytes) tuples into the destination's hierarchyid column.
result = cursor.bulkcopy("dbo.EmployeeOrgArchive", rows)
print(f"Copied {result['rows_copied']} rows")

cursor.execute("DROP TABLE dbo.EmployeeOrgArchive")

Для кастомного CLR UDT с регистрацией в ассемблере используйте тип в таблице назначения и указывайте байты, полученные методом IBinarySerialize.Write() этого типа.

MSSQL-Python 1.11.0

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

Усовершенствования

Улучшенная семантика менеджера контекста

with connection: теперь корректно фиксирует транзакции при корректном завершении и откатывает их при возникновении исключения, что делает его поведение более соответствующим духу Python и более предсказуемым.

import mssql_python

# On clean exit, transaction commits
with mssql_python.connect(connection_string) as conn:
    cursor = conn.cursor()
    cursor.execute("INSERT INTO MyTable (Name) VALUES ('Alice')")
    # Automatically committed on exit

# On exception, transaction rolls back
try:
    with mssql_python.connect(connection_string) as conn:
        cursor = conn.cursor()
        cursor.execute("INSERT INTO MyTable (Name) VALUES ('Bob')")
        raise ValueError("Oops!")
except ValueError:
    pass
# Changes rolled back on exit

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

• Исправлена взаимная блокировка GIL в коде завершения работы ODBC (conn.close() и cursor.close()), а также в SQLDescribeParam для параметров со значением None в конфигурациях SSH-туннеля и внутрипроцессного форвардера.
• Фиксированные BINARY и VARBINARY NULL параметры в временных таблицах и таблицах переменных. Когда автоматическое разрешение типов не работает, драйвер издаёт предупреждение на Python с явными cursor.setinputsizes() указаниями.
• Исправлен import mssql_python сбой на Apple Silicon при чистой установке (регрессия в версии 1.8.0). Входящие в комплект зависимости библиотеки ODBC dylib теперь переписаны для архитектур arm64 и x86_64.
• Исправлена взаимная блокировка GIL в ядре Rust, которая приводила к зависанию операций массового копирования при аутентификации с помощью Authentication=ActiveDirectoryServicePrincipal.

MSSQL-Python 1.10.0

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

Усовершенствования

Поддержка массового копирования для ActiveDirectoryServicePrincipal

cursor.bulkcopy() теперь поддерживает Authentication=ActiveDirectoryServicePrincipal, позволяя массовые вставки с использованием учетных данных главного сервиса.

import mssql_python

conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryServicePrincipal;"
    "UID=<application-client-id>;"
    "PWD=<client-secret>;"
    "Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##SpDemo (ID INT, Value FLOAT)")
conn.commit()

result = cursor.bulkcopy("##SpDemo", [(1, 1.5), (2, 2.5)])
print(f"Copied {result['rows_copied']} rows")

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

• Исправлены данные с не-ASCII-символами VARCHAR и CHAR в пути извлечения Arrow.
• Фиксированные тайм-ауты соединения во время операций с массовой загрузкой.

MSSQL-Python 1.9.0

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

Усовершенствования

Объекты строк при массовом копировании

cursor.bulkcopy() теперь принимает полученные Row объекты напрямую, вместо необходимости ручного преобразования кортежа.

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

# Fetch rows from source table
cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product")
rows = cursor.fetchall()

# Pass fetched Row objects directly to bulkcopy
cursor.execute("CREATE TABLE ##RowBulkDemo (ProductID INT, Name NVARCHAR(50), ListPrice MONEY)")
conn.commit()
result = cursor.bulkcopy("##RowBulkDemo", rows)
print(f"Copied {result['rows_copied']} rows")

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

• Упаковка с фиксированным колесом, поэтому simdutf всегда связана статически.
• Исправлены крупные DECIMAL вставки в executemany().
• Исправлен неправильный тип резерва для параметров NULL.
• Фиксированное исключение — туда-обратно огурцы и нерассоленные рейсы.
• Исправлено: nextset() это сохраняет PRINT сообщения между наборами результатов.
• Исправлена Row обработка в executemany() резервном пути данных при выполнении.
• Исправлена проверка типов метода fetch для инструментов статического анализа.

MSSQL-Python 1.8.0

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

Усовершенствования

Поддержка ActiveDirectoryMSI для массового копирования

cursor.bulkcopy() теперь поддерживает Authentication=ActiveDirectoryMSI для системно назначаемых и назначаемых пользователем управляемых удостоверений.

import mssql_python

# System-assigned managed identity
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "Authentication=ActiveDirectoryMSI;"
    "Encrypt=yes"
)
cursor = conn.cursor()
cursor.execute("CREATE TABLE ##MsiDemo (ID INT, Name NVARCHAR(50))")
conn.commit()

result = cursor.bulkcopy("##MsiDemo", [(1, "Alice"), (2, "Bob")])
print(f"Copied {result['rows_copied']} rows")

Индексация строк по строковому ключу

Теперь вы можете получать доступ к значениям строк по названию столбца, например row["col"], помимо позиционного индексирования и доступа к атрибутам.

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

cursor.execute("SELECT ProductID, Name, ListPrice FROM Production.Product WHERE ProductID = 1")
row = cursor.fetchone()

# Access by column name (new in 1.8.0)
print(row["ProductID"]) # Access by key
print(row["Name"])

# Still supports positional indexing
print(row[0])           # Positional access

# And attribute access
print(row.Name)         # Attribute access

Обновление драйвера ODBC, входящего в комплект

Включённый в комплект драйвер Microsoft ODBC для SQL Server был обновлён до версии 18.6.2.1.

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

• Исправлены проблемы с отложенным сроком службы атрибута соединения при аутентификации на основе токенов.
• Исправлен повторный разбор строки подключения в процессе аутентификации.
• Фиксированные executemany() типовые аннотации для входов последовательностей.

MSSQL-Python 1.7.1

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

Усовершенствования

Расширенное покрытие колёс и улучшение производительности

В этом релизе добавлены wheel-пакеты, совместимые с RHEL 8, восстановлены wheel-пакеты для macOS и Python 3.10 universal2, улучшена обработка UTF-16 с помощью simdutf, а также оптимизирован критический участок кода execute().

Влияние на производительность: пропускная способность пакетного выполнения улучшается на ~15% по сравнению с типичными нагрузками благодаря оптимизации горячих путей в execute() методе.

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

• Исправлены сбои при входе, из-за которых теперь вызываются исключения DB-API mssql_python вместо RuntimeError.
• Расширенный релиз GIL блокирует выполнение, извлечение, транзакции и вызовы атрибутов соединения ODBC.
• Исправлены executemany() ошибки при изменении знака десятичных значений.
• Исправлено несогласованное декодирование CP1252 VARCHAR на разных платформах.
• Исправлены cursor.bulkcopy() сбои при пустых строках в столбцах NVARCHAR(MAX) и VARCHAR(MAX).

Замечание

Версия 1.7.0 была отозвана из-за проблем с публикацией. Используйте версию 1.7.1 или более позднюю.

MSSQL-Python 1.6.0

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

Усовершенствования

Очистка строки подключения на основе парсера

Это улучшение обеспечивает правильный разбор специальных символов в полях пароля и значениях в фигурных скобках.

import mssql_python

# Complex passwords with special characters now parse correctly
conn = mssql_python.connect(
    "Server=<server>.database.windows.net;"
    "Database=<database>;"
    "UID=user@contoso;"
    "PWD={p@ssw0rd;with{braces}};"  # Braced values now handled correctly
    "Encrypt=yes"
)

Очистка строки подключения была переведена с логики на основе регулярных выражений на обработку с использованием парсера для корректной работы с синтаксисом строки подключения ODBC.

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

• Исправлено освобождение GIL во время блокировки операций подключения и отключения ODBC.
• Исправлены setinputsizes() вылеты, связанные с подсказками SQL_DECIMAL и SQL_NUMERIC.
• Исправлено некорректное fetchone() поведение методов каталога ODBC.
• Исправлены ошибки недопустимого состояния курсора при использовании reset_cursor=False.
• Фиксированные executemany() типовые подсказки для последовательностей параметров на основе отображения.
• Добавлена защита для прохождения пути для setup_logging(log_file_path=...).

MSSQL-Python 1.5.0

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

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

Поддержка получения данных Apache Arrow

Три новых метода курсора обеспечивают высокопроизводительное извлечение столбцов данных через интерфейс данных Arrow C:

• cursor.arrow() возвращает полный pyarrow.Table.
• cursor.arrow_batch() возвращает один pyarrow.RecordBatch.
• cursor.arrow_reader() возвращает pyarrow.RecordBatchReader для потоковой передачи.

Реализация позволяет избежать создания объектов Python в критическом участке кода, что повышает производительность. Полная документация см. в разделе интеграция Apache Arrow.

Поддержка типа sql_variant

Драйвер теперь определяет столбцы sql_variant при извлечении данных, определяет их базовый тип и возвращает значения Python с корректными типами вместо необработанных байтов.

Замечание

sql_variant столбцы используют потоковый способ получения данных, что может немного повлиять на производительность по сравнению со столбцами фиксированного типа.

Нативная поддержка UUID

Новая настройка native_uuid определяет, будут ли столбцы UNIQUEIDENTIFIER возвращаться в виде объектов uuid.UUID (по умолчанию) или в виде совместимых с pyodbc строк в верхнем регистре. Настройте его на уровне модуля или для каждого соединения:

# Module-level default
settings = mssql_python.get_settings()
settings.native_uuid = True  # default

# Per-connection override
conn = mssql_python.connect(connection_string, native_uuid=False)

Для получения дополнительной информации см. раздел Конфигурация модуля.

Класс Row для публичного экспорта

Класс Row теперь экспортируется на верхнем уровне для аннотаций типов:

from mssql_python import Row

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

• Исправлено ложное обнаружение ? внутри идентификаторов в скобках, строковых литералов и комментариев.
• Исправлено привязывание параметров NULL для VARBINARY столбцов (больше не вызывает неявных ошибок преобразования).
• Исправлена проблема потери микросекунд в значениях datetime.time при преобразовании туда и обратно в столбцах с TIME(1) по TIME(7).
• Исправлен путь выборки Arrow, чтобы он корректно включал доли секунды для столбцов TIME.
• Исправлено массовое копирование с помощью методов аутентификации Microsoft Entra ID (устаревшие поля учетных данных больше не вызывают ошибок валидации).
• Кэшированные экземпляры учетных данных Azure Identity на уровне модуля для улучшения производительности аутентификации.

MSSQL-Python 1.4.0

Дата выхода: март 2025

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

Поддержка массового копирования

Высокопроизводительная массовая загрузка данных теперь доступна через cursor.bulkcopy():

import mssql_python

conn = mssql_python.connect(connection_string)
cursor = conn.cursor()

cursor.execute("CREATE TABLE ##BulkDemo (ID INT, Name NVARCHAR(50), Price DECIMAL(10,2))")
conn.commit()

data = [
    (1, "Item 1", 10.50),
    (2, "Item 2", 20.75),
    # ... potentially millions of rows
]

result = cursor.bulkcopy("##BulkDemo", data)
print(f"Copied {result['rows_copied']} rows")

Метод принимает варианты для batch_size, timeout, column_mappings, keep_identity, check_constraintstable_lockkeep_nullsfire_triggersи .use_internal_transaction

Подробную документацию см. в разделе «Массовое копирование».

Improvements

• Оптимизации производительности для больших наборов результатов.
• Снижение использования памяти во время пакетных операций.
• Улучшенные сообщения об ошибках при сбоях массового копирования.

MSSQL-Python 1.3.0

Дата выхода: январь 2025

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

Класс настроек

Настройте поведение на уровне всего модуля через новый Settings класс:

import mssql_python

settings = mssql_python.get_settings()
settings.lowercase = True       # Lowercase column names in cursor.description

См. конфигурацию модуля для подробностей.

Improvements

• Улучшена обработка тайм-аута подключения во время аварийного переключения Azure SQL.
• Улучшена совместимость с Python 3.13.

MSSQL-Python 1.2.0

Дата выхода: ноябрь 2024

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

Методы обнаружения схем

Новые курсорные методы для исследования метаданных базы данных:

cursor = conn.cursor()

# List all tables
cursor.tables(schema="dbo")

# Get column information
cursor.columns(table="Product", schema="Production")

# Get primary keys
cursor.primaryKeys(table="Product", schema="Production")

# Get foreign key relationships
cursor.foreignKeys(table="SalesOrderDetail", schema="Sales")

# Get stored procedures
cursor.procedures(schema="dbo")

# Get index statistics
cursor.statistics(table="Product", schema="Production")

# Get type information
cursor.getTypeInfo()

См. раздел «Обнаружение схемы » для полной документации.

Improvements

• Улучшенное кэширование метаданных для повторяющихся запросов схемы.
• Более эффективная обработка вычисленных столбцов в columns() результатах.

MSSQL-Python 1.1.0

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

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

Пользовательские выходные преобразователи

Регистрируйте пользовательские функции для преобразования значений столбцов во время выборки:

import mssql_python
from decimal import Decimal

conn = mssql_python.connect(connection_string)

# Convert decimals to float (converter receives Decimal)
def decimal_to_float(value):
    if value is None:
        return None
    return float(value)  # value is already a Decimal object

conn.add_output_converter(mssql_python.SQL_DECIMAL, decimal_to_float)

# Custom money formatting
def format_money(value):
    if value is None:
        return "$0.00"
    return f"${float(value):,.2f}"  # value is already a Decimal object

conn.add_output_converter(mssql_python.SQL_DECIMAL, format_money)

Методы управления:

• add_output_converter(sql_type, converter_func)
• get_output_converter(sql_type)
• remove_output_converter(sql_type)
• clear_output_converters()

Полную документацию см. в разделе «Пользовательские преобразователи типов».

Improvements

• Улучшенные сообщения об ошибках при ошибках преобразования типов.
• Поддержка преобразовательных функций, возвращающих None.

MSSQL-Python 1.0.0

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

Первый общедоступный релиз

Первый общий выпуск mssql-python — нативного драйвера Python от Microsoft для SQL Server.

Основные возможности

• Архитектура DDBC: прямое подключение к базе данных без необходимости установки драйверов ODBC.
• Соответствие DB-API 2.0: стандартный интерфейс Python для баз данных.
• Пул соединений: встроенное управление пулом соединений.
• Аутентификация Microsoft Entra: Полная поддержка аутентификации на основе удостоверений Azure.
• Шифрование TLS: Безопасные соединения с валидацией сертификатов.

Особенности соединения

• 21 ключевое слово строки подключения.
• 9 режимов аутентификации (SQL, Windows и 7 методов Microsoft Entra ID).
• Автоматическое управление коммитированием.
• Методы выполнения: execute(), executemany(), и batch_execute().
• Атрибуты связи через set_attr() и getinfo().
• Поддержка менеджера контекста.

Особенности курсора

• Стандартные методы получения: fetchone(), fetchmany(), fetchall().
• Расширенные методы: fetchval(), skip().
• Методы выполнения: execute() и executemany().
• Объекты строк с доступом к атрибуту и индексу.
• Навигация по нескольким наборам результатов с nextset().

Поддержка типов данных

• Все нативные типы SQL Server.
• Сопоставления типов Python ↔ SQL
• Константы типов SQL для явной типизации (например, mssql_python.SQL_DECIMAL).
• Обработка NULL в формате PythonNone.

Поддержка транзакций

• Ручное закрепление и откат.
• Режим автокоммитирования.
• Контроль уровня изоляции.
• Обнаружение и обработка тупиков.

Режимы проверки подлинности

Mode	Описание
Проверка подлинности SQL Server	Имя пользователя и пароль
Аутентификация Windows	Trusted_Connection
ActiveDirectoryDefault	DefaultAzureCredential
ActiveDirectoryInteractive	Вход через браузер
ActiveDirectoryDeviceCode	Процесс ввода кода устройства
ActiveDirectoryPassword	Имя пользователя и пароль Microsoft Entra (устарело; использует ROPC)
ActiveDirectoryMSI	Манажируемая идентичность
ActiveDirectoryServicePrincipal	Сервис-принципал
Интегрировано с Active Directory	Windows Kerberos

Upgrade

Из pyodbc

Подробные инструкции по миграции см. в разделе Переход с pyodbc.

Основные различия:

• Поддерживаются оба стиля параметров: ? (qmark) и %(name)s (pyformat). Ваши существующие ? запросы работают без изменений.
• Метод callproc() отсутствует. Используйте инструкции EXECUTE вместо этого.
• Встроенный пул соединений.
• Нет внешних зависимостей от драйвера ODBC.

Из pymssql

Для подробного руководства по миграции см. раздел Migrate from pymssql.

Основные различия:

• Замените %s и %d маркеры параметров на ? или %(name)s.
• Используйте строка подключения вместо позиционных аргументов.
• Нет зависимости от FreeTDS.
• Несколько одновременных курсоров для одного соединения.
• Объекты строк с доступом к атрибутам заменяют as_dict=True.

Между версиями mssql-python

Обновите драйвер, чтобы получить новые функции и исправления.

pip install --upgrade mssql-python

Перед обновлением производственных систем проверьте заметки к релизу на наличие неисправных изменений.

Roadmap

Для будущих функций и дорожной карты разработки смотрите репозиторий GitHub.

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

• Драйвер mssql-python
• Жизненный цикл поддержки
• Installation
• Релизы на GitHub