Novidades no mssql-python

Cada versão do driver mssql-python introduz novas funcionalidades, melhorias de desempenho e correções de bugs. As secçõ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 controlador ODBC de que mssql-python necessita em tempo de execução são agora também publicados como um pacote complementar separado, apenas 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, por isso pip install mssql-python instala transparentemente o pacote complementar ao seu lado. Não são necessárias alterações de código.

O carregador nativo prefere o pacote externo mssql_python_odbc quando este está presente e, caso contrário, recorre aos binários ODBC ainda incluídos no wheel mssql-python. O plano B é seguro com o Python Global Interpreter Lock (GIL) e funciona em distribuições Linux baseadas em musl, como o Alpine.

Esta divisão permite fixar ou atualizar os binários dos drivers independentemente do código Python, dá aos redistribuidores uma roda mais pequena mssql-python ao longo do tempo e evita problemas de propriedade duplicada provenientes de ficheiros ODBC agrupados.

Correções de erros

cursor.bulkcopy() passa a usar o tempo limite de ligação da conexão principal

A operação de cópia em massa abre uma conexão separada através da extensão nativa mssql_py_core. Anteriormente, esta operação usava sempre um tempo limite de ligação de 15 segundos definido de forma fixa no código, sem possibilidade de o substituir a partir de Python. Se definir um tempo limite de ligação na ligação principal (connect(..., timeout=<seconds>)), bulkcopy() agora encaminha esse valor para a ligação interna. A definição timeout=0 preserva o comportamento de não substituição e mantém o valor predefinido interno de 15 segundos. O timeout do cursor no momento da bulkcopy() chamada é usado para a operação, por isso alterações posteriores à ligação principal não afetam uma cópia em massa em voo.

O exemplo seguinte utiliza a tabela de consulta Production.Culture da base de dados de exemplo AdventureWorks. Ajuste a cadeia de ligação e o nome da base 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 tipos CLR definidas pelo utilizador

Anteriormente, cursor.bulkcopy() falhava com Protocol Error: Unsupported TDS type for bulk copy: 0xF0 para qualquer coluna de destino que utilizasse um tipo definido pelo utilizador (UDT) do Common Language Runtime (CLR), incluindo os tipos incorporados geography, geometry e hierarchyid, bem como qualquer UDT CLR personalizado registado num assembly. O canal nativo mssql_py_core não tinha nenhum processador para o token de tipo UDT (0xF0) e gerou um erro ao escrever os metadados das colunas, antes de serem enviadas quaisquer linhas. As colunas UDT CLR são agora mapeadas para varbinary(max) na ligação, e os bytes fornecidos são enviados em fluxo como payload do UDT IBinarySerialize, em conformidade com a forma como pyodbc e python-tds carregam colunas UDT. O SQL Server materializa o UDT ao inserir. Disponibilizado através da mssql_py_core atualização de 0.1.6 para 0.1.7.

O exemplo seguinte arquiva a coluna de organograma de HumanResources.Employee (uma coluna hierarchyid, um dos UDTs CLR incorporados do SQL Server) numa nova tabela. Num fluxo de trabalho real, os bytes UDT podem vir de outra instância do SQL Server, de um ficheiro serializado ou da saída de IBinarySerialize.Write() do seu tipo CLR; este exemplo lê-os de uma coluna existente através de CAST(... AS varbinary(max)), para que o exemplo seja autónomo. A cópia em massa inclui a linha em que 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, registado num 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 melhorada do gestor de contexto

with connection: agora confirma corretamente as transações ao terminar sem erros e anula-as em caso de exceção, tornando-o 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 interbloqueio do GIL no processo 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 encaminhador 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 emite agora um aviso Python com orientação explícitacursor.setinputsizes().
• Corrigida a falha de import mssql_python em Apple Silicon numa instalação limpa (regressão introduzida na versão 1.8.0). As dependências ODBC dylib incluídas foram agora reescritas para as arquiteturas arm64 e x86_64.
• Corrigido um deadlock GIL no núcleo Rust que congelava as operações de cópia em massa ao autenticar com Authentication=ActiveDirectoryServicePrincipal.

mssql-python 1.10.0

Data de lançamento: junho de 2026

Enhancements

Suporte ActiveDirectoryServicePrincipal para cópia em massa

