Novidades no mssql-python

Cada versão do driver mssql-python introduz novos recursos, melhorias de desempenho e correções de bugs. As seções seguintes detalham todas as versões.

mssql-python 1.12.0

Data de lançamento: julho de 2026

Enhancements

Pacote complementar independente mssql-python-odbc

Os binários do driver ODBC de que mssql-python precisa em tempo de execução agora também são publicados como um pacote complementar separado, somente de dados: mssql-python-odbc (nome de importação mssql_python_odbc, atualmente fixado na versão 18.6.2). O mssql-python pacote declara mssql-python-odbc==18.6.2 em install_requires, então pip install mssql-python instala transparentemente o pacote complementar junto com ele. Nenhuma alteração de código é necessária.

O loader nativo prefere o pacote externo mssql_python_odbc quando ele está presente e, quando não está, recorre aos binários ODBC ainda incluídos no wheel mssql-python. A alternativa de fallback é segura com o Global Interpreter Lock (GIL) do Python e funciona em distribuições Linux baseadas no musl, como o Alpine Linux.

Essa divisão permite fixar ou atualizar os binários dos drivers independentemente do código Python, reduz a roda dos mssql-python redistribuidores ao longo do tempo e evita problemas de duplicação de propriedade em arquivos ODBC agrupados.

Correções de erros

cursor.bulkcopy() Agora usa o timeout de conexão da conexão principal

A operação de cópia em massa abre uma conexão separada através da mssql_py_core extensão nativa. Anteriormente, essa operação sempre usava um timeout de conexão de 15 segundos codificado fixamente, sem como sobrescrevê-lo do Python. Se você definir um timeout de conexão na conexão principal (connect(..., timeout=<seconds>)), bulkcopy() agora encaminhará esse valor para a conexão interna. Definir timeout=0 preserva o comportamento de não substituição e mantém o valor interno padrão de 15 segundos. O timeout do cursor no momento da bulkcopy() chamada é usado para a operação, então mudanças posteriores na conexão pai não afetam uma cópia em massa durante o voo.

O exemplo a seguir usa a tabela de consulta Production.Culture do banco de dados de exemplo AdventureWorks. Ajuste a cadeia de conexão e o nome do banco de dados para o seu ambiente:

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() suporta colunas de tipo CLR definidas pelo usuário

Anteriormente, cursor.bulkcopy() falhava com Protocol Error: Unsupported TDS type for bulk copy: 0xF0 em qualquer coluna de destino que usasse um tipo definido pelo usuário (UDT) do Common Language Runtime (CLR), incluindo os tipos internos geography, geometry e hierarchyid e qualquer UDT CLR personalizado registrado em um assembly. O wire path nativo mssql_py_core não tinha um manipulador para o token de tipo UDT (0xF0) e gerou um erro ao gravar os metadados da coluna, antes que qualquer linha fosse enviada. As colunas UDT do CLR agora são mapeadas para varbinary(max) na transmissão, e os bytes fornecidos são transmitidos em fluxo como a carga útil do UDT IBinarySerialize, da mesma forma que pyodbc e python-tds carregam colunas UDT. O SQL Server materializa o UDT ao inserir. Entregue por meio da mssql_py_core atualização da versão 0.1.6 para 0.1.7.

O exemplo a seguir arquiva a coluna org-chart de HumanResources.Employee (uma coluna hierarchyid, um dos UDTs CLR internos do SQL Server) em uma nova tabela. Em um fluxo de trabalho real, os bytes UDT podem vir de outra instância do SQL Server, de um arquivo serializado ou da saída de IBinarySerialize.Write() do seu tipo CLR; este exemplo os lê de uma coluna existente por meio de CAST(... AS varbinary(max)) para que o exemplo seja independente. A cópia em massa inclui a linha cuja 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")

Para um CLR UDT personalizado registrado em um assembly, use o tipo na tabela de destino e forneça os bytes produzidos pelo método IBinarySerialize.Write() do tipo.

mssql-python 1.11.0

Data de lançamento: julho de 2026

Enhancements

Semântica aprimorada do gerenciador de contexto

