Limitações e funcionalidades não suportadas no mssql-django

Este artigo lista limitações do mssql-django backend quando utilizado com SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric.

Limitações das funcionalidades do Django

As seguintes funcionalidades do Django não são suportadas ou têm suporte limitado no mssql-django backend:

Característica Situação Detalhes
Avg com DurationField Não suportado 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 Azure SQL Managed Instance. O Base de Dados SQL do Azure não suporta assemblies CLR. Veja Configurar consultas de regex.
DISTINCT ON Não suportado O SQL Server não suporta DISTINCT ON cláusulas. Uso .values().distinct() ou subconsultas.
Subquery em ORDER BY Não suportado Ordenar por expressões de subconsulta pode não funcionar.
Nível de base de dados CASCADE Limitado Algumas SET NULL operações SET DEFAULT podem exigir migração manual do SQL.
is_dst em Trunc/Extract Não suportado is_dst (usado para resolver horários ambíguos durante as transições do horário de verão) em Extract() e Trunc() não é suportado. Use AT TIME ZONE em SQL bruto para consultas conscientes do DST.
Anotação de ponto flutuante Limitado Agregados de ponto Avg flutuante podem perder precisão em comparação com o 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,1500000000000000002222 em vez de exatamente 0,15. Use DecimalField ou Cast(avg_expr, output_field=DecimalField()) para cálculos financeiros críticos.
Anotar/existe em ORDER BY Não suportado Usar anotações ou expressões existentes pode order_by não funcionar.
Aritmética de potência e data da mão direita Não suportado Operações de potência à direita (por exemplo, F('value') ** 2 funciona mas 2 ** F('value') falha) e divisão com timedelta não são suportadas.
Fos horários e deltas temporais Limitado Os fusos horários e os deltas horários não são totalmente suportados. Veja Suporte a fusos horários no mssql-django.
NthValue Função janela Não suportado O SQL Server não suporta NTH_VALUE(). Use FIRST_VALUE, LAST_VALUE, ou uma subconsulta.
ignore_conflicts em bulk_create Não suportado bulk_create(objs, ignore_conflicts=True) não é suportado. O SQL Server não tem equivalente ao do PostgreSQLON CONFLICT DO NOTHING.
Pesquisa JSONField contains Não suportado Utilize em vez disso consultas por caminhos de chave (por exemplo, filter(metadata__color="blue")). Ver limitações do JSONField.
select_for_update(of=(...)) Não suportado O SQL Server não suporta bloquear tabelas específicas. O backend levanta NotSupportedError. Ver Gestão de transações.

Limitações da migração

Limitação Detalhes
Alter AutoField Não é possível alterar um campo para ou de AutoField (IDENTITY coluna). Requer criar uma nova tabela.
Renomeação com chaves estrangeiras Renomear uma coluna que tenha restrições de chave estrangeira pode falhar. Utilize SeparateDatabaseAndState.
AddConstraint / RemoveConstraint Conflitos Algumas operações de restrição podem entrar em conflito. Candidata-te em migrações separadas.
Operações de extração de datas ExtractYear, ExtractMonth, e operações semelhantes têm apoio limitado tzinfo .

Limitações do JSONField

  • mssql-djangoMapa JSONField para Nvarchar(Max). O SQL Server 2025 introduziu um tipo nativo json, mas o driver Microsoft ODBC para SQL Server não o expõe.
  • A contains pesquisa não é suportada. Utilize em vez disso consultas por caminhos de chave (por exemplo, filter(metadata__color="blue")).
  • Os valores das cadeias entre aspas retornam com aspas extra (por exemplo, '"value"' em vez de 'value').
  • Algumas pesquisas aninhadas podem comportar-se de forma diferente do PostgreSQL.
  • Para mais informações, consulte JSONField com SQL Server.

Limitações do InspectDB

  • As 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.
  • Rever e ajustar manualmente os modelos gerados.
  • Para mais informações, veja Engenharia inversa 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. Este limite afeta operações de Django que geram consultas parametrizadas com listas de valores grandes:

Operação Como atinge o limite
filter(field__in=large_list) Cada item da lista torna-se um parâmetro. O backend otimiza automaticamente mais de 2.048 itens numa 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.

Define batch_size operações em massa e IN divide grandes consultas. Consulte afinação de desempenho para soluções.

Limitações das operações em massa

Limitações do quadro de teste

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

Para mais informações, consulte Testar aplicações Django com SQL Server.

Notas específicas de versão

Versão mssql-django Notes
1.7.3 Corrigido FA001 para Authentication= modos diferentes de ActiveDirectoryMsi. 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 corrigida .explain() para Django 4.0 e versões posteriores.
1.7.1 Correção da base de dados SQL no Fabric (EngineEdition 12). Correção de índice AlterField descendente.
1.7 O ODBC Driver 18 é o padrão. Adicionados suportes para Django 6.0, Python 3.14, SQL Server 2025.
1.6 Suporte para Django 5.1 e 5.2. Funcionalidade JSON melhorada.
1.5 Correções de bugs para AutoField, formatação de parâmetros e consultas de esquema.
1.4 Suporte para Django 5.0. db_comment assistência.
1.3 Suporte para Django 4.2.
1.2 Suporte para Django 4.1. Suporte para fusos horários. return_rows_bulk_insert opção. Suporte ao SQL Server 2022.
1.1 Suporte para Django 3.2 e 4.0.

Notas específicas da versão Django

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

Configurar consultas de regex

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

Pré-requisitos

  • Uma instância do SQL Server que suporta integração com CLR. O SQL Server on-premises e o Azure SQL Managed Instance suportam CLR. O Base de Dados SQL do Azure não suporta assemblies CLR, por isso __regex__iregex as consultas não estão disponíveis no Base de Dados SQL do Azure.
  • O utilizador que se liga deve ter sysadmin uma permissão ALTER SETTINGS . O comando de gestão ativa automaticamente o CLR.
  • A mssql aplicação deve estar em INSTALLED_APPS.

Instalar o conjunto CLR

Execute o comando de gestão, passando o nome da sua base de dados:

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

Este comando executa os seguintes passos:

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

Caution

Definir clr strict security para 0 permite carregar assemblies CLR sem sinal. Isto é obrigatório porque o pacote regex_clr.dll não está assinado. Discuta esta alteração com o seu DBA antes de executar o comando em servidores de produção. A definição aplica-se a todo o servidor, não a cada base de dados.

Usar consultas regulares

Após instalar o conjunto, 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 estas consultas para dbo.REGEXP_LIKE(column, pattern, case_flag) = 1.

Note

Deve executar o install_regex_clr comando uma vez por base de dados. Se a base de dados for descartada e recriada (por exemplo, durante os testes), execute novamente o comando.

Conteúdo relacionado

  • Last updated on