Utilizar o controlador mssql-odbc (Pré-visualização)

mssql-python carrega um dos dois fornecedores ODBC nativos:

Provider O que é Status
msodbcsql18 Microsoft ODBC Driver 18 para SQL Server, o driver C++ estabelecido Padrão, inalterado
mssql-odbc Um novo driver ODBC escrito em Rust Pré-visualização, adesão voluntária

Este artigo aborda mssql-odbca 0.3.0, a versão atualmente usada por mssql-python, e no que difere de msodbcsql18.

Note

mssql-odbc está em desenvolvimento e validação ativos. Ainda não é um substituto completo para o Microsoft ODBC Driver 18. Mantém msodbcsql18 como o teu padrão de produção por agora. A equipa de desenvolvimento planeia colmatar as lacunas de pré-visualização nos próximos lançamentos, exceto pelas exclusões intencionais explicitamente identificadas neste artigo.

Availability

O driver é enviado dentro do pacote mssql-python-rs como wheels pré-compiladas para CPython 3.10 e posteriores:

Platform Architectures
Windows x64; ARM64 no CPython 3.11+
macOS universal2 (x86_64 + arm64), macOS 15 ou posterior
Linux (glibc) x86_64, aarch64 — manylinux_2_28 e manylinux_2_34
Linux (musl) x86_64, aarch64 — musllinux_1_2

Ativar o controlador

O mssql-python pacote depende de mssql-python-rs, por isso uma instalação normal traz consigo o driver Rust:

pip install mssql-python

Se instalares com --no-deps ou a partir de um índice privado, instala mssql-python-rs também explicitamente.

Selecione o provedor antes da primeira conexão, quer através de uma variável de ambiente:

PowerShell::

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash ou Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

ou do Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Ligue usando a cadeia de ligação existente da sua aplicação. Mantenha a validação de certificados ativada (Encrypt=yes;TrustServerCertificate=no). Para autenticação e configuração de certificados, veja Cadeias de ligação e Encriptação e certificados.

connection = mssql_python.connect(connection_string)

O controlador aplica estas regras ao escolher o fornecedor:

  • A MSSQL_PYTHON_NATIVE_PROVIDER variável ambiente tem precedência sobre native_provider. Uma atribuição de atributos conflituosa emite RuntimeWarning.
  • A seleção torna-se fixa após a validação da cadeia de conexão e imediatamente antes da construção da conexão nativa. Uma falha de ligação subsequente não elimina a seleção. Um erro anterior de análise da cadeia de ligação ou a falta do pacote do fornecedor não resolve o problema de seleção. Depois de a seleção ficar fixa, mudar native_provider para outro fornecedor emite RuntimeWarning e não tem efeito. Reinicie o processo para mudar de fornecedor.
  • Um nome de fornecedor não reconhecido gera ValueError; o controlador não recorre ao fornecedor padrão. Um nome desconhecido atribuído a native_provider gera imediatamente um erro. Um nome desconhecido na variável de ambiente gera um erro quando tentas ligar-te.
  • Defina native_provider para None para limpar a seleção de atributos antes de ficar fixa. A variável ambiente continua a ter prioridade.

Ligue mssql_python.get_native_provider_info() para verificar o fornecedor selecionado, a fonte de seleção e se a seleção está fixa. Antes de ligar, isto reporta a seleção, não a prova de que o driver nativo carregou com sucesso.

Para voltar atrás, defina a variável para msodbcsql18, ou remova a definição e remova qualquer atribuição de native_provider do seu código (ou defina-a para "msodbcsql18"). Depois, reinicie o processo.

O que funciona hoje

O mssql-odbc driver implementa todas as funções ODBC que mssql-python chama, pelo que a maioria das aplicações pode mudar de fornecedor sem alterações de código. Consulte Problemas conhecidos para ver as restantes diferenças.