with connection: agora confirma corretamente as transações ao encerrar normalmente e as desfaz em caso de exceção, o que o torna mais idiomático em Python e previsível.

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

Correções de erros

• Corrigido um deadlock do GIL na rotina de encerramento do ODBC (conn.close() e cursor.close()) e em SQLDescribeParam para parâmetros com valor None em configurações com túnel SSH e com forwarder no processo.
• Parâmetros fixos BINARY e VARBINARY NULL em tabelas temporárias e variáveis de tabela. Quando a resolução automática de tipos falha, o driver agora emite um aviso em Python com orientação explícitacursor.setinputsizes().
• Corrigido o problema em que import mssql_python falhava no Apple Silicon em uma instalação limpa (regressão na versão 1.8.0). As dependências ODBC dylib incluídas agora são reescritas para as arquiteturas arm64 e x86_64.
• Corrigido um deadlock do GIL no núcleo em Rust que congelava operações de cópia em massa durante a autenticação com Authentication=ActiveDirectoryServicePrincipal.

mssql-python 1.10.0

Data de lançamento: junho de 2026

Enhancements

Suporte ao ActiveDirectoryServicePrincipal para cópia em massa

cursor.bulkcopy() Agora suporta Authentication=ActiveDirectoryServicePrincipal, permitindo inserções em massa usando credenciais do principal de serviço.

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")

Correções de erros

• Corrigidos os dados não ASCII VARCHAR e CHAR no caminho de busca do Arrow.
• Prazos de conexão fixos durante operações de carga a granel.

mssql-python 1.9.0

Data de lançamento: junho de 2026

Enhancements

Objetos de linha na cópia em massa

cursor.bulkcopy() agora aceita objetos buscados Row diretamente em vez de exigir conversão manual de tuplas.

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")

Correções de erros

• Embalagem de roda fixa, então simdutf está sempre ligada estaticamente.
• Fixaram grandes DECIMAL inserts em executemany().
• Corrigido o tipo incorreto de fallback para parâmetros NULL.
• Exceção fixa das viagens de ida e volta de pickle e despepilha.
• Corrigido nextset() para que preserve PRINT mensagens entre diferentes conjuntos de resultados.
• Tratamento corrigido Row no executemany() caminho de fallback de dados na execução.
• Fixou a verificação de tipos de método fetch para ferramentas de análise estática.

mssql-python 1.8.0

Data de lançamento: maio de 2026

Enhancements

Suporte ao ActiveDirectoryMSI para cópia em massa

cursor.bulkcopy() agora oferece suporte a Authentication=ActiveDirectoryMSI para identidades gerenciadas atribuídas pelo sistema e atribuídas pelo usuário.

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")

Indexação de linhas por chave de texto

Agora você pode acessar valores de linha pelo nome da coluna, por exemplo row["col"], além da indexação posicional e do acesso a atributos.

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

Atualização do driver ODBC incluído

O driver Microsoft ODBC para SQL Server incluído foi atualizado para a versão 18.6.2.1.

Correções de erros

• Corrigidos problemas no ciclo de vida do connect-attribute adiado na autenticação baseada em tokens.
• Corrigiu a análise repetida da cadeia de conexão no fluxo de autenticação.
• Anotações de tipo fixo executemany() para entradas de sequência.

MSSQL-Python 1.7.1

Data de lançamento: maio de 2026

Enhancements

Cobertura ampliada das rodas e melhorias de desempenho

Esta versão adiciona wheels compatíveis com o RHEL 8, restaura os wheels do Python 3.10 para macOS universal2, melhora o tratamento de UTF-16 por meio de simdutf e otimiza o caminho crítico de execute().

Impacto no desempenho: A taxa de execução em lote melhora em ~15% em relação às cargas de trabalho típicas devido às otimizações do caminho quente no execute() método.

Correções de erros

• Falhas de login foram corrigidas para que gerem exceções mssql_python DB-API em vez de RuntimeError.
• Liberação estendida de GIL bloqueando a execução, busca, transação e chamadas de atributos de conexão ODBC.
• Corrigidas falhas executemany() quando valores decimais mudam de sinal.
• Corrigi a decodificação inconsistente do CP1252 VARCHAR entre plataformas.
• Corrigidas falhas com strings vazias nas colunas cursor.bulkcopy() e NVARCHAR(MAX).

