Limitações e recursos não suportados no mssql-django

Este artigo lista limitações do mssql-django backend quando usado com SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric.

Limitações das funcionalidades do Django

Os seguintes recursos do Django não são suportados ou têm suporte limitado no mssql-django backend:

Característica Status Detalhes
Avg com DurationField Sem suporte Agregado Avg não funciona em DurationField.
__regex e __iregex consultas Requer configuração Suportado após instalar o assembly CLR no SQL Server ou Instância Gerenciada de SQL do Azure. Banco de Dados SQL do Azure não suporta assemblies CLR. Veja Configurar consultas regulares.
DISTINCT ON Sem suporte O SQL Server não suporta DISTINCT ON cláusulas. Uso .values().distinct() ou subconsultas.
Subquery em ORDER BY Sem suporte Ordenar por expressões de subconsulta pode não funcionar.
Nível de banco de dados CASCADE Limited Algumas SET NULL operações e SET DEFAULT podem exigir migração manual do SQL.
is_dst em Trunc/Extract Sem suporte is_dst (usado para resolver horários ambíguos durante transições no horário de verão) em Extract() e Trunc() não é suportado. Use AT TIME ZONE SQL bruto para consultas conscientes do DST.
Anotação de ponto flutuante Limited Agregados de ponto Avg flutuante podem perder precisão em comparação ao PostgreSQL devido ao comportamento do tipo float do SQL Server. Por exemplo, fazer uma média de 0,1 e 0,2 pode resultar em 0,150000000000000002222 em vez de exatamente 0,15. Use DecimalField ou Cast(avg_expr, output_field=DecimalField()) para cálculos financeiros críticos.
Anotar/existir em ORDER BY Sem suporte Usar anotações ou expressões existentes pode order_by não funcionar.
Aritmética de potência e data da mão direita Sem suporte Operações de potência à direita (por exemplo, F('value') ** 2 funciona, mas 2 ** F('value') falham) e divisão com timedelta não são suportadas.
Fos horários e deltas horários Limited Fuso horário e deltas de tempo não são totalmente suportados. Veja Suporte a fusos horários no mssql-django.
NthValue Função janela Sem suporte O SQL Server não suporta NTH_VALUE(). Use FIRST_VALUE, LAST_VALUE, ou uma subconsulta.
ignore_conflicts em bulk_create Sem suporte Não há suporte para bulk_create(objs, ignore_conflicts=True). O SQL Server não tem equivalente ao arquivo de .ON CONFLICT DO NOTHING
Consulta JSONField contains Sem suporte Use buscas por caminho de chave (por exemplo, filter(metadata__color="blue")). Veja limitações do JSONField.
select_for_update(of=(...)) Sem suporte O SQL Server não suporta travar tabelas específicas. O backend levanta NotSupportedError. Veja Gerenciamento de transações.

Limitações da migração

Limitation Detalhes
Alter AutoField Não é possível mudar um campo para ou de AutoField (IDENTITY coluna). Exige criar uma nova tabela.
Renomeação com chaves estrangeiras Renomear uma coluna que possui restrições de chave estrangeira pode falhar. Use SeparateDatabaseAndState.
AddConstraint / RemoveConstraint Conflitos Algumas operações de restrição podem entrar em conflito. Solicite em migrações separadas.
Operações de extração de data ExtractYear, ExtractMonth, e operações similares têm suporte limitado tzinfo .

Limitações do JSONField

  • mssql-djangoMapeia JSONField para Nvarchar(Max). O SQL Server 2025 introduziu um tipo nativo de json, mas o driver ODBC da Microsoft para SQL Server não o expõe.
  • A contains consulta não é suportada. Use buscas por caminho de chave (por exemplo, filter(metadata__color="blue")).
  • Os valores de string entre aspas retornam com aspas extras (por exemplo, '"value"' em vez de 'value').
  • Algumas buscas aninhadas podem se comportar de forma diferente do PostgreSQL.
  • Para mais informações, veja JSONField com SQL Server.

Limitações do InspectDB

  • Chaves primárias compostas não são geradas automaticamente unique_together .
  • Alguns tipos de colunas específicos do SQL Server podem mapear para campos genéricos do Django.
  • Revise e ajuste manualmente os modelos gerados.
  • Para mais informações, veja Engenharia reversa de modelos com inspectdb.

Limite de parâmetros do SQL Server

O SQL Server limita cada consulta a um máximo de 2.100 parâmetros. Esse limite afeta operações de Django que geram consultas parametrizadas com listas de valores grandes:

Operation Como ele atinge o limite
filter(field__in=large_list) Cada item da lista se torna um parâmetro. O backend automaticamente lista mais de 2.048 itens em uma tabela temporária.
prefetch_related() Cada ID de objeto pai torna-se um parâmetro na cláusula da consulta WHERE IN relacionada. Auto-otimizado como filter(field__in=...) quando ultrapassa 2.048 IDs.
bulk_create() Cada campo de cada objeto torna-se um parâmetro. Um modelo com 10 campos e 250 objetos gera 2.500 parâmetros.
bulk_update() Cada campo usa dois parâmetros por objeto (um para a correspondência PK, outro para o valor).
Q() com muitas condições Cada valor em objetos encadeados Q torna-se um parâmetro.

