Novidades no mssql-django

Este artigo descreve novas funcionalidades, melhorias e alterações em cada versão do backend da mssql-django base de dados Django.

Versão 2.0

Data de lançamento: setembro de 2026

A versão 2.0 adiciona o controlador mssql-python da Microsoft como alternativa ao nível da base de dados a pyodbc, atualiza a matriz de compatibilidade de Python, Django e SQL Server e inclui correções de compatibilidade e fiabilidade. pyodbc continua a ser o driver padrão.

Destaques

  • suporte para o controlador mssql-python: Um alias de base de dados adere com "python_driver": "mssql_python" no seu dicionário OPTIONS. O driver cobre conexões, agrupamento de conexões, novas tentativas, transações e pontos de restauro, valores datetimeoffset, introspeção e a autenticação Microsoft Entra. Os pseudónimos que omitem a opção continuam a usar pyodbc, por isso nada muda até te inscreveres. Para mais informações, consulte Selecionar o driver da base de dados para mssql-django.
  • Não é necessária uma instalação separada do controlador ODBC ao usar o mssql-python: Um alias em mssql-python não precisa de um Controlador ODBC da Microsoft para SQL Server instalado à parte. Os pseudónimos que continuam em pyodbc continuam a fazê-lo.
  • Matriz de suporte modernizada: Python 3.10 a 3.14, Django 5.2 a 6.1, e SQL Server 2017 a 2025. O Django 6.0 e versões posteriores requerem Python 3.12 ou posteriores.

