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.18.0

Data de lançamento: 18 de novembro de 2026

Enhancements

Nomes de aplicações personalizados

Defina APP ou Application Name na sua cadeia de ligação para identificar a sua carga de trabalho na monitorização do lado do servidor. Por exemplo, APP=orders-api aparece como MSSQL-Python|orders-api em APP_NAME() e sys.dm_exec_sessions.program_name. As ligações síncronas, o caminho assíncrono nativo experimental e a cópia em massa enviam todas o mesmo nome.

O nome padrão é MSSQL-Python. Antes desta versão, os caminhos nativos assíncronos e de cópia em massa enviavam mssql-python. Se um filtro de monitorização corresponder mssql-python exatamente, atualize-o.

Para mais informações, consulte Application name.

Obtenção e conversão de linhas mais rápidas

Padrões comuns de busca fazem menos trabalho repetido:

  • dict(row._mapping) Já não reconstrói a pesquisa pelo nome da coluna cada vez que o chama.
  • fetchone(), fetchmany(1), fetchval(), e a iteração sobre um cursor reutilizam a configuração da obtenção anterior nesse cursor.
  • fetchall() E fetchmany() com conversores de saída saltam uma conversão interna de texto antes de chamarem o seu conversor. Os conversores continuam a funcionar na mesma ordem e recebem SQL NULL da mesma forma.
  • Chamadas repetidas de fetchmany(1) em resultados de texto mantêm a sua configuração após cada linha. O controlador ainda não lê as linhas à frente.

Quando um fetch não consegue usar o caminho mais rápido, o driver usa o código Python existente. Não é necessária qualquer alteração da aplicação.

Consultas parametrizadas repetidas mais rápidas

O driver converte pyformat marcadores de posição numa única passada e armazena o resultado em cache, pelo que executar a mesma instrução novamente salta a conversão. Quando executa novamente a mesma instrução no mesmo cursor, e cada parâmetro tem o mesmo tipo e tamanho da execução anterior, o driver reutiliza a instrução preparada em vez de a preparar novamente.

Para mais informações, consulte Criar consultas parametrizadas.

Runtime do Rust atualizado

O driver necessita de mssql-python-rs==0.5.0. Esta versão gasta menos tempo a processar texto SQL e a enviar parâmetros quando utiliza o fornecedor de opt-in mssql-odbc ou o caminho assíncrono nativo.

O provedor mssql-odbc aplica agora SQL_ATTR_CONNECTION_TIMEOUT ao pedido que reinicia uma ligação agrupada. Antes desta versão, o timeout aplicava-se apenas à limpeza após um pedido cancelado.

No macOS, Encrypt=Strict as ligações via TCP que passam pelo runtime Rust, como o mssql-odbc fornecedor e o caminho assíncrono nativo, usam agora o Network.framework da Apple para TLS. Estas ligações podem negociar TLS 1.3. Outras Encrypt configurações não mudam.

O mssql-odbc provider suporta agora parâmetros com valor de tabela ao nível ODBC, incluindo NULL células e valores de célula enviados através do streaming de dados no momento da execução. O mssql-python cursor não tem uma API para passar parâmetros com valor de tabela.

O msodbcsql18 provedor mantém-se como predefinido. Para mais informações, consulte Utilizar o driver mssql-odbc (Pré-visualização) e os requisitos de dependência.

Correções de erros

Fecho de ligação agrupada do Synapse

Fechar uma ligação agrupada com autocommit ativado já não falha nos pools SQL dedicados Azure Synapse. Quando o driver devolveu a ligação ao pool, enviou SET TRANSACTION ISOLATION LEVEL READ COMMITTED, que os pools SQL dedicados não suportam. O controlador já não envia essa instrução.

Tempos de espera de checkout em pool explícitos

Se definir SQL_ATTR_CONNECTION_TIMEOUT para um valor inferior ao tempo limite de início de sessão, a verificação que é executada antes de o agrupamento reutilizar uma ligação mantém agora o seu valor. Antes desta correção, a verificação substituiu-a pelo tempo limite de login mais longo. Depois de a verificação ser bem-sucedida, o driver restaura o seu valor original.

Para mais informações, consulte Verificações de estado da ligação.

Encerramento do leitor Arrow

