Usando o driver mssql-odbc (Prévia)

mssql-python carrega um dos dois provedores ODBC nativos:

Provider O que é Status
msodbcsql18 Driver ODBC Microsoft 18 para SQL Server, o driver C++ estabelecido Padrão, inalterado
mssql-odbc Um novo driver ODBC escrito em Rust Visualização, opt-in

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

Note

mssql-odbc está em desenvolvimento e validação ativas. Ainda não é um substituto completo para o Driver ODBC 18 da Microsoft. Mantenha msodbcsql18 como seu padrão de produção por enquanto. A equipe de desenvolvimento planeja fechar as lacunas da versão prévia em lançamentos futuros, exceto por exclusões intencionais explicitamente identificadas neste artigo.

Availability

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

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

Habilitando o driver

O mssql-python pacote depende de mssql-python-rs, então uma instalação normal traz o driver Rust junto:

pip install mssql-python

Se você instalar com --no-deps ou a partir de um índice privado, instale mssql-python-rs explicitamente também.

Selecione o provedor antes da primeira conexão, seja com uma variável de ambiente:

PowerShell:

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Bash ou Zsh:

export MSSQL_PYTHON_NATIVE_PROVIDER=mssql-odbc

ou a partir do Python:

import mssql_python

mssql_python.native_provider = "mssql-odbc"

Conecte-se usando a cadeia de conexão já existente do seu aplicativo. Mantenha a validação de certificados ativada (Encrypt=yes;TrustServerCertificate=no). Para autenticação e configuração de certificados, veja Strings de conexão e Criptografia e certificados.

connection = mssql_python.connect(connection_string)

O driver aplica estas regras ao escolher o provedor:

  • MSSQL_PYTHON_NATIVE_PROVIDER A variável de ambiente tem precedência sobre native_provider. Uma atribuição de atributos conflitante emite RuntimeWarning.
  • A seleção passa a ser fixa após a validação da string de conexão e imediatamente antes da construção da conexão nativa. Uma falha de conexão subsequente não elimina a seleção. A seleção não corrige um erro anterior de análise da string de conexão nem a ausência do pacote do provedor. Após a seleção estar fixa, trocar native_provider para outro provedor emite RuntimeWarning e não tem efeito. Reinicie o processo para trocar de provedor.
  • Um nome de provedor não reconhecido gera ValueError; o driver não recorre ao provedor padrão. Um nome desconhecido atribuído a native_provider gera um erro imediatamente. Um nome desconhecido na variável de ambiente gera um erro quando você tenta se conectar.
  • Defina native_provider para None limpar a seleção de atributos antes que ela fique fixa. A variável ambiente ainda tem 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 conectar, isso indica a seleção, não a prova de que o driver nativo carregou com sucesso.

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

O que funciona hoje

O mssql-odbc driver implementa todas as funções ODBC que mssql-python chama, então a maioria dos aplicativos pode trocar de provedor sem alterações no código. Verifique os problemas conhecidos para as diferenças restantes.

Area Notes
Ciclo de vida da conexão Conectar, close(), with blocos, tempo de login, diagnósticos e alterar o banco de dados atual. As configurações da string de conexão incluem ApplicationIntent, MultiSubnetFailover, IpAddressPreference, PacketSize, KeepAlive, e ConnectRetryCount / ConnectRetryInterval (resiliência de conexão ociosa).
Authentication autenticação SQL (UID / PWD); autenticação do Windows (Trusted_Connection=Yes, usando SSPI no Windows ou Kerberos no Linux e macOS); e autenticação interativa do Microsoft Entra, autenticação por código de dispositivo do Microsoft Entra, autenticação de entidade de serviço do Microsoft Entra, autenticação de identidade gerenciada do Microsoft Entra, credencial padrão e token de acesso do Microsoft Entra. A autenticação integrada do Entra e a autenticação por senha não são suportadas; veja Problemas conhecidos.
TLS Encrypt, TrustServerCertificate, HostnameInCertificate e ServerCertificate.
Execução da consulta Execução direta e preparada, reutilização de plano preparado, parâmetros qmark e a conversão pyformat que mssql-python realiza.
Sintaxe de escape ODBC Função, data/hora, outer join, GUID, LIKE ... {escape ...}, intervalo e formas de escape {encrypt ...}.
Procedimentos armazenados Chame-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 comum de binding; Limitações dos parâmetros XML e UDT estão listadas abaixo.
executemany() Em lote com arrays de parâmetros ODBC. Linhas contendo valores streamados voltam à execução linha por linha.
Recuperação de linhas fetchone(), fetchmany(), fetchall(), iteração, fetchval(), conversão tipada e streaming de texto/binário em grande escala.
Carregamento de setas arrow_batch(), arrow()e arrow_reader(). Requer pyarrow.
Vários conjuntos de resultados nextset(), incluindo resultados produzidos por arrays de parâmetros.
Transactions Autocommit, commit, rollback, o commit automático (ou rollback, caso um erro tenha escapado) 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 instruções executadas pelos cursores dessa conexão; a expiração gera OperationalError. 0 significa sem tempo limite. Essa configuração é separada do tempo limite de login passado como connect(timeout=...).
Agrupamento de conexões O pool embutidomssql-python, incluindo o reset de conexão no checkout e pools separados por identidade do 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 largos e conversores de saída. Decodificação personalizada de caracteres estreitos e conversão de parâmetros não-Unicode têm limitações listadas em Problemas conhecidos.

