Novidades no mssql-python

Este artigo lista o que mudou em cada versão do driver mssql-python, o mais recente primeiro. Cada secção cobre novas funcionalidades, alterações de comportamento e correções de bugs para uma versão.

Para as versões que a Microsoft suporta atualmente, veja Ciclo de vida de Suporte.

mssql-python 1.14.0

Data de lançamento: agosto de 2026

Enhancements

A deteção e ligação de parâmetros são executadas em código nativo

A deteção e a associação dos tipos de parâmetros são agora executadas numa única cadeia de processamento nativa, em vez de chamadas em Python por parâmetro. Esta alteração corrige um estrangulamento significativo de desempenho, com maiores melhorias na taxa de transferência de ponta a ponta em operações de maior dimensão, como inserções em massa. Não é necessária qualquer alteração na candidatura.

Correções de erros

O timeout argumento para connect() definir o tempo limite da consulta em vez do tempo limite da autenticação

O timeout argumento agora define SQL_ATTR_LOGIN_TIMEOUT e limita a tentativa de autenticação, que é o que o nome do argumento e a documentação descrevem. Nas versões anteriores, passou a ser o tempo limite da consulta por instrução, pelo que connect(timeout=30) não limitava quanto tempo uma tentativa de ligação podia demorar e interrompia as consultas após 30 segundos. O tempo limite da consulta por declaração continua disponível como a Connection.timeout propriedade.

Importante

Se tiver passado timeout a connect() para abortar consultas de execução prolongada, esse comportamento já não ocorre. Defina Connection.timeout em vez disso. O mesmo se aplica se recorreu a connect(timeout=) para aumentar o tempo limite de ligação que bulkcopy() usa para a sua ligação interna: defina Connection.timeout antes de criar o cursor.

Para mais informações, consulte Tempo limite da ligação.

bulkcopy() Rejeitado timeout=0

Um valor de 0 de 0 gerou um erro de validação, embora timeout signifique ausência de limite de tempo na API de cópia em massa subjacente. O método agora aceita 0 e desativa o tempo limite da operação. Valores negativos, não inteiros e booleanos continuam a ser rejeitados.

Para mais informações, consulte Cópia em massa.

A limpeza substituiu a exceção original de busca do Arrow

Quando uma obtenção a partir de um leitor Arrow falhava, a rotina de limpeza do controlador gerava um segundo erro que substituía o erro original, pelo que o código chamador via uma falha de limpeza em vez do motivo pelo qual a obtenção falhou. A limpeza agora verifica primeiro o estado do cursor e preserva a exceção original.

executemany() Os erros de conversão decimal incluíam valores de parâmetros

Uma falha na conversão decimal em executemany() comunicava o valor que causou o erro através da exceção encadeada, o que podia colocar dados de clientes nos registos da aplicação e nos sistemas de monitorização. O erro agora reporta apenas o índice de linhas, o índice da coluna e o tipo de valor.

Para obter mais informações, consulte Tratamento de erros.

Cópias em massa rejeitadas por tipos de Arrow View

bulkcopy_arrow() não podia consumir arrays Arrow View de comprimento variável, por isso as colunas string_view do Polars tinham primeiro de ser convertidas com DataFrame.to_arrow(). Os valores da Vista de Strings e os NULLs passam agora diretamente pela Interface de Dados Arrow C.

Para mais informações, veja integração com Polars.

O carregamento das extensões do Windows utilizava a arquitetura do CPU anfitrião

No Windows, o driver escolhia a sua extensão nativa com base no processador host em vez do interpretador em execução, por isso o Python x64 num host ARM64 carregava através de um caminho de reserva e escrevia avisos para o stdout. O carregador deriva agora a arquitetura do interpretador e assinala as alternativas como avisos.

mssql-python 1.13.0

Data de lançamento: agosto de 2026

Enhancements

Os binários do driver ODBC são fornecidos apenas em mssql-python-odbc

A versão 1.13.0 remove o fallback de libs/ do wheel mssql-python e declara mssql-python-odbc==18.6.2.1 em install_requires. O comando pip install mssql-python continua a gerar um controlador funcional. Instala mssql-python-odbc explicitamente quando instalares com --no-deps, ou a partir de um índice privado que não o espelhe.

Para obter mais informações, consulte Instalação.

Cópia em massa de fontes Apache Arrow

O novo cursor.bulkcopy_arrow() método carrega dados que já estão em formato Apache Arrow, sem converter cada linha em objetos Python primeiro. Ao passar uma origem Arrow para bulkcopy(), agora gera TypeError.