Antes desta correção, fechar um leitor Arrow de outra thread enviava um pedido de cancelamento mesmo quando nenhum fetch estava a funcionar. Esse pedido fechou o cursor, e o próximo fetch da thread de leitura gerou ProgrammingError. Agora close() cancela apenas um fetch que está em execução e retorna apenas depois de o fetch parar. Um leitor de uma consulta anterior não pode fechar ou ler um resultado posterior no mesmo cursor. Erros que o encerramento não causou continuam a chegar ao teu código.

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

Tratamento do marcador de posição Pyformat

O driver já não substitui texto %(name)s dentro de literais de cadeia, identificadores entre aspas ou entre colchetes, ou comentários. Um sinal de percentagem escapado (%%) passa a ser sempre um único % e deixa de causar incompatibilidade entre marcadores de posição e valores de parâmetros.

Correções em tempo de execução do Rust

Estas correções estão na mssql-python-rs versão 0.5.0. Aplicam-se ao mssql-odbc provedor e ao caminho assíncrono nativo.

  • O tempo de espera da ligação limita agora cada pedido ao nível da ligação, incluindo os pedidos que verificam uma ligação em pool antes da reutilização.
  • As instruções preparadas deixam de falhar quando o driver liberta um descritor de instrução ao mesmo tempo que invalida um plano preparado.
  • O driver agora limpa os identificadores de instruções preparadas após um pedido cancelado.
  • Alterar o nível de isolamento da transação já não descarta o estado válido do cursor.
  • Abrir uma ligação num thread com uma pequena pilha já não transborda a pilha.
  • Um comprimento sobredimensionado num valor escalar sql_variant gera agora um erro de protocolo. Antes desta correção, o comprimento sofria overflow e os bytes não lidos eram deixados no fluxo. Os valores válidos não são afetados.

No mssql-odbc fornecedor, os valores enviados com o streaming de dados em execução passam agora a ser colocados nas posições dos respetivos parâmetros associados. Antes desta correção, o provider movia-os depois dos outros parâmetros. Quando executou parâmetros em fluxo e depois um array de parâmetros na mesma instrução preparada, os valores podiam atingir parâmetros errados.

Para os detalhes completos da versão, consulte a versão mssql-python 1.18.0.

mssql-python 1.17.0

Data de lançamento: 2 de novembro de 2026

Enhancements

Provedor nativo de pré-visualização atualizado

O fornecedor opt-in mssql-odbc na versão 0.4.0 de mssql-python-rs adiciona autenticação integrada com o Microsoft Entra ID, cancelamento de instruções em execução e streaming de parâmetros XML (Extensible Markup Language) de grandes dimensões e de parâmetros de tipos definidos pelo utilizador também de grandes dimensões. Também negocia cache do Sistema de Nomes de Domínio (DNS) assistido por servidor e encaminhamento melhorado quando o servidor os suporta. O seu comportamento padrão de failover multi-sub-redes permite agora tentativas de ligação paralelas para conexões aplicáveis ao Protocolo de Controlo de Transmissão (TCP).

O fornecedor permanece em preview. msodbcsql18 continua a ser o provedor predefinido. Para capacidades e limitações atuais, consulte Utilização do driver mssql-odbc (Pré-visualização).

Reutilização mais rápida do pool de ligações

O driver ignora a limpeza redundante quando pode confirmar que uma ligação em pool já está limpa. Ligações com trabalho não comprometido ou alteração do estado da sessão ainda precisam de limpeza antes de ser reutilizadas. O checkout ainda valida a ligação com uma ida e volta ao servidor.

Para mais informações, consulte Ciclo de vida da conexão.

Correções de erros

Cópia em massa após atualizações de pacotes

O driver necessita de mssql-python-rs==0.4.0. O runtime atualizado corrige falhas de cópia em massa causadas pelo layout nativo do módulo após uma atualização. A instalação ou atualização de mssql-python com dependências instala automaticamente o runtime correspondente.

Para mais informações, consulte Requisitos de Dependência.

Cópia em massa Unicode, nomes de destinos e precisão de data-hora

bulkcopy() e bulkcopy_arrow() tratam o texto UTF-8 corretamente e corrigem a perda de frações de segundos ao carregar valores datetime2. Por exemplo, os carimbos temporais de nanossegundos do Arrow podem reter o sétimo dígito fracionário num destino datetime2(7), em vez de serem truncados para microssegundos. Os objetos Python datetime continuam limitados à precisão de microssegundos.