Defina batch_size operações em massa e faça IN grandes consultas. Veja Ajuste de Performance para soluções.

Limitações das operações em massa

Limitações do framework de teste

--keepdb é necessário ao usar autenticação de identidade gerenciada (ActiveDirectoryMsi) porque o executor de testes não pode criar ou destruir bancos de dados com esse método de autenticação.

Para mais informações, veja Teste aplicativos Django com SQL Server.

Notas específicas de versão

Versão MSSQL-Django Observações
1.7.3 Fixo FA001 para Authentication= modos diferentes ActiveDirectoryMside . Fixo KeyError em subclasses DatabaseWrapper (regressão a partir da 1.7.1).
1.7.2 Tratamento fixo do fuso horário para datatimeoffset e Now() com USE_TZ=True. Compatibilidade consertada .explain() para Django 4.0 e versões posteriores.
1.7.1 Correção do banco de dados SQL no Fabric (EngineEdition 12). Correção do índice AlterField descendente.
1.7 O ODBC Driver 18 é o padrão. Django 6.0, Python 3.14, suporte ao SQL Server 2025 adicionado.
1.6 Suporte para Django 5.1 e 5.2. Funcionalidade JSON aprimorada.
1.5 Correções de bugs para AutoField, formatação de parâmetros e consultas de esquema.
1.4 Suporte ao Django 5.0. db_comment suporte.
1.3 Suporte para Django 4.2.
1.2 Suporte para Django 4.1. Suporte para fusos horários. return_rows_bulk_insert Option. Suporte ao SQL Server 2022.
1.1 Suporte para Django 3.2 e 4.0.

Notas específicas de versão de Django

Versão de Django Observações
5.1 inspectdb Pode inspecionar tabelas com chaves primárias compostas, mas não gera definições completas de modelo para elas.
5.2 CompositePrimaryKey O apoio é parcial. inspectdb ainda requer correções manuais, comparação de tuplas com subconsultas exige Django 5.2.4 e versões posteriores, e algumas migrações além dos caminhos de atualização em massa do JSONField CASE WHEN ainda têm exclusões de teste. Para mais informações, veja o repositório GitHub.
6.0 Requer Python 3.12 e versões posteriores. Todas as limitações da 5.2 se aplicam. O backend lida com todas as alterações da API 6.0 de forma transparente.

Configurar consultas regulares

O mssql-django backend suporta Django __regex e __iregex buscas, mas eles exigem uma etapa única de configuração. O backend vem um assembly CLR (regex_clr.dll) que fornece uma dbo.REGEXP_LIKE função para o SQL Server.

Pré-requisitos

  • Uma instância do SQL Server que suporta integração com CLR. O SQL Server on-premises e o Instância Gerenciada de SQL do Azure suportam CLR. Banco de Dados SQL do Azure não suporta assemblies CLR, então __regex__iregex e consultas não estão disponíveis no Banco de Dados SQL do Azure.
  • O usuário que se conecta deve ter sysadmin uma permissão ALTER SETTINGS . O comando de gerenciamento ativa automaticamente o CLR.
  • O mssql aplicativo deve estar em INSTALLED_APPS.

Instale o conjunto CLR

Execute o comando de gerenciamento, passando o nome do seu banco de dados:

python manage.py install_regex_clr <your-database-name>

Esse comando executa os seguintes passos:

  1. Ativa o CLR no servidor (sp_configure 'clr enabled', 1) se ainda não estiver ativado.
  2. Define clr strict security para 0 (necessário para SAFE assemblies no SQL Server 2017+).
  3. Cria o regex_clr assembly a partir da DLL agrupada.
  4. Cria a dbo.REGEXP_LIKE função escalar.

Cuidado

Configurar clr strict security para 0 permite que assemblies CLR sem sinal sejam carregados. Isso é obrigatório porque o pacote regex_clr.dll não é assinado. Discuta essa mudança com seu DBA antes de executar o comando em servidores de produção. A configuração se aplica a todo o servidor, não a cada banco de dados.

Use consultas regulares

Após instalar o monte, use __regex e __iregex nos conjuntos de consultas:

# Case-sensitive regex
products = Product.objects.filter(name__regex=r"^Widget \d+$")

# Case-insensitive regex
products = Product.objects.filter(name__iregex=r"^widget \d+$")

O backend traduz essas consultas para dbo.REGEXP_LIKE(column, pattern, case_flag) = 1.

Note

Você deve executar o install_regex_clr comando uma vez por banco de dados. Se o banco de dados for descartado e recriado (por exemplo, durante os testes), execute o comando novamente.

Conteúdo relacionado

  • Last updated on