cursor.bulkcopy() suporta agora Authentication=ActiveDirectoryServicePrincipal, permitindo inserções em lote utilizando 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 obtenção do Arrow.
• Corrigidos os tempos limite de ligação durante operações de carregamento em massa.

MSSQL-Python 1.9.0

Data de lançamento: junho de 2026

Enhancements

Objetos de linha na cópia em massa

cursor.bulkcopy() passa agora a aceitar diretamente objetos obtidos Row em vez de exigir a conversão manual de tuplos.

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 rodas fixas, por isso simdutf está sempre ligada estaticamente.
• Fixei inserções grandes DECIMAL em executemany().
• Corrigida a alternativa incorreta do tipo para parâmetros NULL.
• Corrigida a exceção nas operações de pickle e unpickle.
• Foi corrigido nextset() para que preservasse as mensagens PRINT entre diferentes conjuntos de resultados.
• Manipulação corrigida Row no executemany() caminho de queda de dados na execução.
• Corrigida a verificação de tipos do método fetch para ferramentas de análise estática.

mssql-python 1.8.0

Data de lançamento: maio de 2026

Enhancements

Suporte ActiveDirectoryMSI para cópia em massa

cursor.bulkcopy() suporta agora Authentication=ActiveDirectoryMSI para identidades geridas atribuídas pelo sistema e atribuídas pelo utilizador.

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 linha por chave de tipo string

Agora pode aceder aos valores das linhas 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 integrado

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

Correções de erros

• Foram corrigidos problemas de tempo de vida diferido do atributo connect na autenticação baseada em tokens.
• Corrigi a análise repetida de cadeia de ligação no caminho 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 expandida das rodas e melhorias de desempenho

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

Impacto no desempenho: A taxa de transferência da execução em lote melhora em ~15% em cargas de trabalho típicas devido a otimizações no caminho crítico do método execute().

Correções de erros

• Foram corrigidas falhas de início de sessão para que gerem exceções da DB-API mssql_python em vez de RuntimeError.
• Libertação estendida de GIL através do bloqueio de execução, busca, transação e chamadas de atributos de ligação ODBC.
• Falhas corrigidas executemany() quando os valores decimais mudam de sinal.
• Corrigi a decodificação inconsistente do CP1252 VARCHAR entre plataformas.
• Corrigidas as falhas de cursor.bulkcopy() para strings vazias nas colunas NVARCHAR(MAX) e VARCHAR(MAX).

MSSQL-Python 1.6.0

Data de lançamento: abril de 2026

Enhancements

Sanitização de cadeia de ligação baseada em analisador

Esta melhoria garante o processamento correto de caracteres especiais nos campos de palavra-passe e nos valores entre chavetas.

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 ligação passou de uma lógica baseada em expressões regulares para um processamento baseado em analisador sintático, para garantir o tratamento correto da sintaxe das cadeias de ligação ODBC.

Correções de erros

• Corrigi a libertação do GIL durante o bloqueio das operações de ligação e desconexão ODBC.
• Corrigi setinputsizes() crashes com SQL_DECIMAL e SQL_NUMERIC dicas.
• Corrigido o comportamento incorreto de fetchone() nos métodos de catálogo ODBC.
• Corrigidos 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.
• Foi adicionado um guarda de percurso de caminho para setup_logging(log_file_path=...).

MSSQL-Python 1.5.0

Data de lançamento: abril de 2026

Novas funcionalidades

Suporte de busca do Apache Arrow

Três novos métodos de cursor proporcionam recuperação de dados colunares de alto desempenho através da Interface de Dados Arrow C:

• cursor.arrow() retorna um pyarrow.Table completo.
• cursor.arrow_batch() devolve um único pyarrow.RecordBatch.
• cursor.arrow_reader() devolve um pyarrow.RecordBatchReader para transmissão em fluxo.

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 para o tipo sql_variant

O driver agora deteta sql_variant colunas em tempo de busca, resolve o seu tipo base subjacente e devolve valores Python corretamente digitados em vez de bytes brutos.

Suporte nativo à UUID

Uma nova definição native_uuid controla se as colunas UNIQUEIDENTIFIER são devolvidas como objetos uuid.UUID (por defeito) ou como cadeias de caracteres em maiúsculas compatíveis com pyodbc. Configure-o ao nível do módulo ou por ligaçã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, consulte Configuração do módulo.