Um nome de destino com mais de três partes gera RuntimeError agora durante a consulta de metadados, antes de as linhas serem enviadas, em vez de chegar a um erro do lado do servidor.

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

Recuperação limitada de ligações em pool não responsivas

Com o fornecedor predefinido msodbcsql18, o checkout aplica um timeout temporário nativo para a operação de conexão durante a validação do pool. Utiliza um tempo limite positivo de login, ou 15 segundos se o tempo limite for zero ou não especificado. Após a falha da validação, o driver descarta essa conexão e tenta um início de sessão de substituição em vez de validar cada conexão inativa restante.

Múltiplas operações de validação, limpeza e um login substituto podem exceder o timeout temporário. Não é uma validação total nem connect() um prazo final. A aquisição de tokens Microsoft Entra ID não está limitada pelo tempo limite de login.

O fornecedor de opt-in mssql-odbc não garante os mesmos limites de validação. Para mais informações, consulte Verificações de saúde da ligação e limitações do fornecedor nativo.

Contagens precisas de linhas após nextset()

Cursor.nextset() atualiza rowcount para cada resultado subsequente de modificação de dados num lote, procedimento armazenado ou ciclo em Transact-SQL (T-SQL). Um resultado que produz uma linha começa com rowcount == -1 antes de buscar. As versões anteriores mantinham a contagem da primeira instrução ao avançar para outro resultado.

Para mais informações, consulte Número de linhas.

Compatibilidade de Timestamp() da DB-API

O microsecond argumento para Timestamp() é opcional e por defeito é zero. A chamada de seis argumentos Timestamp(year, month, day, hour, minute, second) funciona agora conforme especificado pelo PEP 249.

Para mais informações, consulte DB-API construtor de carimbo temporal.

Para os detalhes completos da atualização, consulte a versão mssql-python 1.17.0.

mssql-python 1.16.0

Data de lançamento: outubro de 2026

Enhancements

Suporte a Python 3.15

O Python Package Index (PyPI) tem agora wheels para Python 3.15 no Windows, Linux e macOS. A versão inclui 41 wheels que cobrem Python 3.10 a 3.15.

Para mais informações, consulte Ciclo de vida do Suporte.

Pacotes Conda

O driver é agora publicado no microsoft canal no Anaconda.org. O pacote conda é um pacote autónomo que inclui os binários do controlador ODBC e o runtime Rust:

conda install -c microsoft mssql-python

No Linux, o pacote conda requer a glibc 2.34 e versões posteriores. No macOS, requer o macOS 15 e versões posteriores. Para a lista completa de plataformas e requisitos, consulte Instalação a partir do conda.

Fornecedor nativo opt-in mssql-odbc

Agora pode selecionar um fornecedor ODBC baseado em Rust chamado mssql-odbc. O Microsoft ODBC Driver 18 (msodbcsql18) mantém-se como padrão. Selecione o provedor antes da primeira ligação com a MSSQL_PYTHON_NATIVE_PROVIDER variável de ambiente ou o atributo mssql_python.native_provider. O código da tua aplicação não muda.

Para mais informações, consulte Utilização do driver mssql-odbc (Pré-visualização).

Acesso à linha ao estilo de dicionário com row._mapping

Cada um Row tem agora uma propriedade _mapping apenas de leitura que associa os nomes das colunas aos valores. Use dict(row._mapping) para converter uma linha num dicionário sem combinar valores com cursor.description.

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

O runtime Rust é incluído no mssql-python-rs pacote

O runtime de Rust que alimenta cópias em massa agora é enviado num pacote separado, com versão correspondente mssql-python-rs, em vez de dentro da mssql-python wheel. O comando pip install mssql-python instala-o automaticamente. A versão 0.3.0 do pacote utiliza wheels da interface binária estável de aplicação CPython (ABI), pelo que cada wheel serve versões Python 3.10 e posteriores.

Para mais informações, consulte Requisitos de Dependência.

Pacote complementar atualizado mssql-python-odbc

O driver agora requer mssql-python-odbc a versão 18.6.2.2. As wheels do Linux são divididas por biblioteca C, por isso os ambientes glibc e musl (Alpine Linux) instalam apenas os binários correspondentes do controlador ODBC 18.6.