Para mais informações, consulte integração com Apache Arrow e cópia em massa.

token_provider parâmetro para credenciais do Microsoft Entra

A connect() função e a Connection classe aceitam um token_provider argumento, por isso pode passar um objeto credencial, como DefaultAzureCredential em vez de nomear um modo de autenticação na cadeia de ligação. O argumento é incompatível com a palavra-chave Authentication e com os tokens transmitidos através de attrs_before, e suporta apenas o âmbito da cloud comercial do Azure.

Para obter mais informações, consulte Autenticação do Microsoft Entra.

Agrupamento de ligações com reconhecimento da identidade

O conjunto de ligações agora separa as ligações com base na identidade Microsoft Entra. Em versões anteriores, o pool era indexado apenas pela cadeia de ligação, o que permitia fornecer uma ligação autenticada como um utilizador a um pedido feito por outro. O controlador também adquire um token apenas quando um pedido de ligação não encontra correspondência no pool e atualiza uma ligação do pool quando faltam menos de 5 minutos para o respetivo token expirar.

Para mais informações, consulte agrupamento de ligações.

Correções de erros

executemany() não inseriu nenhuma linha quando surgiam valores NULL após a primeira linha

Uma chamada executemany() que misturava valores numéricos não-NULL e NULL não inseria nenhuma linha nem levantava qualquer exceção, quando o primeiro NULL aparecia após a primeira linha. Este comportamento afetava parâmetros de tinyint, smallint, int e float . O driver inicializa agora os indicadores ODBC para cada parâmetro numérico de largura fixa antes da execução do array.

Um SQL_WVARCHAR conversor de saída transformou colunas que não eram cadeias de caracteres

Registar um único conversor de strings também transformava os valores int, decimal e date, porque o controlador recorria ao conversor SQL_WVARCHAR para qualquer coluna que não tivesse o seu próprio conversor. O driver agora usa esse recurso apenas quando o tipo de Python mapeado da coluna é str ou bytes.

Conversores de saída registados por código inteiro do tipo SQL nunca foram executados

Conversores registados com um código inteiro do tipo SQL, como SQL_DECIMAL, eram armazenados mas nunca invocados, porque o driver despachava apenas no tipo Python em cursor.description. O driver faz agora primeiro a seleção com base no código numérico inteiro, depois no tipo Python e, por fim, no recurso de fallback SQL_WVARCHAR.

Importante

Se registou conversores por código inteiro do tipo SQL numa versão anterior, esses conversores começam a funcionar quando atualiza. Reveja-os antes de implementar, porque os valores das colunas que antes passavam sem alterações agora são transformados.

Para mais informações, consulte Conversores de tipo personalizado.

Fechar um leitor Arrow não libertou o cursor do lado do servidor

Fechar um leitor Arrow deixava o cursor alocado no servidor e o elemento pai Cursor num estado inconsistente, porque cursor.arrow_reader() devolvia um pyarrow.RecordBatchReader bruto. O método devolve agora um wrapper cujo close() método liberta o cursor do lado do servidor e redefine o estado do cursor, e o wrapper funciona como gestor de contexto.

Para mais informações, consulte integração com o Apache Arrow.

Um cursor parcialmente inicializado gerou AttributeError em Cursor.__del__

Um cursor cujo inicializador falhou levantou a AttributeError como exceção não levantável durante a recolha de lixo.

Cursor.__init__ foi acionado antes de definir os atributos closed e hstmt, que __del__ depois tentou ler. O inicializador agora define ambos os atributos antes de qualquer código que possa ser levantado e __del__ protege a sua chamada de registo para que permaneça segura durante o encerramento do interpretador.

mssql-python 1.12.0

Data de lançamento: julho de 2026

Enhancements

Pacote complementar independente mssql-python-odbc

Os binários dos drivers ODBC são agora publicados separadamente como mssql-python-odbc, um pacote complementar apenas de dados fixado na versão 18.6.2. Não precisas de alterar código, porque pip install mssql-python instala o pacote complementar com ele. O carregador nativo prefere o pacote complementar e recorre aos binários agrupados dentro da mssql-python roda quando este não está presente.

Para obter mais informações, consulte Instalação.

Correções de erros

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

bulkcopy() passa a usar o tempo limite de ligação da sua ligação principal, que define com connect(..., timeout=<seconds>). Anteriormente, a ligação separada que a cópia em bloco abria usava um tempo limite de ligação de 15 segundos fixo no código, que não podia ser alterado a partir de Python. Uma ligação principal criada com timeout=0 continua a ter o valor predefinido de 15 segundos.

