Novidades no mssql-django

Este artigo descreve novos recursos, melhorias e alterações em cada versão do back-end do banco de dados do mssql-django Django.

Versão 2,0

Data de lançamento: setembro de 2026

A versão 2.0 adiciona o driver da Microsoft mssql-python como alternativa por banco de dados ao pyodbc, atualiza a matriz de suporte do Python, Django e SQL Server e inclui correções de compatibilidade e confiabilidade. pyodbc continua sendo o driver padrão.

Destaques

  • Suporte ao driver mssql-python: um alias de banco de dados é aceito com "python_driver": "mssql_python" no dicionário OPTIONS. O driver cobre conexões, pool de conexões, novas tentativas, transações e pontos de salvamento, valores datetimeoffset, introspecção e autenticação da Microsoft Entra. Aliases que omitem a opção continuam usando pyodbc, então nada muda até você aderir. Para mais informações, veja Selecionar o driver de banco de dados para mssql-django.
  • Não é necessária uma instalação separada do driver ODBC no caminho do mssql-python: Um alias em mssql-python não precisa de um driver ODBC da Microsoft para SQL Server instalado externamente. Aliases que permanecem ativados pyodbc ainda são aceitos.
  • Matriz de suporte modernizada: Python 3.10 a 3.14, Django 5.2 a 6.1 e SQL Server 2017 a 2025. Django 6.0 e versões posteriores exigem Python 3.12 ou posteriores.

