Use o driver mssql-odbc (Versão prévia)

mssql-python carrega um dos dois provedores ODBC nativos:

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 para SQL Server Default
mssql-odbc driver ODBC baseado em Rust Visualizar, opt-in

O mssql-python-rs pacote 0.4.0 inclui o mssql-odbc provedor.

Note

Use msodbcsql18 para cargas de trabalho em produção. Antes de optar pelo provedor em versão prévia, mssql-odbc revise os problemas conhecidos dele.

Availability

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

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

Habilitar o driver

Instalar mssql-python também instala mssql-python-rs, que contém o mssql-odbc driver:

python -m 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 de abrir a primeira conexão. Use um dos seguintes métodos.

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Defina a variável de ambiente MSSQL_CONNECTION_STRING como a string de conexão do seu aplicativo. Mantenha a validação de certificados ativada (Encrypt=yes;TrustServerCertificate=no). Para mais informações, veja Strings de conexão e Criptografia e certificados.

Execute este exemplo com o provedor escolhido:

import os
import mssql_python

with mssql_python.connect(os.environ["MSSQL_CONNECTION_STRING"], timeout=45) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT 1")
        print(cursor.fetchone()[0])

O exemplo imprime 1.

A seleção do prestador segue as seguintes regras:

  • MSSQL_PYTHON_NATIVE_PROVIDER tem precedência sobre native_provider. Definir o atributo para um provedor conflitante gera RuntimeWarning.
  • Antes de o driver carregar, defina native_provider como None para limpar a configuração do Python. Isso não limpa a variável de ambiente.
  • Um nome de provedor não reconhecido gera ValueError. Atribuir um nome inválido a native_provider gera um erro imediatamente; uma variável de ambiente inválida gera um erro ao se conectar. O driver não recorre ao provedor padrão.
  • O provedor é definido quando o driver inicia uma tentativa nativa de conexão, mesmo que essa tentativa falhe. Reinicie o Python para trocar de provedores. Alterar native_provider para outro provedor emite RuntimeWarning e não tem efeito.

Erros de validação de string de conexão e pacotes de provedores ausentes ocorrem antes desse ponto. Você pode corrigir esses erros e escolher outro provedor sem precisar reiniciar.

Ligue mssql_python.get_native_provider_info() para verificar o nome do provedor, como foi selecionado e se a seleção é fixa.

Para voltar a msodbcsql18, remova MSSQL_PYTHON_NATIVE_PROVIDER e qualquer native_provider atribuição da sua aplicação, então reinicie o Python.

Configurações padrão de failover para múltiplas sub-redes

O provedor Rust habilita MultiSubnetFailover por padrão em conexões aplicáveis do Protocolo de Controle de Transmissão (TCP). Defina MultiSubnetFailover=no explicitamente para solicitar tentativas de conexão sequenciais. Para alterar o padrão de toda a implantação, defina MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT para true ou false antes de o driver nativo ser usado pela primeira vez. A palavra-chave connection-string sobrepõe esse valor padrão.

O atributo numérico SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) também sobrepõe a palavra-chave quando definido antes de conectar.

O driver não ativa esse padrão para transportes que não sejam TCP, espelhamento de banco de dados, instâncias nomeadas que exigem descoberta pelo SQL Server Browser ou conexões locais do Windows que omitem um protocolo e endereço explícitos. Habilitar explicitamente MultiSubnetFailover para um transporte não TCP, espelhamento de banco de dados ou descoberta do SQL Server Browser gera um erro de conexão. Para mais informações, veja Alta disponibilidade e failover.

Recursos com suporte

Os seguintes recursos são suportados, sujeitos aos problemas conhecidos.

