Perguntas frequentes sobre mssql-django

O pacote mssql-django é um backend de banco de dados do Django, mantido pela Microsoft, para o SQL Server. Ele permite que aplicações Django se conectem ao SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric. A versão 2.0 e versões posteriores conectam-se pelo pyodbc driver, que é o padrão, ou pelo driver da mssql-python Microsoft.

Instale-o com pip:

pip install mssql-django

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

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 sua versão do Django: o Django 5.2 é testado com Python 3.10 a 3.13, e Django 6.0 e 6.1 são testados com Python 3.12 a 3.14. Consulte o ciclo de vida de suporte para a matriz de compatibilidade completa.

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

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

Aliases que omitem a opção continuam usando pyodbc. Para as diferenças de comportamento entre os dois caminhos, veja Selecionar o driver de banco de dados para mssql-django.

Sim. O mssql-django pacote é mantido por Microsoft e está disponível em PyPI e GitHub.

Defina ENGINE como "mssql" em sua DATABASES configuração:

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

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

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

O mssql-python caminho ignora a driver opção e usa o ODBC Driver 18 que pip instala com ele.

Use o nome do servidor totalmente qualificado 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",
        },
    },
}

Use extra_params em OPTIONS ou na configuração TOKEN. A TOKEN configuração funciona com qualquer azure.identity credencial, incluindo DefaultAzureCredential e ManagedIdentityCredential.

from azure.identity import DefaultAzureCredential

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

"TOKEN": token,

Consulte a autenticação do Microsoft Entra para conhecer todos os métodos com suporte.

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

Sim. Quando USE_TZ=True, o Django usa o tipo de dados datetimeoffset no SQL Server. Se você estiver migrando um banco de dados existente, precisará alterar as colunas datetime2 existentes. Consulte o suporte a fuso horário.

Sim. Use connection.cursor() com cursor.execute() para chamar procedimentos armazenados. Consulte procedimentos armazenados para obter exemplos, incluindo vários parâmetros e conjuntos de resultados.

Por predefinição, não. A return_rows_bulk_insert opção usa Falsecomo padrão . Defina isso como True em seu banco de dados OPTIONS para permitir o retorno de IDs após inserções em massa. Essa opção deve permanecer False para tabelas com gatilhos. Consulte operações em massa.

Instale o driver ODBC Microsoft para SQL Server. No Linux, adicione o repositório APT Microsoft primeiro e, em seguida, 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

Em Windows, baixe o instalador no site do Microsoft. No 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 obter instruções completas específicas da plataforma.

O SQL Server não dá suporte à alteração de uma coluna de ou para uma coluna IDENTITY (AutoField). Crie um novo modelo com o tipo de campo desejado e migre dados manualmente. Consulte Limitações e recursos sem suporte no mssql-django.

O backend processa automaticamente as atualizações com todos os valores NULL. Se você precisar controlar o valor do espaço reservado, use o parâmetro default em bulk_update, que mantém NULL fora das expressões CASE WHEN ... THEN NULL que causam erros de inferência de tipo no SQL Server:

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

Consulte Operações em massa para obter detalhes.