Correções de erros

  • Configurações explícitas de MARS são respeitadas: um valor explícito MARS_Connection em extra_params é preservado em vez de ser substituído pelo padrão do Windows, e a correspondência não diferencia maiúsculas de minúsculas. A configuração MARS_Connection=no agora funciona contra endpoints que rejeitam o MARS, incluindo o Microsoft Fabric Warehouse. Com o MARS desativado, o ORM armazena em buffer os resultados da iteração antes de retorná-los, para que uma consulta aninhada possa reutilizar a conexão, o que consome mais memória em querysets grandes. Essa correção de conexão não adiciona suporte total ao Warehouse para migrações ou outros recursos do SQL Server.
  • Caracteres curinga entre colchetes são escapados em pesquisas de expressão: Pesquisas por padrão que comparam dois campos com a expressão F(), como contains e startswith, escapam o caractere curinga [ do SQL Server. Os caracteres de colchetes são tratados como dados em vez de como sintaxe de caractere curinga.
  • As aspas são escapadas nos nomes de esquema do inspectdb: Uma aspa simples no valor inspectdb --schema é escapada na consulta de metadados, de modo que nomes de esquema que contêm uma aspas simples não produzam mais Transact-SQL (T-SQL) malformado.
  • Um HOST vazio se conecta ao localhost na implementação mssql-python: A tag HOST omitida, que o Django preenche com uma string vazia, resulta em localhost em vez de falhar na validação com um valor vazio de SERVER=. Esse comportamento corresponde ao pyodbc padrão para instâncias locais.

Improvements

  • pytz substituído por zoneinfo e tzdata: O tratamento de fusos horários usa o módulo zoneinfo da biblioteca padrão, com o pacote tzdata fornecendo o banco de dados de fusos horários da IANA em ambientes que não incluem esse banco de dados, como o Windows e imagens mínimas de contêiner. Os deslocamentos permanecem corretos ao longo do ano para fusos horários com deslocamento negativo no horário de verão. pytz não é mais uma dependência.
  • Versões mais recentes do SQL Server são aceitas: uma versão principal do SQL Server que o backend não reconhece usa o conjunto de capacidades mais recente que o backend conhece, em vez de falhar na validação da versão. Você pode se conectar a uma nova versão do SQL Server antes que uma versão correspondente mssql-django seja lançada. Aceitar a conexão não declara recursos não testados como suportados.

Alterações críticas

  • Python 3.8 e 3.9, e Django 3.2 a 5.1, não são mais suportados. O código de compatibilidade das versões anteriores permanece em uso, 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 é limitada a plataformas que possuem uma distribuição compatível mssql-python , excluindo o SUSE Linux no ARM64. Projetos em outras plataformas permanecem 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 é limitado ao Microsoft ODBC Driver 17 e 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 enquanto continua 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 você use um dos dois recursos do Django 6.1 descritos nesta seção.

Destaques

  • Suporte ao Django 6.1: Validado contra o Django 6.1 enquanto continua a apoiar o Django 3.2 até o 6.0. A restrição de dependência se amplia 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 marcou quote_name_unless_alias como obsoleto. O backend agora chama SQLCompiler.quote_name no Django 6.1 e em versões posteriores, condicionado à versão, de modo que as versões anteriores do Django permaneçam inalteradas. Consultas fatiadas e deslocadas, como qs[a:b] e OFFSET ... FETCH, compilam sem avisos de depreciação.
  • A introspecção de chaves estrangeiras retorna a regra ON DELETE: o Django 6.1 expandiu get_relations() para incluir a regra ON DELETE no nível do banco de dados. O backend retorna a estrutura esperada de três partes e mapeia corretamente as chaves estrangeiras do SQL Server NO ACTION, de modo que inspectdb e a introspecção de chaves estrangeiras produzam modelos corretos.

Recursos do Django 6.1 que não são suportados

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

  • Ações referenciais em nível de banco de dados (DB_CASCADE, DB_SET_NULL, DB_SET_DEFAULT): SQL Server rejeita grafos de chave estrangeira com múltiplos caminhos em cascata para a mesma tabela (erro 1785), então não há caminho nativo para esse recurso em nenhuma versão do SQL Server. Usar um desses valores eleva a verificação fields.E324do sistema Django , que aponta para o nível on_deletepadrão de Django .
  • Agregações bit a bit (BitAnd, BitOr, BitXor): o SQL Server não possui função nativa de agregação bit a bit, e o backend não as emula, portanto essas agregações geram NotSupportedError.

Para obter mais informações, consulte Limitações e recursos sem suporte no mssql-django.

Versão 1.7.4

Data de lançamento: julho de 2026

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

Correções de erros

  • IndexError em consultas GROUP BY com %% com escape e parâmetros reais: anteriormente, qualquer consulta com uma cláusula GROUP BY passava por uma etapa de reescrita de placeholders que identificava padrões como %\w+ e os substituía por {}. Essa expressão regular também identificava literais %% com escape, inserindo placeholders fictícios e gerando IndexError: Replacement index N out of range sempre que uma consulta combinava um %% com escape com um parâmetro %s real. A expressão regular mais restrita agora afeta apenas %% (preservado literalmente) e %s (o verdadeiro marcador de posição), que é o único padrão que o compilador emite. A mesma correção também evita um bug silencioso não relacionado, no qual um padrão sem escape, como LIKE '%abc%', em uma consulta sem parâmetros, era regravado como LIKE '{}%' e exibia linhas incorretas.
  • NotImplementedError para IntegerChoices em consultas GROUP BY brutas: Anteriormente, passar um valor IntegerChoices para uma consulta bruta que continha uma cláusula GROUP BY gerava NotImplementedError: Not supported type <enum ...>. O auxiliar de tipagem de parâmetros usava verificações exatas de tipo (typ == int), e type(IntegerChoices_value) corresponde à classe do enum, e não a int. Por isso, o valor acabava chegando à exceção, mesmo sendo uma subclasse de int. As verificações de tipo agora usam isinstance, e o ramo bool é avaliado antes do ramo int (porque bool é, ele próprio, uma subclasse de int). As opções de enum agora são associadas corretamente, bool ainda se associa a BIT, e o int simples permanece inalterado.

Versão 1.7.3

Data de lançamento: junho de 2026

A versão 1.7.3 é uma atualização de patch compatível com versões anteriores, com duas correções relacionadas à conexão e ao tempo de execução.

Correções de erros

  • FA001 para modos de Authentication= diferentes de ActiveDirectoryMsi: anteriormente, o backend ignorava Trusted_Connection=yes apenas para ActiveDirectoryMsi. Outros modos do Entra que não fornecem um valor USER (por exemplo, ActiveDirectoryIntegrated, ActiveDirectoryDefault, ActiveDirectoryDeviceFlow) ainda recebiam Trusted_Connection=yes, que o driver ODBC rejeitava com o erro FA001 (Cannot use Authentication option with Integrated Security option). A correção detecta qualquer valor Authentication= explícito com uma correspondência que diferencia maiúsculas de minúscula com reconhecimento de limite e ignora Trusted_Connection e Integrated Security=SSPI. O tratamento de senhas permanece inalterado: SqlPassword, ActiveDirectoryPassword, e ActiveDirectoryServicePrincipal continuam a enviar PWD, enquanto ActiveDirectoryInteractive continua a omitê-lo.
  • KeyError em subclasses de DatabaseWrapper: As propriedades em cache sql_server_version e to_azure_sql_db dependiam da introspecção de type(self).__dict__ de cached_property, o que gerava KeyError na primeira vez que uma subclasse de DatabaseWrapper as acessava (uma regressão introduzida na versão 1.7.1). A correção usa dicionários explícitos de nível da classe (_known_versions, _known_azures), acessados por meio de self., de modo que a pesquisa seja resolvida por meio de MRO e os wrappers em subclasses funcionem corretamente.

Versão 1.7.2

Data de lançamento: maio de 2026

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

Correções de erros

  • .explain() compatibilidade com o Django 4.0 e versões posteriores: Corrigido o tratamento do compilador dos metadados de explain do Django para que .explain() não falhe mais com AttributeError no Django 4.0 e versões posteriores. O back-end agora segue os campos de explicação adequados para a versão e gera corretamente NotSupportedError quando necessário.
  • Tratamento de fuso horário de datetimeoffset: correção da análise de datetimeoffset para que os deslocamentos de fuso horário sejam preservados em vez de descartados. As datas e as horas retornadas agora incluem informações de fuso horário quando esperado.
  • Now() com USE_TZ=True: geração de SQL atualizada de Now() para usar um comportamento de reconhecimento de fuso horário quando o suporte a fuso horário estiver habilitado, evitando descompassos de carimbo de data/hora em hosts do SQL Server que não usam UTC.

Versão 1.7.1

Data de lançamento: abril de 2026

A versão 1.7.1 é um lançamento de correção compatível com versões anteriores, com correções de bugs.

Correções de erros

  • FieldDoesNotExist ao alterar campos com ordenação decrescente de índice: Corrigido _alter_field() em schema.py para usar index.fields_orders em vez de index.fields ao resolver os nomes dos campos de índice. O código anterior passou campo bruto com ordenação de cadeias de caracteres (por exemplo, "-pub_date") para model._meta.get_field(), o que gerou FieldDoesNotExist. Agora, somente o nome do campo é extraído, e o sufixo de ordenação é descartado corretamente.
  • Suporte ao Banco de Dados SQL no Microsoft Fabric (EngineEdition 12): reconhecimento do Banco de Dados SQL no Fabric (EngineEdition=12) como uma edição do Azure. Anteriormente, a edição do mecanismo do Fabric não era reconhecida, fazendo com que to_azure_sql_db retornasse False e que as verificações de feature gate falhassem. A correção adiciona EDITION_AZURE_SQL_FABRIC=12_AZURE_EDITIONS e mapeia Fabric à versão de SQL Server com suporte mais recente. JSONField, as funções de hash, a introspecção de ordenação e a desmontagem do banco de dados de teste agora funcionam corretamente no Fabric.

Versão 1.7

Data de lançamento: março de 2026

Destaques

  • Suporte ao Django 6.0: compatibilidade completa com o Django 6.0, que requer Python 3.12 ou posterior. Todas as alterações de API 6.0 são tratadas de forma transparente pelo back-end.
  • Suporte parcialCompositePrimaryKey: o back-end adiciona suporte parcial ao Django 5.2 CompositePrimaryKey. A comparação de tuplas em relação às subconsultas requer o Django 5.2.4 ou versões posteriores, e alguns casos extremos envolvendo chaves compostas e casos de borda JSONField permanecem. O próprio Django 5.2 foi apoiado pela primeira vez no mssql-django 1.6.
  • Suporte ao SQL Server 2025: Validado para SQL Server 2025.
  • ODBC Driver 18 como padrão: o backend agora passa a usar por padrão o ODBC Driver 18 para SQL Server, com fallback automático para o ODBC Driver 17 se a versão 18 não estiver instalada.

Notas específicas da versão

Versão do Django Observações
Django 5.1 inspectdb pode inspecionar tabelas com chaves primárias compostas, mas não gera definições de modelo completas para elas.
Django 5.2 CompositePrimaryKey o suporte é parcial. A comparação de tuplas com subconsultas requer o Django 5.2.4 ou superior, e ainda há alguns casos de borda JSONField mais migração permanecem.
Django 6.0 Requer Python 3.12 ou posterior. Todas as limitações 5.2 se aplicam.

Versão 1.6

Data de lançamento: agosto de 2025

  • Adicionado suporte ao Django 5.1 e 5.2.
  • Funcionalidade de JSON aprimorada e compatibilidade com versões anteriores.
  • Infraestrutura de pipeline aprimorada.

Versão 1.5

Data de lançamento: abril de 2024

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

Versão 1.4

Data de lançamento: janeiro de 2024

  • Adicionado suporte ao Django 5.0.
  • Suporte db_comment adicionado.
  • Correções de bug para conversões de data/hora e agregações vazias.

Versão 1.3

Data de lançamento: maio de 2023

  • Adicionado suporte ao Django 4.2.
  • Adição de suporte à função Replace que diferencia maiúsculas de minúsculas.
  • Correções de bugs no tratamento de OFFSET e no preenchimento à esquerda.

Versão 1.2

Data de lançamento: dezembro de 2022

  • Adicionado suporte ao Django 4.1.
  • Adicionado suporte a fuso horário (datetimeoffset com USE_TZ=True).
  • Adicionada a opção return_rows_bulk_insert para recuperação do ID de inserção em lote.
  • Adicionado suporte ao SQL Server 2022.
  • Adicionado suporte para JSONField Instância Gerenciada de SQL do Azure.

Versão 1.1

Data de lançamento: julho de 2022

  • Suporte ao Django 3.2 e 4.0.
  • Há suporte para SQL Server 2016 e posteriores, e para o Banco de Dados SQL do Azure.
  • Conectividade baseada em pyodbc.

Conteúdo relacionado

  • Última atualização em