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

mssql-python carrega um dos dois fornecedores 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

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

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 fornecedor Rust ativa MultiSubnetFailover por predefinição para as ligações aplicáveis ao Protocolo de Controlo de Transmissão (TCP). Defina MultiSubnetFailover=no explicitamente para solicitar tentativas de ligação sequenciais. Para alterar o padrão em toda a implantação, defina MSSQL_RS_MULTISUBNET_FAILOVER_DEFAULT para true ou false antes de o controlador nativo ser usado pela primeira vez. A palavra-chave connection-string sobrepõe-se a esta predefinição.

O atributo numérico SQL_COPT_SS_MULTISUBNET_FAILOVER (1248) também sobrepõe a palavra-chave quando definido antes da ligação.

O driver não ativa este padrão para transportes não TCP, espelhamento de bases de dados, instâncias nomeadas que exigem descoberta do SQL Server Browser, ou ligações locais do Windows que omitem um protocolo e endereço explícitos. Ativar MultiSubnetFailover explicitamente para um transporte não TCP, espelhamento de base de dados ou descoberta no SQL Server Browser gera um erro de ligação. Para mais informações, 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). O driver nativo também negocia cache assistida pelo servidor do Sistema de Nomes de Domínio (DNS) e encaminhamento melhorado 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 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.
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, binário, Extensible Markup Language (XML) e parâmetros de tipo definido pelo utilizador (UDT) suportam a transmissão em fluxo de dados em tempo de execução.
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 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 que não há tempo limite. Defina o timeout de login separadamente com connect(timeout=...).
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.
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 SQL de ID de ordenação. A decodificação personalizada de carateres narrow 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 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.

Fechar um arrow_reader() envia SQLCancel para interromper uma busca em curso. A chamada quase falhada aguarda que a limpeza do cancelamento termine. 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 diferenças antes de migrar uma carga de trabalho de msodbcsql18.

Issue Details Workaround
Autenticação por palavra-passe do Microsoft Entra ID Authentication=ActiveDirectoryPassword não é suportado. Este método não consegue satisfazer a autenticação multifatorial (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 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 ligação. Use as palavras-chave Authentication e ApplicationIntent da cadeia de ligação.
Tempo limite da operação de conexão SQL_ATTR_CONNECTION_TIMEOUT controlos de limpeza após cancelamento. Não impõe um timeout na reposição da ligação em pool. Um pedido de ligação pode permanecer bloqueado se o servidor deixar de responder durante o reset. Não há tempo limite de reposição agrupada disponível. Definir connect(timeout=...) para login e Connection.timeout para extratos.
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. Use MultiSubnetFailover=yes para ouvintes de grupos de disponibilidade e outros hosts com múltiplos endereços. Para as predefinições, veja Predefinições de ativação pós-falha de várias sub-redes.
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.
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.
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.
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. A limpeza da instrução preparada usa o tempo limite da consulta da instrução, mas um timeout zero deixa essa limpeza ilimitada. Busca apenas as linhas de que precisas, por exemplo com TOP, e define Connection.timeout antes de criar o cursor.
Decodificação personalizada de caracteres estreitos O driver nativo utiliza a página de código ANSI do Windows no Windows e a página de código da configuração regional do processo no Linux e macOS para texto não Unicode. Uma decodificação explícita em Python que não corresponde a essa página de código pode produzir texto incorreto ou bytes. Utilize a decodificação padrão de caracteres largos: conn.setdecoding(mssql_python.SQL_CHAR).
Connection.getinfo() Alguns valores de capacidade e limites baseados no tamanho dos pacotes diferem de msodbcsql18. SQL_USER_NAME indica o principal da base de dados em vez da cadeia de ligação UID. Consulte os metadados específicos do servidor quando uma capacidade ou limite reportado seja relevante para a sua aplicação.
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. (#473) Compare a carga de trabalho.

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:

$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 de registo e MSSQL_TDS_TRACE_DIR seleciona o diretório para ficheiros de traço por processo a partir do driver ODBC nativo em vez da saída de erro padrão. O pacote complementar Rust também cria ficheiros de registo sob mssql_python_logs no diretório atual.

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.

Conteúdo relacionado

  • Última atualização a