mssql-python 1.6.0

Data de lançamento: abril de 2026

Enhancements

Sanitização de cadeia de conexão baseada em analisador sintático

Esse aprimoramento garante a interpretação correta de caracteres especiais nos campos de senha e em valores entre chaves.

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"
)

A sanitização da cadeia de conexão passou da lógica baseada em expressões regulares para o processamento com analisador sintático, para o tratamento correto da sintaxe da cadeia de conexão ODBC.

Correções de erros

• Corrigida a liberação do GIL durante operações bloqueantes de conexão e desconexão via ODBC.
• Corrigi setinputsizes() travamentos com SQL_DECIMAL e SQL_NUMERIC dicas.
• Corrigido o comportamento incorreto de fetchone() para métodos do catálogo ODBC.
• Corrigido erros de estado inválido do cursor quando reset_cursor=False é usado.
• Dicas de tipo fixo executemany() para sequências de parâmetros baseadas em mapeamento.
• Adicionou uma proteção de travessia de caminho para setup_logging(log_file_path=...).

MSSQL-Python 1.5.0

Data de lançamento: abril de 2026

Novos recursos

Suporte de busca Apache Arrow

Três novos métodos de cursor oferecem recuperação colunar de dados de alto desempenho por meio da Interface de Dados Arrow C:

• cursor.arrow() retorna um pyarrow.Table completo.
• cursor.arrow_batch() retorna um único pyarrow.RecordBatch.
• cursor.arrow_reader() retorna pyarrow.RecordBatchReader para streaming.

A implementação ignora a criação de objetos em Python no caminho quente para melhorar o desempenho. Para documentação completa, veja integração com o Apache Arrow.

suporte ao tipo sql_variant

O driver agora detecta colunas sql_variant no momento da busca, determina seu tipo base subjacente e retorna valores de Python com o tipo correto, em vez de bytes brutos.

Suporte nativo à UUID

Uma nova configuração native_uuid controla se as colunas UNIQUEIDENTIFIER são retornadas como objetos uuid.UUID (padrão) ou como cadeias de caracteres em maiúsculas compatíveis com pyodbc. Configure em nível de módulo ou por conexão:

# 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)

Para mais informações, veja Configuração do módulo.

Exportação pública da classe Row

A Row classe agora é exportada no nível superior para anotações de tipos:

from mssql_python import Row

Correções de erros

• Corrigiu a detecção incorreta de ? dentro de identificadores entre colchetes, literais de cadeia de caracteres e comentários.
• Fixei a vinculação de parâmetros NULL para VARBINARY colunas (não gera mais erros implícitos de conversão).
• Corrigida a perda de microssegundos em valores datetime.time durante operações de ida e volta para colunas de TIME(1) a TIME(7).
• Corrigido o caminho de busca do Arrow para incluir corretamente frações de segundo para colunas TIME.
• Cópia em massa corrigida com métodos de autenticação do Microsoft Entra ID (campos de credenciais obsoletos não causam mais erros de validação).
• Instâncias de credenciais Azure Identity armazenadas em cache no nível do módulo para melhorar o desempenho da autenticação.

mssql-python 1.4.0

Data de lançamento: março de 2025

Novos recursos

Suporte para cópia em massa

O carregamento de dados em massa de alto desempenho agora está disponível por meio de: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")

O método aceita opções para batch_size, timeout, column_mappings, keep_identity, check_constraintstable_lock, , keep_nulls, fire_triggers, e use_internal_transaction.

Consulte Cópia em massa para obter a documentação completa.

Improvements

• Otimizações de desempenho para grandes conjuntos de resultados.
• Uso reduzido de memória durante operações em lote.
• Mensagens de erro aprimoradas para falhas de cópia em massa.

mssql-python 1.3.0

Data de lançamento: janeiro de 2025

Novos recursos

Classe de configurações

Configure o comportamento em todo o módulo através da nova Settings classe:

import mssql_python

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

Veja Configuração do módulo para detalhes.

Improvements

