Selecione o driver da base de dados para mssql-django

A partir da versão 2.0, mssql-django liga-se através de dois drivers de base de dados Python:

• pyodbc com um driver Microsoft ODBC para SQL Server instalado externamente. Este driver é o padrão.
• mssql-python, o driver Python da Microsoft, que não precisa de um driver ODBC instalado separadamente.

Escolhes o driver para cada alias de base de dados. Um alias pode usar mssql-python, enquanto o resto do projeto continua a usar pyodbc. O valor ENGINE mantém-se "mssql" em ambos os casos.

Optar um alias para mssql-python

Defina a opção python_driver no dicionário desse pseudónimo OPTIONS:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<database>",
        "USER": "<user_id>",
        "PASSWORD": "<password>",
        "HOST": "<server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "python_driver": "mssql_python",
            "extra_params": "Encrypt=yes",
        },
    },
}

O backend aceita "mssql_python", "mssql-python", e "python", e a comparação ignora o caso. Omita python_driver, deixa vazio ou define para "pyodbc" manter o driver padrão. Como a configuração é para cada alias, pode reverter uma base de dados de cada vez ao remover a opção.

O mssql-python módulo é importado apenas quando um alias o seleciona. Se a versão instalada for anterior à 1.15.0, o backend levanta ImproperlyConfigured com a versão necessária.

Requisitos de instalação

pip install mssql-django Instala ambos os drivers. O mssql-python caminho não tem uma instalação separada de drivers ODBC. Uma instalação --no-deps, ou um índice privado que não replica mssql-python, faz com que o pacote fique em falta e o alias falhe aquando da importação.

Instale os pré-requisitos da plataforma para mssql-python, incluindo OpenSSL no macOS e as bibliotecas necessárias no Linux.

Como mssql-python é uma dependência obrigatória, mssql-django a versão 2.0 instala-se apenas em plataformas que tenham uma distribuição compatível mssql-python . Para a lista de plataformas, consulte o suporte e o ciclo de vida do mssql-django.

Diferenças de comportamento

Os dois drivers criam cadeias de ligação diferentes e expõem palavras-chave de ligação diferentes. Revise esta secção antes de mudar de pseudónimo.

Definições de ligação

Tempos limite, novas tentativas, nível de isolamento, agrupamento e return_rows_bulk_insert comportam-se da mesma forma em ambas as vias.

Parâmetros extra de ligação

mssql-python 1.15 valida extra_params com base numa lista de permissões e rejeita tudo o que esteja fora dela. Palavras-chave suportadas incluem Authentication, Encrypt, TrustServerCertificate, ServerCertificateHostnameInCertificate, ServerSPN, MultiSubnetFailover, ApplicationIntent, , ConnectRetryCount, KeepAliveIpAddressPreferenceConnectRetryIntervalKeepAliveIntervale .PacketSize

O controlador rejeita MARS_Connection, APP, LongAsMax e ColumnEncryption, bem como palavras-chave exclusivas do pyodbc, como WSID, AnsiNPW, QuotedId, Current Language, Description, Network Library, Regional, UseFMTONLY, Connect Timeout, SERVERNAME, DSN e DRIVER. Remova essas palavras-chave antes de mudar de pseudónimo e use a connection_timeout opção em vez de Connect Timeout.

Quando extra_params define uma palavra-chave que o backend também gera, o valor explícito vence.

Vários conjuntos de resultados ativos

No caminho pyodbc, o backend adiciona MARS_Connection=yes quando o alias usa um controlador ODBC da Microsoft no Windows. Um valor explícito MARS_Connection em extra_params é honrado em vez disso, e a correspondência ignora o caso.

O mssql-python caminho nunca ativa o MARS e rejeita a MARS_Connection palavra-chave, por isso não podes ativar o MARS para esse alias.

Sem MARS, QuerySet.iterator() carrega o resultado completo para a memória antes de devolver as linhas, para que uma consulta aninhada possa reutilizar a ligação à base de dados, e chunk_size não altera isso. Considere o custo de memória em conjuntos de consultas grandes.

Para endpoints que rejeitam MARS, como o Microsoft Fabric Warehouse, veja Desativar MARS.

Configuração de codificação

Ambos os drivers aceitam setencoding e setdecoding, e cada entrada vai para o método de ligação do driver selecionado. Cada setdecoding entrada precisa de uma sqltype chave em ambos os caminhos, e a mesma entrada funciona em qualquer um dos drivers. Uma diferença: mssql-python aceita -99 para SQL_WMETADATA, e pyodbc rejeita-o.

Escolha entre os pilotos

Para novos desenvolvimentos, use mssql-python. Remove a etapa de instalação do driver ODBC das imagens de contentores e das implementações de serviços de aplicação.

Utilize pyodbc quando a sua implementação depender de um DSN nomeado, do FreeTDS, do Always Encrypted através da palavra-chave ColumnEncryption, de uma versão do controlador ODBC que gere manualmente ou de MARS. Para o que o MARS requer em cada caminho, veja Múltiplos Conjuntos de Resultados Ativos.

Os projetos existentes podem permanecer em pyodbc. Continua a ser o padrão e é totalmente suportado. Quando mudares, troca um alias de cada vez e corre o teu conjunto de testes contra ele antes de moveres o resto.

Conteúdo relacionado

• Opções de ligação para mssql-django
• Referência de configuração MSSQL-Django
• Agregação de ligações no mssql-django
• Autenticação Microsoft Entra com mssql-django
• Driver mssql-python para SQL Server