Utilizar o controlador mssql-odbc (Versão preliminar)

mssql-python carrega um de dois fornecedores de ODBC nativos:

Provider Description Status
msodbcsql18 Microsoft ODBC Driver 18 para SQL Server Predefinição
mssql-odbc Driver ODBC baseado em Rust Pré-visualização, opt-in

Este artigo aborda o mssql-odbc provider incluído no mssql-python-rs 0.5.0 e o que difere de msodbcsql18.

Note

Utilize msodbcsql18 para cargas de trabalho em produção. Antes de aderir ao fornecedor de pré-visualização mssql-odbc , reveja os problemas conhecidos.

Availability

O driver vem dentro do pacote mssql-python-rs como wheels pré-compiladas 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)

Ativar o controlador

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

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

$env:MSSQL_PYTHON_NATIVE_PROVIDER = "mssql-odbc"

Defina a MSSQL_CONNECTION_STRING variável de ambiente para a cadeia de ligação da sua aplicação. Mantenha a validação de certificados ativada (Encrypt=yes;TrustServerCertificate=no). Para mais informações, consulte Strings de ligação e Encriptação e certificados.

Execute este exemplo com o fornecedor que escolheu:

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 como um fornecedor em conflito emite RuntimeWarning.
  • Antes do driver carregar, defina native_provider para None para limpar a definição de Python. Isto não elimina a variável de ambiente.
  • Um nome de prestador não reconhecido gera ValueError. Atribuir um nome inválido a native_provider gera imediatamente um erro; uma variável de ambiente inválida gera um erro quando se liga. O controlador não recorre ao provedor predefinido.
  • O fornecedor fica definido quando o driver inicia uma tentativa nativa de ligação, mesmo que essa tentativa falhe. Reinicie o Python para mudar de provedor. Mudar native_provider para outro fornecedor emite RuntimeWarning e não tem efeito.

Erros de validação da cadeia de ligação e pacotes do fornecedor em falta ocorrem antes deste ponto. Pode corrigir estes erros e escolher outro fornecedor sem ter de reiniciar.

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

Para voltar a msodbcsql18, remove MSSQL_PYTHON_NATIVE_PROVIDER e qualquer atribuição de native_provider da tua aplicação, depois reinicia o Python.

Predefinições de failover de várias sub-redes

O provider Rust usa MultiSubnetFailover=yes por predefinição para ligações TCP elegíveis. Defina MultiSubnetFailover=no para tentativas sequenciais. Para alterar a predefinição da implementação distribuída, defina MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT como true ou false (indistinguível entre maiúsculas e minúsculas) antes da primeira utilização do driver. Outros valores causam um erro, a menos que sejam substituídos na ligação.

A palavra-chave connection-string substitui a predefinição por omissão do ambiente. O atributo pre-connect SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) sobrepõe-se a ambos.

A predefinição exclui transportes não TCP, espelhamento de bases de dados e instâncias nomeadas que requerem descoberta pelo SQL Server Browser. Estas opções também rejeitam MultiSubnetFailover=yes explícito.

No Windows, o valor predefinido também está desativado para destinos locais simples, como localhost. Um prefixo ou porta TCP explícita, como tcp:localhost ou localhost,1433, evita esta exclusão de destino local. A opção explícita MultiSubnetFailover=yes também o substitui. Consulte Alta disponibilidade e failover.

Funcionalidades suportadas