Operações de obtenção mais rápidas

As operações de busca passam menos tempo em Python:

  • fetchmany() e fetchall() construir Row objetos no caminho nativo de busca quando a ligação não tem conversores de saída e não são convertidos valores de uniqueidentifier para cadeias de caracteres.
  • os valores date, time e datetime são construídos com menos sobrecarga.
  • Os metadados da coluna são reutilizados para o conjunto de resultados atual em vez de serem descritos novamente em cada busca.
  • Obtenções limpas ignoram exames diagnósticos repetidos.
  • Índices inteiros, como row[0], utilizam um caminho de pesquisa direta.
  • fetchval() omite as chamadas de registo de depuração quando o registo de depuração está desativado.

Não é necessária qualquer alteração na candidatura.

Correções de erros

Os processos do Windows podem falhar durante o encerramento

O driver podia libertar o seu handle de ambiente ODBC após a finalização do Python, o que podia provocar uma violação de acesso quando um processo Windows saísse. O identificador já não é libertado após a finalização.

Os caracteres iniciais U+FEFF e U+FFFE foram eliminados do texto obtido

Quando uma cadeia obtida começava com U+FEFF ou U+FFFE, o driver tratava esse ponto de código como uma marca de ordem de bytes e removia-o. O driver agora devolve o valor completo para tipos limitados como nvarchar(n) e varchar(n). Tipos de grande valor como nvarchar(max) não são cobertos por esta correção: um U+FEFF inicial continua a ser removido, e um U+FFFE inicial faz com que o valor seja decodificado com a ordem errada dos bytes.

As ligações em pool podiam manter uma transação vazia aberta

Uma ligação em pool pode regressar ao pool com uma transação aberta e vazia ou com o autocommit desligado. O driver agora reverte a ligação física e ativa o autocommit antes de devolver a ligação ao pool. Se essa limpeza falhar, o driver descarta a ligação em vez de a reutilizá-la no pool.

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

Os parâmetros de tipo definidos pelo utilizador não tinham metadados de tipo

Parâmetros que declara como tipos definidos pelo utilizador do SQL Server com setinputsizes() e SQL_SS_UDT (-151), como geography e geometry, agora obtêm os seus metadados de tipo do servidor antes da associação. A correção abrange os casos de valores None e de instruções reutilizadas para parâmetros declarados. Um None não declarado passado para uma coluna de tipo definido pelo utilizador numa instrução reutilizada continua a falhar.

setencoding() Ignorou pedidos não suportados sem aviso

O driver envia sempre instruções Transact-SQL (T-SQL) e parâmetros str como UTF-16LE. Ao chamar setencoding() com uma codificação ou ctype diferente de UTF-16LE, com SQL_WCHAR, é agora emitido UserWarning em vez de ser silenciosamente ignorado. Chamar setencoding() sem argumentos restaura os valores predefinidos sem aviso.

Para mais informações, consulte Gerir ligações.

O registo nativo podia interpretar metadados como diretivas de formato

Quando o registo nativo estava ativado, valores fornecidos pelo servidor, como metadados da coluna Arrow, eram passados ao logger nativo como strings de formato. O driver agora regista esses valores como texto literal.

A cópia em massa não colocava consistentemente aspas nos identificadores de destino

A cópia em massa agora coloca entre aspas e escapa de forma consistente os nomes das tabelas de destino, os nomes das colunas e as colações. Os nomes multipartes e os nomes entre aspas com parênteses retos que contêm espaços ou caracteres ] funcionam. Um nome malformado, como um colchete não fechado ou um nome de tabela em falta, gera um erro antes de quaisquer linhas serem enviadas.

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

mssql-python 1.15.0

Data de lançamento: setembro de 2026

Enhancements

setinputsizes() O tratamento de parâmetros é executado em código nativo

O processamento de parâmetros para setinputsizes() passa agora pelo pipeline de execução nativo em C++ em vez de chamadas em Python por parâmetro. Instruções extensas, em lote, parametrizadas e executadas frequentemente despendem menos tempo no processamento de parâmetros no lado do Python. Não é necessária qualquer alteração na candidatura.

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

Binary() aceita memoryview objetos

Binary() aceita agora um(a) memoryview como entrada binária, por isso pode passar uma vista zero-cópia de um buffer sem o converter para bytes primeiro.