Area Notes
Ciclo de vida da conexão Conectar, close(), blocos with, tempo limite de logon, diagnóstico e alteração do 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). O driver nativo também negocia cache assistido por servidor do Sistema de Nomes de Domínio (DNS) e roteamento aprimorado quando o servidor os suporta.
Authentication autenticação SQL (UID / PWD); autenticação do Windows (Trusted_Connection=Yes, usando Security Support Provider Interface (SSPI) no Windows ou Kerberos no Linux e macOS); e autenticação do Microsoft Entra ID interativa, integrada, com código de dispositivo, com entidade de serviço, com identidade gerenciada, com credencial padrão e com token de acesso. A autenticação por senha do Microsoft Entra ID não é suportada. Para obter mais informações, consulte Problemas conhecidos.
Segurança da Camada de Transporte (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, junção externa, identificador globalmente único (GUID), LIKE ... {escape ...}, intervalo e formas de escape {encrypt ...}.
Procedimentos armazenados Chame-os com Transact-SQL (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 Parâmetros de texto grande, binários, Extensible Markup Language (XML) e tipos definidos pelo usuário (UDT) suportam streaming de dados em execução.
executemany() Em lote com matrizes de parâmetros ODBC. Linhas contendo valores streamados voltam à execução linha por linha.
Busca de linhas fetchone(), fetchmany(), fetchall(), iteração, fetchval(), conversão tipada e streaming de texto/binário em grande escala.
Busca do Arrow 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 e os níveis de isolamento read-uncommitted, read-committed, repeatable-read, serializável e snapshot. Com o autocommit desligado, o gerenciador de contexto de conexão faz commit ao sair bem-sucedido e reverte em caso de exceção.
Tempo limite da consulta Defina Connection.timeout em segundos antes de criar um cursor. Quando uma instrução ultrapassa esse tempo limite, o driver gera OperationalError. 0 significa “sem tempo limite”. Defina o timeout de login separadamente com connect(timeout=...).
Agrupamento de conexões O pool embutido mssql-python, incluindo redefinição da conexão antes da reutilização. Para isolamento de pool específico de autenticação, veja Identity isolation.
APIs de metadados tables(), columns(), primaryKeys(), foreignKeys(), statistics(), , rowIdColumns(), rowVerColumns(), , procedures()e getTypeInfo().
Codificação e conversores Codificação padrão de caracteres largos, conversores de saída e parâmetros não Unicode conscientes da colação, incluindo UTF-8 e colações legadas de SQL com ID de ordenação. A decodificação personalizada de caracteres estreitos deve corresponder à página de código do cliente. Para obter mais informações, consulte Problemas conhecidos.

A autenticação integrada do Microsoft Entra ID utiliza a conta Windows logada no Windows. No Linux e macOS, ele usa um ticket Kerberos para autenticar no endpoint Serviços de Federação do Active Directory (AD FS) (AD FS) do tenant. Para pré-requisitos, veja autenticação integrada do Windows.

Fechar um arrow_reader() envia SQLCancel para interromper uma busca em andamento. A chamada em andamento espera a limpeza do cancelamento terminar. Para mais informações, veja integração com o Apache Arrow.

Tipos de dados

O driver retorna valores xml, json e vetor como objetos Pythonstr, com vetor representado como um array de Notação de Objetos JavaScript (JSON). Ele retorna tipos de runtime de linguagem comum (CLR), como geometria, geografia e hierarchyid, como objetos Python bytes. Para mais informações, veja Mapeamentos de tipos de dados e Problemas conhecidos.

Problemas conhecidos

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

Issue Details Workaround
Autenticação por senha do Microsoft Entra ID Não há suporte para Authentication=ActiveDirectoryPassword. Esse método não consegue satisfazer a autenticação multifator (MFA). A autenticação SQL (UID / PWD) não é afetada. Use outro método do Microsoft Entra ID, como uma entidade de serviço, identidade gerenciada ou token de acesso.
attrs_before Configurações O modo de autenticação do Microsoft Entra ID e a intenção da aplicação não podem ser definidos como atributos numéricos de conexão. Use as palavras-chave Authentication e ApplicationIntent de cadeia de conexão.
Tempo limite da operação de conexão SQL_ATTR_CONNECTION_TIMEOUT controles de limpeza de cancelamento. Não impõe um timeout no reset de conexão em pool. Uma solicitação de conexão pode permanecer bloqueada se o servidor parar de responder durante o reset. Não há tempo limite de redefinição do pool disponível. Defina connect(timeout=...) para login e Connection.timeout para extratos.
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 dá suporte a ela. mssql-python rejeita a TransparentNetworkIPResolution palavra-chave connection-string com qualquer um dos provedores. Use MultiSubnetFailover=yes para listeners de grupo de disponibilidade e outros hosts com vários endereços. Para os padrões, veja Padrões de failover de várias sub-redes.
Classificação de dados Metadados de classificação de confidencialidade não estão disponíveis, e SQL_COPT_SS_DATACLASSIFICATION_VERSION (1400) não é compatível. Consultar sys.sensitivity_classifications.
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 de inicialização spawn e conecte-se dentro de cada worker.
Rastreamento nativo no Linux Com o rastreamento nativo ativado, o Python pode abortar durante a limpeza do driver ao sair do processo. Deixe MSSQL_TDS_TRACE sem configurar no Linux.
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. A limpeza da instrução preparada usa o tempo limite da consulta da instrução, mas um tempo de espera zero deixa essa limpeza ilimitada. Busque apenas as linhas que você precisa, por exemplo com TOP, e defina Connection.timeout antes de criar o cursor.
Decodificação personalizada de caractere estreito O driver nativo usa a página de código ANSI do Windows no Windows e a página de código da localidade do processo no Linux e macOS para texto estreito. Uma decodificação explícita em Python que não corresponde àquela página de código pode produzir texto incorreto ou bytes. Use a decodificação padrão de caracteres largos: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Alguns valores de capacidade e limites baseados em tamanho de pacote diferem de msodbcsql18. SQL_USER_NAME reporta a entidade principal do banco de dados em vez da cadeia de conexão UID. Consulte os metadados específicos do servidor quando uma capacidade ou limite reportado for relevante para sua aplicação.
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 Leituras em blocos de dados varchar(max) e nvarchar(max) podem ser mais lentas do que com msodbcsql18. (#473) Avalie o desempenho da sua carga de trabalho.

Relatar problemas

Se você encontrar um bug, reproduza-o com msodbcsql18 e registre se ele ocorre com ambos os provedores. Para instruções sobre como alternar, veja Habilitar o driver.

Inclua a saída de mssql_python.get_native_provider_info(), seu sistema operacional, as versões do Python e do driver, e o lote T-SQL com falha e a mensagem de erro no seu relatório:

No Windows, defina essas variáveis no PowerShell antes de iniciar o Python para coletar diagnósticos nativos dos drivers. Reproduza o problema com mssql-odbc selecionado:

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = ".\traces"

MSSQL_TDS_TRACE permite o rastreamento, MSSQL_TDS_TRACE_LEVEL seleciona o nível do log e MSSQL_TDS_TRACE_DIR seleciona o diretório para arquivos de rastreamento por processo do driver ODBC nativo em vez da saída padrão de erro. O pacote complementar Rust também cria arquivos de log em mssql_python_logs no diretório atual.

Os rastreamentos podem conter texto T-SQL e valores de parâmetro. Oculte dados sensíveis antes de compartilhar trechos. Após o diagnóstico, remova essas variáveis e reinicie o Python para desativar o rastreamento.

Conteúdo relacionado

  • Última atualização em