As seguintes funcionalidades são suportadas, sujeitas aos problemas conhecidos.

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).
Resiliência de rede As ligações TCP elegíveis utilizam tentativas de endereço paralelo por predefinição. O modo paralelo não prioriza endereços por IpAddressPreference e rejeita mais de 64 endereços resolvidos. Para tentativas sequenciais e ordenação por famílias de endereços, consulte Predefinições de failover multi-sub-rede. O algoritmo separado Transparent Network IP Resolution (TNIR) não está implementado. O cache do Sistema de Nomes de Domínio (DNS) assistido pelo servidor permite o recurso a endereços em cache em caso de falha de DNS após um início de sessão bem-sucedido, em que o servidor permite o armazenamento em cache. O encaminhamento melhorado é utilizado quando negociado com o servidor.
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 interativa do Microsoft Entra ID, autenticação integrada, autenticação por código de dispositivo, service principal, autenticação com identidade gerida, autenticação com credencial predefinida e token de acesso. A autenticação por palavra-passe 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. No macOS, Encrypt=Strict as ligações TCP podem negociar TLS 1.3 com um servidor compatível.
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, 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 Texto grande e parâmetros binários fluem para o servidor pelo caminho de ligação normal. Explicit SQL_SS_XML e SQL_SS_UDT bindings através setinputsizes() também fluem quando o Python seleciona data-at-execution: o tamanho declarado deve exceder 4000 para str ou 8000 para bytes ou bytearray. A ligação ao tipo definido pelo utilizador (UDT) exige que o servidor descreva o tipo do parâmetro. Alguns bindings personalizados e mistos ainda fazem buffer. Para obter mais informações, consulte Problemas conhecidos.
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 de tipos e transmissão de texto/binário de grande dimensão.
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 e os níveis de isolamento read-uncommitted, read-committed, repeatable-read, serializable e snapshot. Com o autocommit desligado, o gestor de contexto de ligação faz commit na saída bem-sucedida e faz rollback em caso de exceção.
Tempo limite da consulta Define Connection.timeout em segundos antes de criar um cursor. Quando uma instrução ultrapassa esse timeout, o driver lança OperationalError. 0 significa sem limite de tempo. Defina o timeout de login separadamente com connect(timeout=...).
Tempo limite da operação de conexão conn.set_attr(mssql_python.SQL_ATTR_CONNECTION_TIMEOUT, seconds) Aplica-se a pedidos de rede pertencentes à conexão, incluindo commit, rollback e alterações de catálogo e isolamento. O reset agrupado adia o reset do servidor para o seguinte pedido de configuração de isolamento; tanto esse pedido como qualquer rollback anterior utilizam este timeout. 0 deixa esses pedidos sem limite. Este timeout é separado dos tempos limite de início de sessão e de consulta e não constitui um prazo total para a obtenção de ligação do pool. A limpeza após o cancelamento pode aumentar o tempo decorrido da chamada.
Limpeza do cursor Fechar um cursor cancela o trabalho pendente no servidor quando necessário, em vez de ler todos os resultados restantes. A limpeza da instrução preparada respeita o tempo de espera da consulta. A limpeza de cancelamento tem um orçamento de espera adicional igual ao tempo de espera da ligação, ou 120 segundos quando esse tempo de espera é 0.
Agrupamento de conexões O pool incorporado mssql-python, incluindo a reposição da ligação antes da reutilização. Para isolamento de pool específico de autenticação, veja isolamento de identidade.
Multithreading Conexões e consultas simultâneas com uma conexão e um cursor separados por trabalhador. Não partilhe cursores entre threads.
APIs de metadados tables(), rowIdColumns(), procedures(), rowVerColumns(), getTypeInfo(), getinfo(), statistics(), foreignKeys(), primaryKeys() e columns(). SQL_USER_NAME Reporta o utilizador da base de dados em vez da cadeia UIDde conexão. Os valores de capacidades e os limites baseados no tamanho do pacote podem diferir de msodbcsql18: SQL_NEED_LONG_DATA_LEN indica "N" porque a entrada longa não requer um comprimento total declarado. Utilize as capacidades e limites devolvidos.
Codificação e conversores Codificação padrão de caracteres largos, conversores de saída, parâmetros não Unicode sensíveis à ordenação e resultados de caracteres estreitos na codificação do cliente da plataforma. A descodificação personalizada de caracteres estreitos deve corresponder a essa codificação; uma incompatibilidade pode produzir texto incorreto ou bytes. Utilize conn.setdecoding(mssql_python.SQL_CHAR) para restaurar a decodificação padrão de caracteres largos. Para substituição de parâmetros não Unicode, consulte Problemas conhecidos.

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

Se um fetch estiver a correr quando fecha um arrow_reader(), close() cancela o fetch e retorna depois de este parar. Fechar um leitor de uma consulta anterior não afeta uma consulta posterior no mesmo cursor. Para mais informações, consulte integração com o Apache Arrow.

Tipos de dados

O driver devolve valores xml, json e vetor como objetos Python str, com vetor representado como um array JavaScript Object Notation (JSON). Ele devolve tipos comuns de runtime de linguagem (CLR), como geometry, geography e hierarchyid, como objetos Pythonbytes. Para mais informações, consulte Mapeamentos de tipos de dados e Problemas conhecidos.

Problemas conhecidos