Area Notes
Ciclo de vida da ligação Conectar, close(), with blocos, tempo de espera de login, diagnóstico e alteração da base de dados atual. As definições da cadeia de ligação incluem ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, e ConnectRetryCount / ConnectRetryInterval (resiliência da ligação inativa).
Authentication autenticação SQL (UID / PWD); autenticação do Windows (Trusted_Connection=Yes, usando SSPI no Windows ou Kerberos no Linux e macOS); e interativa do Microsoft Entra, código do dispositivo, principal de serviço, identidade gerida, credencial predefinida e token de acesso. O integrado no Entra e a autenticação por palavra-passe não são suportados; ver Problemas conhecidos.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate e ServerCertificate.
Execução da consulta Execução direta e preparada, reutilização de planos preparados, parâmetros qmark e a conversão mssql-python efetuada por pyformat.
Sintaxe de escape ODBC Função, data/hora, junção externa, GUID, LIKE ... {escape ...}, intervalo e formas de escape {encrypt ...}.
Procedimentos armazenados Execute-os com T-SQL ou sintaxe posicional {call ...} através de execute(), leia conjuntos de resultados e avance com nextset().
Parâmetros de entrada Parâmetros escalares, SQL NULL, setinputsizes(), e parâmetros mistos regulares/streamed.
Parâmetros grandes Grandes parâmetros de texto e binários fluem para o servidor pelo caminho de ligação comum; As limitações dos parâmetros XML e UDT estão listadas abaixo.
executemany() Agrupado com arrays de parâmetros ODBC. As linhas que contêm valores transmitidos passam para execução linha a linha.
Obtenção de linhas fetchone(), fetchmany(), fetchall(), iteração, fetchval(), conversão tipada e streaming de texto/binário em grande escala.
Obter setas arrow_batch(), arrow()e arrow_reader(). Requer pyarrow.
Vários conjuntos de resultados nextset(), incluindo resultados produzidos por arrays de parâmetros.
Transações Autocommit, commit, rollback, o commit automático (ou rollback, caso tenha escapado um erro) que ocorre quando um bloco with connect(...) termina, e os níveis de read-uncommitted, read-committed, repeatable-read, serializable e snapshot isolation.
Tempo limite da consulta Defina Connection.timeout (em segundos) para limitar as instruções executadas pelos cursores dessa ligação; a expiração gera OperationalError. 0 significa que não há tempo limite. Esta definição é separada do tempo limite de login passado como connect(timeout=...).
Agrupamento de conexões O pool incorporadomssql-python, incluindo o reset da ligação no checkout e pools separados por identidade Microsoft Entra.
APIs de metadados tables(), columns(), primaryKeys(), foreignKeys(), statistics(), rowIdColumns(), rowVerColumns(), procedures(), e getTypeInfo().
Codificação e conversores Codificação padrão de caracteres longos e conversores de saída. A descodificação personalizada de caracteres estreitos e a conversão de parâmetros não-Unicode têm limitações listadas em Problemas conhecidos.

Tipos de dados

Podes ler todos os tipos de dados do SQL Server, e o driver suporta todos os tipos de parâmetros que mssql-python associa. O driver retorna xml, json, e vector valores como str (vector como array JSON), e tipos CLR como geometry, geography, e hierarchyid como bytes. Para outros mapeamentos em Python, veja Mapeamentos de tipos de dados. Para limitações específicas de cada tipo veja Problemas conhecidos.

Problemas conhecidos

Verifique estas diferenças antes de migrar uma carga de trabalho de msodbcsql18.