Tipos de dados

Você pode ler todos os tipos de dados do SQL Server, e o driver suporta todos os tipos de parâmetros que mssql-python vincula. O driver retorna valores xml, json e vector como str (vector como um 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 essas diferenças antes de migrar uma carga de trabalho de msodbcsql18.

Issue Details Workaround
Autenticação integrada do Microsoft Entra Não há suporte para Authentication=ActiveDirectoryIntegrated. A autenticação do Windows (Trusted_Connection=Yes) não é afetada. Use outro método do Microsoft Entra, ou mantenha msodbcsql18.
Autenticação por senha do Microsoft Entra Authentication=ActiveDirectoryPassword não é suportado, e não há previsão de suporte porque esse método não satisfaz o MFA. A autenticação SQL (UID / PWD) não é afetada. Use outro método do Microsoft Entra, como um principal de serviço, identidade gerenciada 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 que não sejam o tempo limite da consulta são rejeitados. Use as palavras-chave equivalentes da string 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; nenhum deles é um prazo geral para operações de conexão.
Hosts com vários endereços msodbcsql18 tem a Resolução Transparente de IP de Rede (TNIR) habilitada por padrão; mssql-odbc não suporta isso. mssql-python rejeita a TransparentNetworkIPResolution palavra-chave connection-string com qualquer um dos provedores. Sem MultiSubnetFailover=Yes, os endereços são testados um de cada vez, então um endereço inacessível pode atrasar a conexão. Não há negociação de cache DNS assistido por servidor nem de roteamento aprimorado. Defina MultiSubnetFailover=Yes para ouvintes de grupos de disponibilidade e outros hosts com vários endereços.
Falhas de DNS transitórias Se uma busca DNS falhar, o driver não recorre ao último endereço válido. (#457) Tente novamente a conexão.
Classificação de dados Metadados de classificação de sensibilidade não estão disponíveis, e SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) não é compatível. Consultar sys.sensitivity_classifications.
Multithreading O uso com múltiplas threads não foi validado. Mantenha msodbcsql18 para cargas de trabalho multithread.
fork() Após conectar No Linux, um processo criado por fork após a conexão do pai pode travar quando usa o driver, mesmo com uma nova conexão. Com o pooling ativado, o processo pai também pode travar. (#566) Use o método spawn start e conecte-se dentro de cada worker.
Cancelando um comando em execução Uma consulta ou busca em execução não pode ser interrompida. Por exemplo, fechar um arrow_reader() não impede uma leitura em andamento em outro tópico. Use 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 cancelá-los, o que pode ser lento. Fechar um cursor que usou uma instrução preparada ignora Connection.timeout e pode travar se o servidor parar de responder. (#546) Busque apenas as linhas que você precisa, por exemplo, com TOP.
Parâmetros grandes xml e UDT Valores vinculados 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. Vincule os valores xml como strings comuns.
Valores vazios image Um valor vazio e não-NULL do SQL Server image é retornado como None em vez de b"". Leia CAST(image_column AS varbinary(max)), ou use msodbcsql18 quando a distinção vazio/NULL importa.
Parâmetros de cadeia de caracteres não Unicode Strings vinculadas como char / varchar até setinputsizes() podem ser codificadas incorretamente para as páginas de código 437, página de código 850 e colações UTF-8. Use a vinculação padrão de string.
Decodificação legada de páginas de código no Windows Com setdecoding(SQL_CHAR, encoding="cp1252") ou outra página de código legada, o texto pode ser decodificado incorretamente ou retornado como bytes, porque o driver retorna dados char / varchar como UTF-8. Use o padrão: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() SQL_USER_NAME retorna a string de conexão UID, não o usuário do banco de dados. Fica vazio quando nenhum UID chega ao driver. Alguns valores de capacidade e limites baseados em tamanho de pacote diferem de msodbcsql18. Use SELECT USER_NAME() para o usuário do banco de dados.
Falhas por falta de memória Algumas falhas de alocação de drivers encerram o processo Python em vez de gerar MemoryError. (#484) Limite o tamanho dos valores que você envia e busca.
Desempenho de leitura para valores grandes Em um benchmark, as leituras em blocos de varchar(max) / nvarchar(max) dados foram um pouco mais lentas do que com msodbcsql18. (#473) Avalie o desempenho da sua carga de trabalho.

Esta não é uma lista completa.

Relatar problemas

Se encontrar um bug, selecione msodbcsql18, reinicie o processo e verifique se o comportamento ainda ocorre. Também remova qualquer atribuição conflitante de provedor no lado Python. A comparação ajuda a isolar o problema; ela sozinha não comprova sua causa. Inclua a saída de mssql_python.get_native_provider_info(), sua plataforma e o SQL com falha ou a mensagem de erro:

Para diagnósticos de drivers Rust, defina essas variáveis antes de iniciar 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 log e MSSQL_TDS_TRACE_DIR grava arquivos por processo em vez de stderr. Reinicie o Python depois de mudar essas configurações. Os rastreamentos podem conter texto SQL e valores de parâmetros. Revise e oculte dados sensíveis antes de compartilhar trechos relevantes, e desative o rastreamento após o diagnóstico.

Conteúdo relacionado

  • Última atualização em