Selecione o driver de banco de dados para mssql-django

A partir da versão 2.0, mssql-django conecta-se por meio de dois drivers de banco de dados em Python:

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

Você escolhe o driver para cada alias de banco de dados. Um único alias pode ser usado mssql-python enquanto o restante do projeto permanece ativo pyodbc. O ENGINE valor permanece "mssql" em ambos os casos.

Optar por um alias no mssql-python

Defina a opção python_driver no dicionário OPTIONS desse alias:

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, deixe vazio ou configure para "pyodbc" manter o driver padrão. Como a configuração é por alias, você pode reverter um banco de dados de cada vez removendo essa 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 gera 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 possui instalação separada de drivers ODBC. Uma instalação via --no-deps, ou um índice privado que não espelha mssql-python, faz com que o pacote fique ausente e o alias falhe na 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 apenas em plataformas que possuem uma distribuição compatível mssql-python . Para a lista de plataformas, veja suporte e ciclo de vida mssql-django.

Diferenças de comportamento

Os dois drivers constroem cadeias de conexão diferentes e expõem palavras-chave de conexão distintas. Revise esta seção antes de trocar de pseudônimo.

Configurações de conexão

Timeouts, novas tentativas, nível de isolamento, colação e return_rows_bulk_insert se comportam da mesma forma em ambos os caminhos.

Parâmetros extras de conexão

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

O driver rejeita MARS_Connection, APP, LongAsMax e ColumnEncryption, juntamente com 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 trocar um pseudônimo e use a connection_timeout opção no lugar de Connect Timeout.

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

Conjuntos de resultados ativos múltiplos

No caminho pyodbc, o backend adiciona MARS_Connection=yes quando o alias usa um driver 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 ele rejeita a MARS_Connection palavra-chave, então você não pode ativar o MARS para esse alias.

Sem o MARS, QuerySet.iterator() lê o resultado completo para a memória antes de retornar linhas, para que uma consulta aninhada possa reutilizar a conexão, e chunk_size não muda isso. Considere o custo de memória em grandes conjuntos de consultas.

Para endpoints que rejeitam MARS, como o Microsoft Fabric Warehouse, consulte Desabilitar MARS.

Configuração de codificação

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

Escolha entre os pilotos

Para novos desenvolvimentos, use mssql-python. Ele remove a etapa de instalação do driver ODBC das imagens de contêineres e das implantações de serviços de aplicativos.

Use pyodbc quando sua implantação depende de um DSN nomeado, FreeTDS, Always Encrypted através da ColumnEncryption palavra-chave, uma versão do driver ODBC que você gerencia por conta própria, ou MARS. Para o que o MARS exige em cada caminho, veja Múltiplos Conjuntos de Resultados Ativos.

Projetos existentes podem permanecer em pyodbc. Ele continua sendo o padrão e totalmente suportado. Quando você fizer a migração, troque um alias por vez e execute sua suíte de testes nele antes de migrar o restante.

Conteúdo relacionado

• Opções de conexão para mssql-django
• Referência de configuração mssql-django
• Pool de conexões no mssql-django
• Autenticação do Microsoft Entra com mssql-django
• driver mssql-python para SQL Server