Issue Details Workaround
Autenticação integrada do Microsoft Entra Authentication=ActiveDirectoryIntegrated não é suportado. A autenticação do Windows (Trusted_Connection=Yes) não é afetada. Utilize outro método do Microsoft Entra ou mantenha msodbcsql18.
Autenticação de senha do Microsoft Entra Authentication=ActiveDirectoryPassword não é suportado, e o suporte não está previsto porque este método não consegue satisfazer o MFA. A autenticação SQL (UID / PWD) não é afetada. Utilize outro método do Microsoft Entra, como um principal de serviço, identidade gerida ou token de acesso.
attrs_before configurações Autenticação, intenção de aplicação e failover multi-sub-redes não podem ser definidos como atributos numéricos. Atributos da instrução SQL, exceto o tempo de espera da consulta, são rejeitados. Utilize as palavras-chave equivalentes à cadeia de conexão.
Tempo limite da operação de conexão set_attr(SQL_ATTR_CONNECTION_TIMEOUT, ...) aceita e armazena o valor, mas não impõe um timeout na versão 0.3.0. Use connect(timeout=...) para login e Connection.timeout para extratos; nenhuma delas é um prazo geral para operações de ligação.
Hosts com múltiplos endereços msodbcsql18 ativa o Transparent Network IP Resolution (TNIR) por defeito; mssql-odbc não o suporta. mssql-python rejeita a TransparentNetworkIPResolution palavra-chave connection-string com qualquer um dos fornecedores. Sem MultiSubnetFailover=Yes, os endereços são testados um de cada vez, pelo que um endereço inacessível pode atrasar a ligação. O cache DNS assistido pelo servidor e o encaminhamento melhorado não são negociados. Defina MultiSubnetFailover=Yes para ouvintes de grupos de disponibilidade e outros hosts com múltiplos endereços.
Falhas de DNS transitórias Se uma consulta DNS falhar, o driver não recorre ao último endereço bem-sucedido. (#457) Tente novamente a conexão.
Classificação dos dados Os metadados de classificação de sensibilidade não estão disponíveis, e SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) não são suportados. Consultar sys.sensitivity_classifications.
Multithreading O uso multithread não foi validado. Mantenha msodbcsql18 para cargas de trabalho multithreaded.
fork() Depois de ligar No Linux, um processo bifurcado após a ligação do pai pode bloquear quando usa o driver, mesmo com uma nova ligação. Com o pooling ativado, o pai também pode deixar de responder. (#566) Use o método de arranque spawn e ligue dentro de cada worker.
Cancelamento de uma declaração corrente Uma consulta ou busca em execução não pode ser interrompida. Por exemplo, fechar um(a) arrow_reader() não impede uma leitura em curso noutra thread. Utilize Connection.timeout para limitar instruções de longa duração.
Resultados não lidos Fechar um cursor ou executar outra instrução lê e descarta os resultados restantes em vez de os cancelar, o que pode ser lento. Fechar um cursor que usou uma instrução preparada ignora Connection.timeout e pode bloquear se o servidor deixar de responder. (#546) Busca apenas as linhas que precisas, por exemplo com TOP.
Parâmetros Large xml e UDT Os valores ligados como SQL_SS_XML ou SQL_SS_UDT através de setinputsizes() são armazenados em buffer na memória em vez de serem transmitidos em streaming. Associe xml valores como cadeias comuns.
Valores vazios image Um valor vazio e não nulo do SQL Server image é devolvido como None em vez de b"". Leia CAST(image_column AS varbinary(max)), ou use msodbcsql18 quando a distinção vazio/NULO importa.
Parâmetros de cadeia não-Unicode As strings associadas como char / varchar até setinputsizes() podem ser codificadas incorretamente para as páginas de código 437, 850 e colações UTF-8. Usa a associação predefinida de cadeia.
Decodificação de páginas de código legadas no Windows Com setdecoding(SQL_CHAR, encoding="cp1252") ou outra página de código legada, o texto pode ser decodificado incorretamente ou devolvido como bytes, porque o driver devolve char / varchar dados como UTF-8. Utilize o padrão: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME devolve a string de ligação UID, não o utilizador da base de dados. Fica vazio quando nenhum UID chega ao driver. Alguns valores de capacidade e limites baseados no tamanho dos pacotes diferem de msodbcsql18. Utilize SELECT USER_NAME() para o utilizador da base de dados.
Falhas por falta de memória Algumas falhas de alocação de drivers terminam o processo Python em vez de lançar MemoryError. (#484) Limite o tamanho dos valores que envia e obtém.
Desempenho de leitura de valores grandes Num benchmark, as leituras em chunks dos varchar(max) / nvarchar(max) dados foram ligeiramente mais lentas do que com msodbcsql18. (#473) Compare a carga de trabalho.

Esta lista não é exaustiva.

Comunicar problemas

Se encontrar um bug, selecione msodbcsql18, reinicie o processo e verifique se o comportamento ainda ocorre. Também remova qualquer atribuição conflituosa de provider do lado do Python. A comparação ajuda a isolar o problema; por si só, não prova qual é a sua causa. Inclua a saída de mssql_python.get_native_provider_info(), a sua plataforma e o SQL que falhou ou a mensagem de erro:

Para diagnósticos do driver Rust, defina estas variáveis antes de iniciar o Python e reproduza o problema com mssql-odbc selecionado. Por exemplo, no PowerShell:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "warn,mssqlodbc=debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"

MSSQL_TDS_TRACE Ativa o rastreamento, MSSQL_TDS_TRACE_LEVEL seleciona o filtro de registo e MSSQL_TDS_TRACE_DIR escreve ficheiros por processo em vez de stderr. Reinicie o Python depois de alterar estas definições. Os rastreios podem conter texto SQL e valores de parâmetros. Revise e oculte dados sensíveis antes de partilhar excertos relevantes e desative o rastreio após o diagnóstico.

Conteúdo relacionado

  • Última atualização a