Verifique estas limitações antes de mudar uma carga de trabalho de msodbcsql18. A tabela seguinte assinala exclusões intencionais.

Issue Details Workaround
Autenticação por palavra-passe Microsoft Entra ID (exclusão intencional) Authentication=ActiveDirectoryPassword não é suportado, e o suporte não está planeado porque este método não consegue satisfazer a autenticação multifator (MFA). A autenticação SQL (UID / PWD) não é afetada. Utilize outro método do Microsoft Entra ID, como um principal de serviço, identidade gerida ou token de acesso.
attrs_before Configurações O seletor numérico de autenticação (SQL_COPT_SS_AUTHENTICATION) e o atributo de intenção da aplicação permanecem sem suporte. O failover em várias sub-redes e os atributos de segurança integrada são suportados. A correspondência de identificadores de metadados (SQL_ATTR_METADATA_ID) também não é suportada. Utilize as palavras-chave Authentication e ApplicationIntent da cadeia de ligação, quando aplicável.
fork() Após estabelecer a ligação 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.
Rastreamento nativo no Linux Com o rastreamento nativo ativado, o Python pode abortar durante a limpeza do driver na saída do processo. Deixe MSSQL_TDS_TRACE sem configurar no Linux.
Utilização de memória com ligações personalizadas de grandes parâmetros Os valores de dados na execução associados como de largura fixa a SQL_CHAR, SQL_WCHAR ou SQL_BINARY são armazenados em buffer para conversão. Misturar parâmetros em buffer e transmitidos em streaming também pode armazenar em buffer valores grandes anteriores enquanto se espera por um valor bufferizado posterior. Prefira as ligações predefinidas de comprimento variável. Evite grandes sobreposições de largura fixa através de setinputsizes() quando a utilização de memória for importante.
Substituição de caracteres não Unicode Para caracteres fora da página de código alvo de um parâmetro não Unicode, o driver pode substituir ? em que msodbcsql18 usa um carácter mais adequado. Prefira tipos SQL Unicode e as ligações padrão de string Python quando o texto deve ser preservado.
Alterações de isolamento após SQL bruto Após o raw SET TRANSACTION ISOLATION LEVEL, definir o atributo de ligação para o nível em cache do driver pode devolver sucesso sem restaurar esse nível no servidor. (#798) Evite misturar SQL bruto e alterações de isolamento baseadas em atributos. Use um SET TRANSACTION ISOLATION LEVEL explícito ao restaurar o nível.
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 Leituras em blocos de dados varchar(max) e nvarchar(max) podem ser mais lentas do que com msodbcsql18. Os resultados dependem da plataforma e da carga de trabalho. (#473) Compare a carga de trabalho.

Esta lista não é exaustiva.

Comunicar problemas

Se encontrar um bug, reproduza-o msodbcsql18 e registe se ocorre com ambos os fornecedores. Para instruções para alternar, veja Ativar o controlador.

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

No Windows, defina estas variáveis no PowerShell antes de iniciar o Python para recolher diagnósticos nativos dos drivers. Reproduza o problema com mssql-odbc selecionado. No Linux, deixe MSSQL_TDS_TRACE não definido devido à falha de saída do processo descrita em Problemas conhecidos.

$env:MSSQL_TDS_TRACE = "true"
$env:MSSQL_TDS_TRACE_LEVEL = "debug"
$env:MSSQL_TDS_TRACE_DIR = "./traces"
$env:MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB = "100"

MSSQL_TDS_TRACE ativa o rastreio, MSSQL_TDS_TRACE_LEVEL seleciona o filtro de registo e MSSQL_TDS_TRACE_DIR seleciona o diretório para ficheiros de rastreio por processo a partir do driver ODBC nativo em vez da saída de erro padrão. MSSQL_TDS_TRACE_MAX_FILE_SIZE_MB define o limiar de rotação por ficheiro (100 MiB por predefinição; aceita 1-1024). Não é um limite total de espaço em disco: ficheiros individuais podem ultrapassar o limiar, e ficheiros antigos não são apagados. O pacote complementar Rust também cria ficheiros de registo sob mssql_python_logs no diretório atual. Reinicie o Python depois de alterar estas definições.

Os rastreios podem conter texto T-SQL e valores de parâmetros. Oculte dados sensíveis antes de partilhar excertos. Após o diagnóstico, remova estas variáveis e reinicie o Python para desativar o rastreamento.