Perguntas Frequentes do 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. A versão 2.0 e versões posteriores ligam-se através do pyodbc driver, que é o predefinido, ou do driver da mssql-python Microsoft.

Instale-o com pip:

pip install mssql-django

A mssql-django versão 2.0 do pacote suporta Django 5.2, 6.0 e 6.1. Os projetos em Django 3.2 a 5.1 mantêm-se na versão 1.8.0. Verifique o ciclo de vida do suporte para a matriz completa de compatibilidade.

A mssql-django versão 2.0 do pacote suporta Python 3.10 a 3.14. A versão específica de Python também deve ser compatível com a sua versão de Django: o Django 5.2 é testado com Python 3.10 até 3.13, e Django 6.0 e 6.1 são testados com Python 3.12 a 3.14. Consulte o ciclo de vida do Suporte para a matriz completa de compatibilidade.

A versão 2.0 e versões posteriores suportam dois drivers, selecionados para cada alias de base de dados. pyodbcé o padrão e necessita de um driver Microsoft ODBC instalado externamente para SQL Server. Para usar o controlador da Microsoft mssql-python em alternativa, que não requer uma instalação separada do controlador ODBC, adicione python_driver ao dicionário OPTIONS desse alias:

"OPTIONS": {
    "python_driver": "mssql_python",
},

Os pseudónimos que omitem a opção continuam a usar pyodbc. Para as diferenças de comportamento entre os dois caminhos, veja Selecionar o driver de base de dados para mssql-django.

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

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

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

No caminho predefinidopyodbc, use o Microsoft ODBC Driver 18 para SQL Server. É o padrão, e o backend volta automaticamente ao ODBC Driver 17 se a versão 18 não estiver instalada. Especifique explicitamente o controlador no dicionário OPTIONS apenas se precisar de fixar uma versão específica, o que também desativa o mecanismo de recurso:

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

A via mssql-python ignora a opção driver e utiliza o Controlador ODBC 18 que pip instala juntamente com ele.

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",
        },
    },
}

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.

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.

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.

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.

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.

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.

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.

O backend trata automaticamente as atualizações com todos os valores NULL. Se precisares de controlar o valor do marcador de posição, utiliza o parâmetro default em bulk_update, o que mantém NULL fora das expressões CASE WHEN ... THEN NULL que causam erros de inferência de tipo do SQL Server:

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

Consulte Operações em massa para mais detalhes.