Classe de linha de exportação pública

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

from mssql_python import Row

Correções de erros

• Corrigiu a deteção de falsos positivos ? dentro de identificadores colcheados, literais de string e comentários.
• Corrigida a associação de parâmetros NULL em colunas VARBINARY (já não gera erros de conversão implícita).
• Corrigido um problema em que valores datetime.time de ponto fixo perdiam os microssegundos em operações de ida e volta para colunas de TIME(1) a TIME(7).
• Corrigido o caminho de obtenção do Arrow para incluir corretamente segundos fracionais nas colunas TIME.
• Cópia em massa corrigida com métodos de autenticação do Microsoft Entra ID (campos de credenciais obsoletos já não causam erros de validação).
• Instâncias de credenciais Azure Identity armazenadas em cache ao 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

Novas funcionalidades

Suporte para cópia em massa

O carregamento de dados em massa de alto desempenho está agora disponível através 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_constraints, table_lock, keep_nulls, fire_triggers, e use_internal_transaction.

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

Improvements

• Otimizações de desempenho para grandes conjuntos de resultados.
• Redução do uso de memória durante operações em lote.
• Mensagens de erro melhoradas para falhas de cópia em massa.

mssql-python 1.3.0

Data de lançamento: janeiro de 2025

Novas funcionalidades

Classe de definiçõ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

Consulte a configuração do módulo para mais detalhes.

Improvements

• Melhor gestão do timeout da ligação durante o failover do SQL do Azure.
• Compatibilidade melhorada com Python 3.13.

mssql-python 1.2.0

Data de lançamento: novembro de 2024

Novas funcionalidades

Métodos de descoberta de esquemas

Novos métodos de cursor para exploração de metadados de bases 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()

Consulte Descoberta de esquemas para documentação completa.

Improvements

• Cache de metadados melhorado para consultas repetidas de esquema.
• Melhor gestão das colunas computadas nos columns() resultados.

mssql-python 1.1.0

Data de lançamento: setembro de 2024

Novas funcionalidades

Conversores de saída personalizados

Registar funções personalizadas para transformar os valores das colunas durante a obtenção:

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 gestão:

• 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

• Mensagens de erro melhores para falhas de conversão de tipos.
• Suporte para funções de conversor que retornam None.

mssql-python 1.0.0

Data de lançamento: julho de 2024

Lançamento inicial da disponibilidade geral

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

Principais características

• Arquitetura DDBC: Conectividade direta com base de dados sem necessidade de instalação de drivers ODBC.
• Conformidade com a DB-API 2.0: Interface padrão de base de dados para Python.
• Agrupamento de ligações: Gestão incorporada do agrupamento de ligações.
• Autenticação Microsoft Entra: Suporte total para autenticação baseada em identidade no Azure.
• Encriptação TLS: Ligações seguras com validação de certificados.

Características de ligação

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

Características 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 a tipos de dados

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

Suporte a transações

• Confirmação e reversão manuais.
• Modo de confirmação automática.
• Controlo do nível de isolamento.
• Deteção e manuseamento 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:

• São suportados os estilos de parâmetros ? (qmark) e %(name)s (pyformat). As suas consultas existentes ? funcionam sem alterações.
• Nenhum método callproc(). Utilize instruções EXECUTE em vez disso.
• Agrupamento de ligações integrado.
• Sem dependência de drivers ODBC externos.

De pymssql

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

Principais diferenças:

• Substitua os marcadores de parâmetros %s e %d por ? ou %(name)s.
• Use uma cadeia de ligação em vez de argumentos posicionais.
• Sem dependência do FreeTDS.
• Vários cursores concorrentes por ligação.
• Os objetos de linha com acesso a atributos substituem as_dict=True.

Entre versões mssql-python

Atualize o driver para obter novas funcionalidades e correções.

pip install --upgrade mssql-python

Verifique as notas de lançamento para ver se há alterações repentinas antes de atualizar os sistemas de produção.

Roteiro

Para funcionalidades futuras e o roteiro de desenvolvimento, consulte o repositório GitHub.

Conteúdo relacionado

• Driver mssql-python
• Ciclo de vida do suporte
• Installation
• Lançamentos do GitHub