• Melhor manejo do timeout da conexão durante o failover do SQL do Azure.
• Compatibilidade aprimorada com Python 3.13.

MSSQL-Python 1.2.0

Data de lançamento: novembro de 2024

Novos recursos

Métodos de descoberta de esquemas

Novos métodos de cursor para exploração de metadados de banco de dados:

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()

Veja Descoberta de Esquema para documentação completa.

Improvements

• Cache aprimorado de metadados para consultas repetidas de esquema.
• Melhor manejo das colunas computadas nos columns() resultados.

mssql-python 1.1.0

Data de lançamento: setembro de 2024

Novos recursos

Conversores de saída personalizados

Registrar funções personalizadas para transformar valores de coluna durante a busca:

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)

Métodos de manejo:

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

Para documentação completa, veja Conversores de tipo personalizado.

Improvements

• Melhores mensagens de erro para falhas na conversão de tipo.
• Suporte para funções de conversor que retornam None.

MSSQL-Python 1.0.0

Data de lançamento: julho de 2024

Lançamento inicial para disponibilidade geral

A primeira versão de disponibilidade geral do mssql-python, o driver nativo de Python da Microsoft para SQL Server.

Principais recursos

• Arquitetura DDBC: Conectividade direta com banco de dados sem exigir instalação de drivers ODBC.
• Conformidade com a DB-API 2.0: Interface padrão de banco de dados do Python.
• Pool de conexões: Gerenciamento integrado de pool de conexões.
• Autenticação Microsoft Entra: Suporte completo para autenticação baseada em identidade no Azure.
• Criptografia TLS: Conexões seguras com validação de certificados.

Recursos de conexão

• 21 palavras-chave de cadeia de conexão.
• 9 modos de autenticação (SQL, Windows e 7 métodos Microsoft Entra ID).
• Controle de autocommit.
• Métodos de execução: execute(), executemany(), e batch_execute().
• Atributos de conexão através de set_attr() e getinfo().
• Suporte ao gerenciador de contexto.

Recursos do cursor

• Métodos padrão de busca: fetchone(), fetchmany(), fetchall().
• Métodos estendidos: fetchval(), skip().
• Métodos de execução: execute() e executemany().
• Objetos de linha com acesso a atributos e índice.
• Navegação por múltiplos conjuntos de resultados com nextset().

Suporte do tipo de dados

• Todos os tipos nativos do SQL Server.
• Mapeamentos de tipos entre Python e SQL.
• Constantes de tipo SQL para tipagem explícita (por exemplo, mssql_python.SQL_DECIMAL).
• Tratamento de NULL em Python None.

Suporte à transação

• Commit e rollback manuais.
• Modo de autocommit.
• Controle de nível de isolamento.
• Detecção e manuseio de bloqueios.

Modos de autenticação

Upgrade

De pyodbc

Para orientações detalhadas sobre migração, veja Migrar a partir de pyodbc.

Principais diferenças:

• Tanto o estilo de parâmetro ? (qmark) quanto o estilo de parâmetro %(name)s (pyformat) são suportados. Suas consultas existentes ? funcionam sem alterações.
• Nenhum método callproc(). Use instruções EXECUTE em vez delas.
• Pool de conexões integrado.
• Sem dependência de driver ODBC externo.

De pymssql

Para orientações detalhadas sobre migração, veja Migrar a partir do pymssql.

Principais diferenças:

• Substitua os marcadores de parâmetro %s e %d por ? ou %(name)s.
• Use uma cadeia de conexão em vez de argumentos posicionais.
• Sem dependência do FreeTDS.
• Múltiplos cursores concorrentes por conexão.
• Objetos de linha com acesso a atributos substituem as_dict=True.

Entre as versões mssql-python

Atualize o driver para obter novos recursos e correções.

pip install --upgrade mssql-python

Verifique as notas de lançamento para ver se há mudanças quebrantes antes de atualizar os sistemas de produção.

Roteiro

Para recursos futuros e o roteiro de desenvolvimento, veja o repositório GitHub.

Conteúdo relacionado

• Driver mssql-python
• Ciclo de vida do suporte
• Instalação
• Lançamentos do GitHub