Para mais informações, consulte Cópia em massa.

cursor.bulkcopy() suporta colunas de tipos CLR definidas pelo utilizador

cursor.bulkcopy() anteriormente falhou com Protocol Error: Unsupported TDS type for bulk copy: 0xF0 para qualquer coluna de destino que utilizasse um tipo definido pelo utilizador do Common Language Runtime (CLR), incluindo os tipos incorporados geography, geometry e hierarchyid. O driver agora mapeia as colunas UDT do CLR para varbinary(max) no fio e transmite os bytes que forneces como carga útil do IBinarySerialize UDT. A correção é disponibilizada na versão mssql_py_core 0.1.7.

Para mais informações, veja Cópia em massa e Mapeamentos de tipos de dados.

mssql-python 1.11.0

Data de lançamento: julho de 2026

Enhancements

Semântica melhorada do gestor de contexto

with connection: agora compromete a transação quando o bloco sai limpo, e reverte-a quando uma exceção sai do bloco.

Para mais informações, consulte Gestão de Transações.

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() Agora suporta Authentication=ActiveDirectoryServicePrincipal, por isso podes inserir em massa com credenciais de principal de serviço.

Para mais informações, consulte Cópia em massa e autenticação Microsoft Entra.

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.

Para mais informações, consulte Cópia em massa e Objetos de linha.

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.

Para mais informações, consulte Cópia em massa e autenticação Microsoft Entra.

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.

Para mais informações, consulte objetos de linha.

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 inclui:

  • Jantes compatíveis com RHEL 8.
  • Restaurei as rodas do macOS Python 3.10universal2.
  • Melhoria no processamento de UTF-16 por meio de simdutf.
  • Caminho quente otimizado execute() .

Impacto no desempenho: A taxa de execução em lote melhora devido às otimizações do caminho quente no execute() método.

Para obter mais informações, consulte Instalação.

Correções de erros

  • Foram corrigidas falhas de autenticaçã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).

Note

A versão 1.7.0 foi retirada devido a problemas de publicação. Use a versão 1.7.1 ou posterior.

MSSQL-Python 1.6.0

Data de lançamento: abril de 2026

Enhancements

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

A sanitização das cadeias de ligação utiliza agora um analisador sintático em vez de expressões regulares, pelo que as cadeias de ligação que contêm caracteres especiais nos campos de palavra-passe e valores entre chavetas são corretamente analisadas.

Para obter mais informações, consulte Cadeias de conexão.

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.

Estes métodos não criam um objeto Python para cada valor. 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.

Note

sql_variant As colunas usam um caminho de busca em streaming, que pode ter um ligeiro impacto no desempenho em comparação com colunas do tipo fixo.

Para mais informações, consulte Mapeamentos de tipos de dados.

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 cada ligação.

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

Classe de linha de exportação pública

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

Para mais informações, consulte objetos de linha.

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: fevereiro de 2026

Novas funcionalidades

Suporte para cópia em massa

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

Para mais informações, consulte Cópia em massa.

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 2026

Novas funcionalidades

Classe de definições

Configure o comportamento ao nível do módulo através da nova classe Settings, que inclui a definição lowercase para nomes de colunas em cursor.description.

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

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: janeiro de 2026

Novas funcionalidades

Métodos de descoberta de esquemas

Novos métodos de cursor exploram metadados de bases de dados: tables(), columns(), primaryKeys(), foreignKeys(), procedures(), statistics(), , e getTypeInfo().

Para mais informações, consulte Descoberta de esquemas.

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: dezembro de 2025

Novas funcionalidades

Conversores de saída personalizados

Registar funções personalizadas para transformar os valores das colunas durante a busca, com add_output_converter(), get_output_converter(), remove_output_converter(), e clear_output_converters().

Para mais informações, consulte 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: novembro de 2025

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.

Para mais informações, consulte o driver mssql-python.

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

Mode Descrição
Autenticação do SQL Server Nome de utilizador e palavra-passe
Windows authentication Trusted_Connection
ActiveDirectoryDefault DefaultAzureCredential
ActiveDirectoryInteractive Início de sessão baseado em navegador
ActiveDirectoryDeviceCode Fluxo de código do dispositivo
ActiveDirectoryPassword Nome de utilizador e palavra-passe do Microsoft Entra (descontinuado; usa ROPC)
ActiveDirectoryMSI Identidade gerenciada
ActiveDirectoryServicePrincipal Serviço principal
Integrado no Active Directory Windows Kerberos

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

  • Last updated on