Correções de erros

  • As definições explícitas do MARS são respeitadas: Um valor explícito MARS_Connection em extra_params é preservado em vez de ser sobrescrito pelo padrão do Windows, e a correspondência ignora o caso. A configuração MARS_Connection=no agora funciona contra endpoints que rejeitam o MARS, incluindo o Microsoft Fabric Warehouse. Com o MARS desativado, a iteração do ORM armazena os resultados antes de os fornecer, para que uma consulta aninhada possa reutilizar a ligação, o que consome mais memória em grandes conjuntos de consultas. Esta correção de ligação não adiciona suporte total ao Warehouse para migrações ou outras funcionalidades do SQL Server.
  • Os carateres universais entre colchetes são escapados nas pesquisas de expressões: As pesquisas de padrões que comparam dois campos com uma expressão F(), como contains e startswith, escapam o caráter universal [ do SQL Server. Os caracteres entre parênteses são associados como dados em vez de como sintaxe coringa.
  • As aspas são escapadas nos nomes de esquemas no inspectdb: Uma aspa simples no valor inspectdb --schema é escapada na consulta de metadados, pelo que os nomes de esquemas que contêm uma aspa deixam de produzir instruções Transact-SQL (T-SQL) malformadas.
  • Um HOST vazio liga ao localhost no caminho mssql-python: A omissão de HOST, que o Django preenche como uma string vazia, é resolvida para localhost em vez de falhar na validação com um valor SERVER= vazio. Este comportamento corresponde ao pyodbc padrão para instâncias locais.

Improvements

  • O pytz foi substituído por zoneinfo e tzdata: A gestão dos fusos horários utiliza o módulo da biblioteca padrão zoneinfo, sendo o pacote tzdata responsável por fornecer a base de dados de fusos horários da IANA em ambientes que não a incluem, como o Windows e imagens de contentor mínimas. Os desvios mantêm-se corretos durante todo o ano para fusos horários com desvios negativos da hora de verão. pytz já não é uma dependência.
  • São aceites versões mais recentes do SQL Server: uma versão principal do SQL Server que o backend não reconhece utiliza o conjunto de capacidades mais recente que o backend conhece, em vez de falhar a validação da versão. Podes ligar-te a uma nova versão do SQL Server antes de uma versão correspondente mssql-django ser lançada. Aceitar a ligação não declara as funcionalidades não testadas como suportadas.

Alterações de grande impacto

  • Python 3.8 e 3.9, e Django 3.2 a 5.1, já não são suportados. O código de compatibilidade das versões anteriores mantém-se, mas essas combinações não são testadas nem listadas.
  • mssql-python 1.15.0 ou posterior é uma dependência obrigatória mesmo quando um alias usa pyodbc. A instalação está limitada a plataformas que tenham uma distribuição compatível mssql-python , excluindo o SUSE Linux no ARM64. Os projetos noutras plataformas mantêm-se na versão 1.8.0.
  • O suporte declarado ao SQL Server começa com o SQL Server 2017, e o suporte à conectividade nativa declarada está limitado ao Microsoft ODBC Driver 17 e ao Microsoft ODBC Driver 18.

Versão 1.8.0

Data de lançamento: agosto de 2026

A versão 1.8.0 adiciona suporte para Django 6.1, continuando a suportar Django 3.2 até 6.0. Mover um projeto do Django 6.0 para o 6.1 não requer alterações de código, a menos que utilize uma das duas funcionalidades do Django 6.1 descritas nesta secção.

Destaques

  • Suporte ao Django 6.1: Validado contra o Django 6.1 enquanto continua a apoiar o Django 3.2 até ao 6.0. A restrição de dependência alarga-se de django>=3.2,<6.1 para django>=3.2,<6.2.
  • O compilador de consultas usa quote_name no Django 6.1: o Django 6.1 descontinuou quote_name_unless_alias. O backend passa agora a chamar SQLCompiler.quote_name no Django 6.1 e em versões mais recentes, condicionado pela versão, pelo que as versões anteriores do Django permanecem inalteradas. Consultas fatiadas e deslocadas, como qs[a:b] e OFFSET ... FETCH, compilam sem avisos de depreciação.
  • A introspeção de chaves estrangeiras passa a devolver a regra ON DELETE: o Django 6.1 expandiu get_relations() para incluir a regra ON DELETE ao nível da base de dados. O backend retorna a estrutura de três partes esperada e mapeia as chaves estrangeiras do SQL Server NO ACTION em conformidade, pelo que inspectdb e a introspeção de chaves estrangeiras produzem modelos corretos.

Funcionalidades do Django 6.1 que não são suportadas

Duas adições do Django 6.1 não estão disponíveis neste backend, por razões diferentes:

  • Ações referenciais ao nível da base de dados (DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT): o SQL Server rejeita grafos de chave estrangeira com múltiplos caminhos em cascata para a mesma tabela (erro 1785), pelo que não existe um caminho nativo para esta funcionalidade em nenhuma versão do SQL Server. Usar um destes valores eleva a verificação fields.E324do sistema Django , que o aponta para o nível on_deletepadrão de Django .
  • Agregações bit a bit (BitAnd, BitOr, BitXor): o SQL Server não tem funções nativas de agregação bit a bit, e o backend não as emula, pelo que estas agregações geram NotSupportedError.

Para mais informações, consulte Limitações e funcionalidades não suportadas no mssql-django.

Versão 1.7.4

Data de lançamento: julho de 2026

A versão 1.7.4 é uma atualização retrocompatível com duas correções para o tratamento de consultas brutas e anotadas GROUP BY .

Correções de erros

  • IndexError em consultas GROUP BY com parâmetros com escape %% e parâmetros reais: Anteriormente, qualquer consulta com uma cláusula GROUP BY passava por uma etapa de reescrita de marcadores de posição que correspondia a %\w+ e o substituía por {}. Esse regex também fazia correspondência com literais com escape %%, o que injetava placeholders fantasma e gerava IndexError: Replacement index N out of range sempre que uma consulta combinava um escape %% com um parâmetro real %s. A expressão regular, agora mais restrita, afeta apenas %% (preservado literalmente) e %s (o verdadeiro marcador de posição), que é o único padrão que o compilador alguma vez gera. A mesma correção também evita um bug silencioso não relacionado, em que um padrão não escapado, como LIKE '%abc%', numa consulta sem parâmetros, foi reescrito para LIKE '{}%' e devolveu as linhas erradas.
  • NotImplementedError para IntegerChoices em consultas GROUP BY em bruto: Anteriormente, passar um valor IntegerChoices para uma consulta em bruto que continha uma cláusula GROUP BY gerava NotImplementedError: Not supported type <enum ...>. O auxiliar de tipagem do parâmetro usava verificações exatas de tipo (typ == int), e type(IntegerChoices_value) é a classe de enumeração em vez de int, pelo que o valor acabou por chegar à instrução raise, embora seja uma subclasse de int. As verificações de tipo agora usam isinstance, e o ramo bool é avaliado antes do int ramo (porque bool é ela própria uma int subclasse). As escolhas de enum agora associam-se corretamente, bool continua a associar BIT, e o simples int mantém-se inalterado.

Versão 1.7.3

Data de lançamento: junho de 2026

A versão 1.7.3 é uma versão de patch retrocompatível com duas correções de ligação e runtime.

Correções de erros

  • FA001 para Authentication= modos que não sejam ActiveDirectoryMsi: Anteriormente, o back-end ignorava Trusted_Connection=yes apenas para ActiveDirectoryMsi. Outros modos Entra que não fornecem um USER valor (por exemplo, ActiveDirectoryIntegrated, ActiveDirectoryDefault, ActiveDirectoryDeviceFlow) ainda receberam Trusted_Connection=yes, que o driver ODBC rejeitou com FA001 (Cannot use Authentication option with Integrated Security option). A correção deteta qualquer valor explícito Authentication= com uma correspondência que tem em conta os limites e sem distinção entre maiúsculas e minúsculas, e ignora tanto Trusted_Connection como Integrated Security=SSPI. O tratamento das palavras-passe mantém-se inalterado: SqlPassword, ActiveDirectoryPassword e ActiveDirectoryServicePrincipal continuam a enviar PWD, enquanto ActiveDirectoryInteractive continua a omiti-lo.
  • KeyError na subclasse DatabaseWrapper: As propriedades cache sql_server_version e to_azure_sql_db dependiam da type(self).__dict__ introspeção de cached_property, que surgiu KeyError na primeira vez que uma DatabaseWrapper subclasse as acedeu (uma regressão introduzida na 1.7.1). A correção usa dicts explícitos ao nível da classe (_known_versions, _known_azures) acedidos através de self., pelo que a pesquisa resolve-se através do MRO e os wrappers subclassados funcionam corretamente.

Versão 1.7.2

Data de lançamento: maio de 2026

A versão 1.7.2 é um patch retrocompatível com correções de fuso horário e compatibilidade.

Correções de erros

  • .explain() compatibilidade com Django 4.0 e posteriores: Corrigido o processamento, pelo compilador, dos metadados de explain do Django para que .explain() deixe de falhar com AttributeError no Django 4.0 e posteriores. O backend agora segue campos explicativos apropriados à versão e levanta NotSupportedError corretamente quando necessário.
  • processamento do fuso horário de datetimeoffset: Corrigida a análise de datetimeoffset para que os offsets de fuso horário sejam preservados em vez de serem descartados. Os valores de data e hora devolvidos incluem agora informação de fuso horário, quando esperado.
  • Now() com USE_TZ=True: Geração de SQL atualizada para Now() utilizar um comportamento sensível ao fuso horário quando o suporte a fusos horários está ativado, evitando desvios de carimbos temporais em anfitriões do SQL Server que não utilizam UTC.

Versão 1.7.1

Data de lançamento: abril de 2026

A versão 1.7.1 é uma atualização retrocompatível com correções de bugs.

Correções de erros

  • FieldDoesNotExist ao alterar campos com ordenação de índice decrescente: Fixado _alter_field() em schema.py para usar index.fields_orders em vez de index.fields ao resolver nomes de campos de índice. O código anterior passava cadeias brutas de campo com ordenação (por exemplo, "-pub_date") para model._meta.get_field(), o que elevava FieldDoesNotExist. Agora, apenas o nome do campo é extraído e o sufixo de ordenação é corretamente removido.
  • Suporte para base de dados SQL no Microsoft Fabric (EngineEdition 12): Reconheceu a base de dados SQL no Fabric (EngineEdition=12) como uma edição Azure. Anteriormente, a edição do motor Fabric não era reconhecida, fazendo com que to_azure_sql_db devolvesse False e que as verificações de controlo de funcionalidades falhassem. A correção adiciona EDITION_AZURE_SQL_FABRIC=12_AZURE_EDITIONS e mapeia o Fabric para a versão mais recente suportada do SQL Server. JSONField, funções hash, introspeção de ordenação e eliminação da base de dados de teste funcionam agora corretamente no Fabric.

Versão 1.7

Data de lançamento: março de 2026

Destaques

  • Suporte para Django 6.0: Compatibilidade total com Django 6.0, que requer Python 3.12 ou posterior. Todas as alterações à API 6.0 são tratadas de forma transparente pelo backend.
  • Suporte parcialCompositePrimaryKey: O backend adiciona suporte parcial para Django 5.2CompositePrimaryKey. A comparação de tuplos com subconsultas requer o Django 5.2.4 ou versão posterior, e alguns casos limite de chaves compostas e de JSONField permanecem. O próprio Django 5.2 foi inicialmente suportado no mssql-django 1.6.
  • Suporte ao SQL Server 2025: Validado contra o SQL Server 2025.
  • ODBC Driver 18 predefinido: O backend passa agora a predefinir o ODBC Driver 18 para o SQL Server, com reversão automática para o ODBC Driver 17 se a versão 18 não estiver instalada.

Notas específicas de versão

Versão Django Notes
Django 5.1 inspectdb Pode inspecionar tabelas com chaves primárias compostas, mas não gera definições completas do modelo para elas.
Django 5.2 CompositePrimaryKey O apoio é parcial. A comparação de tuplos com subconsultas requer o Django 5.2.4 ou posterior, e continuam a existir alguns casos limite de migração, além de JSONField.
Django 6.0 Requer Python 3.12 ou posterior. Todas as limitações 5.2 aplicam-se.

Versão 1.6

Data de lançamento: agosto de 2025

  • Adicionei suporte para Django 5.1 e 5.2.
  • Funcionalidade JSON melhorada e compatibilidade retroativa.
  • Melhoria da infraestrutura do oleoduto.

Versão 1.5

Data de lançamento: abril de 2024

  • Adicionado supports_comments um flag de funcionalidade para db_comments.
  • Correções de erros para AutoField, formatação de parâmetros e consultas de esquema.

(Versão 1.4)

Data de lançamento: janeiro de 2024

  • Adicionei suporte ao Django 5.0.
  • Adicionado suporte db_comment.
  • Correções de bugs para conversões de data/hora e agregados vazios.

Versão 1.3

Data de lançamento: maio de 2023

  • Adicionei suporte ao Django 4.2.
  • Adicionado suporte a funções Replace que diferenciam maiúsculas de minúsculas.
  • Correções de erros no tratamento de OFFSET e no preenchimento à esquerda.

Versão 1.2

Data de lançamento: dezembro de 2022

  • Adicionei suporte ao Django 4.1.
  • Adicionado suporte a fusos horários (datetimeoffset com USE_TZ=True).
  • Adicionou-se a opção return_rows_bulk_insert para obtenção dos IDs de inserções em massa.
  • Adicionei suporte ao SQL Server 2022.
  • Adicionado o JSONField suporte ao Azure SQL Managed Instance.

Versão 1.1

Data de lançamento: julho de 2022

  • Suporte para Django 3.2 e 4.0.
  • SQL Server 2016 e posteriores, e suporte ao Base de Dados SQL do Azure.
  • conectividade baseada em pyodbc.

Conteúdo relacionado

  • Last updated on