Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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_PROVIDERtem precedência sobrenative_provider. Definir o atributo como um fornecedor em conflito emiteRuntimeWarning. - Antes do driver carregar, defina
native_providerparaNonepara 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 anative_providergera 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_providerpara outro fornecedor emiteRuntimeWarninge 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:
- Problemas com o driver Rust: https://github.com/microsoft/mssql-rs/issues
-
mssql-pythonQuestões: https://github.com/microsoft/mssql-python/issues
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.