Perguntas Frequentes do mssql-django

Este artigo responde a perguntas frequentes sobre o mssql-django backend Django para SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric.

General

O que é mssql-django?

O mssql-django pacote é um backend de base de dados Django mantido pela Microsoft para SQL Server. Permite que aplicações Django se liguem ao SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric usando o driver pyodbc.

Instale-o com pip:

pip install mssql-django

Que versões do Django suporta o mssql-django?

O mssql-django pacote v1.7 suporta Django 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2 e 6.0. Verifique o ciclo de vida do suporte para a matriz completa de compatibilidade.

Que versões de Python são suportadas?

O mssql-django pacote suporta Python 3.8 e versões posteriores. A versão específica de Python também deve ser compatível com a sua versão de Django. Por exemplo, o Django 5.0 requer Python 3.10 e versões posteriores, e o Django 6.0 requer Python 3.12 e versões posteriores. Consulte o ciclo de vida do Suporte para a matriz completa de compatibilidade.

O mssql-django é mantido pela Microsoft?

Yes. O mssql-django pacote é mantido pela Microsoft e está disponível no PyPI e no GitHub.

Configuration

Que valor ENGINE devo usar em settings.py?

Defina ENGINE para "mssql" na sua DATABASES configuração:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "HOST": "<your-server>",
    },
}

Que driver ODBC devo usar?

Use o Microsoft ODBC Driver 18 para SQL Server. É o padrão na mssql-django versão 1.7 e posteriores, e o backend volta automaticamente ao ODBC Driver 17 se a versão 18 não estiver instalada. Especifique explicitamente o driver no dicionário OPTIONS apenas se precisar de fixar uma versão específica:

"OPTIONS": {
    "driver": "ODBC Driver 18 for SQL Server",
},

Como me ligo ao Base de Dados SQL do Azure?

Utilize o nome de domínio totalmente qualificado do servidor com a porta 1433:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>.database.windows.net",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

Como uso a autenticação Microsoft Entra?

Utilize extra_params em OPTIONS ou na definição TOKEN. A definição TOKEN funciona com quaisquer credenciais azure.identity, incluindo DefaultAzureCredential e ManagedIdentityCredential.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://database.windows.net/.default").token

"TOKEN": token,

Consulte autenticação Microsoft Entra para todos os métodos suportados.

Características

O mssql-django suporta JSONField?

Sim, JSONField é suportado no SQL Server 2016 e versões posteriores. Os dados JSON são armazenados como nvarchar(max) e consultados usando as funções JSON do SQL Server. Consulte o suporte JSONField para consultas suportadas e limitações.

O mssql-django suporta valores de data e hora com fuso horário?

Yes. Quando USE_TZ=True, o Django utiliza o tipo de dados datetimeoffset no SQL Server. Se estiver a migrar uma base de dados existente, precisa de alterar as colunas datetime2 existentes. Veja o suporte ao fuso horário.

Posso chamar procedimentos armazenados?

Yes. Use connection.cursor() com cursor.execute() para chamar procedimentos armazenados. Consulte Procedimentos armazenados para exemplos que incluem múltiplos parâmetros e conjuntos de resultados.

bulk_create devolve os documentos de identificação?

Por predefinição, não. A opção return_rows_bulk_insert é predefinida para False. Defina-o na sua base de dados TrueOPTIONS para permitir o retorno dos IDs após a inserção em massa. Esta opção deve manter-se False para tabelas com gatilhos. Ver operações em massa.

Troubleshooting

É apresentada a mensagem "ODBC Driver não foi encontrado." Como corrijo?

Instale o driver Microsoft ODBC para SQL Server. No Linux, adicione primeiro o repositório Microsoft APT e depois instale o driver:

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -fsSL https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt-get update
ACCEPT_EULA=Y sudo apt-get install -y msodbcsql18

No Windows, descarregue o instalador a partir do site da Microsoft. Em macOS, use Homebrew:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18

Consulte Instalação para instruções completas específicas para cada plataforma.

Porque é que a minha migração falha com "Não é possível alterar IDENTITY a coluna"?

O SQL Server não suporta alterar uma coluna para ou a partir de uma IDENTITY coluna (AutoField). Crie um novo modelo com o tipo de campo desejado e migre os dados manualmente. Veja Limitações e funcionalidades não suportadas no mssql-django.

Porque é que bulk_update falha com campos anuláveis?

No mssql-django 1.7, o back-end trata automaticamente as atualizações com todos os valores NULL. Em versões anteriores, utilize o parâmetro default em bulk_update para evitar expressões CASE WHEN ... THEN NULL em NULL, que causam erros de inferência de tipos do SQL Server:

Product.objects.bulk_update(products, ["description"], default="")

Consulte Operações em massa para mais detalhes.

  • Last updated on