Para mais informações, veja Dados binários.

Constantes do tipo SQL Server estão disponíveis no mssql_python módulo

As constantes de tipo SQL Server são agora expostas diretamente a partir do mssql_python módulo, o que as torna mais fáceis de encontrar quando declaras tipos de parâmetros ou metadados de tipos de leitura.

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

Correções de erros

O registo simultâneo pode bloquear o processo

As rotinas nativas de registo adquiriam o GIL e os mutexes internos numa ordem inconsistente, pelo que uma aplicação multithread com o registo do controlador ativado podia entrar em impasse. A ordem das fechaduras foi corrigida.

Os volantes ARM64 do Windows não incluíam um núcleo nativo ARM64

A roda ARM64 do Windows não oferecia um binário ARM64 mssql_py_core correspondente, o que afetou a cópia em massa nessa plataforma. A wheel passa agora a incluir a compilação ARM64.

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

As DLLs do Windows agrupadas dependiam do percurso de pesquisa de processos

As DLLs de driver e autenticação que são enviadas no pacote são agora carregadas a partir de diretórios locais de pacotes. As dependências nativas resolvem-se sem depender da configuração do caminho de pesquisa a nível de processo, o que era pouco fiável em alguns ambientes de implementação.

Decimal Os parâmetros eram associados de forma diferente consoante o seu valor

Um parâmetro Decimal é agora associado como SQL_NUMERIC, independentemente do respetivo valor em tempo de execução, pelo que a tipagem decimal do parâmetro se mantém inalterada entre valores e percursos de execução.

Para mais informações, consulte Dados decimais e monetários.

A ligação de parâmetros utilizou identificadores de tipo ODBC 2.x obsoletos

Os parâmetros digitados usam agora identificadores de tipo ODBC 3.x em vez dos seus equivalentes ODBC 2.x, o que evita descorrespondências com as configurações atuais de drivers.

Connection.getinfo(SQL_DATABASE_NAME) retornou um valor não descodificado

O valor devolvido para SQL_DATABASE_NAME é agora decodificado, por isso o nome da base de dados aparece como texto em Python.

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

A limpeza do cursor crashou no desligamento do interpretador

Uma conexão que mantinha cursores em estados mistos no ciclo de vida limpava-os numa ordem que podia fazer falhar o processo quando parte dessa operação de limpeza era executada durante o encerramento do interpretador. O encerramento termina agora normalmente.

Para mais informações, consulte Gestão do cursor.

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() rejeitou 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() 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 Polars string_view tinham de ser convertidas com DataFrame.to_arrow() primeiro. 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_providerparâmetro para credenciais 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() inseriu zero linhas quando os NULLs apareceram 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 levantado 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() agora utiliza o tempo de espera de ligação da ligação principal

bulkcopy() Agora utiliza o tempo de espera 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.

São suportadas colunas de tipo definido pelo utilizador CLR

cursor.bulkcopy() falhava anteriormente com Protocol Error: Unsupported TDS type for bulk copy: 0xF0 qualquer coluna de destino que utilizasse um tipo definido pelo utilizador no runtime de linguagem comum (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 confirma a transação quando o bloco termina sem erros, e reverte-a quando ocorre uma exceção no 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() suporta agora Authentication=ActiveDirectoryServicePrincipal, por isso pode inserir em massa com credenciais do 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() agora aceita objetos Row obtidos diretamente em vez de exigir conversão manual de tuplas.

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() passa a suportar Authentication=ActiveDirectoryMSI para identidades geridas atribuídas pelo sistema e 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 graças às otimizações do percurso crítico no método execute().

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 completo pyarrow.Table.
  • cursor.arrow_batch() devolve um único pyarrow.RecordBatch.
  • cursor.arrow_reader() retorna um pyarrow.RecordBatchReader para streaming.

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 utilizam um caminho de rastreamento em streaming, que pode ter um ligeiro impacto no desempenho comparado com colunas de 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 à base de dados sem necessidade de instalação do driver ODBC.
  • Conformidade com a DB-API 2.0: Interface padrão de base de dados em Python.
  • Agrupamento de ligações: Gestão integrada do pool de ligações.
  • Autenticação Microsoft Entra: Suporte completo para autenticação baseada em identidade 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.