Fale conosco
Desenvolvimento

Django 6.1: fetch modes cortam o N+1 silencioso para 2 queries — e o que ainda fica de fora

23 min de leitura
Django 6.1: fetch modes cortam o N+1 silencioso para 2 queries — e o que ainda fica de fora

Django 6.1: fetch modes cortam o N+1 silencioso para 2 queries — e o que ainda fica de fora

O N+1 é o bug de performance mais chato do ORM do Django porque ele não aparece em log, não quebra teste e não dispara alerta. Uma listagem de 100 pedidos que imprime o nome do cliente faz 1 query para os pedidos e mais 100 para os clientes. No ambiente de desenvolvimento, com 12 registros, ninguém percebe. Em produção, com paginação cheia, a latência sobe de 40 ms para centenas de milissegundos — e o culpado nunca está na query lenta que aparece no APM.

O Django 6.1, lançado em 5 de agosto de 2026, mexeu nesse comportamento pela raiz ao introduzir fetch modes : a política de carregamento sob demanda de um campo deixou de ser fixa ( FETCH_ONE , o velho "busca uma query a mais, sempre") e passou a ser configurável por queryset. Nas últimas semanas, benchmarks independentes publicados na comunidade mostraram o tamanho do ganho — e, principalmente, onde ele não pega.

O que fetch_mode() faz de fato

QuerySet.fetch_mode() controla o que acontece quando o código toca num campo que a consulta original não trouxe: uma foreign key, um one-to-one, um campo adiado por defer() / only() ou uma generic relation. Existem três modos embutidos: FETCH_ONE (padrão, comportamento antigo), FETCH_PEERS e FETCH_RAISE .

A diferença conceitual em relação ao select_related() é importante: FETCH_PEERS não faz JOIN. No primeiro acesso, o Django coleta as chaves de todos os objetos do queryset e dispara um WHERE id IN (...) para a relação — por isso são duas queries independentes, e não uma grande com junção. Já o FETCH_RAISE troca o silêncio por exceção: o acesso a um campo não carregado estoura na hora, o que transforma o N+1 em falha de teste em vez de degradação em produção.

Um benchmark divulgado em setembro pelo dev.to levou um laço de 2.000 instâncias de 2.001 queries para 2. Já um experimento de novembro com 467 rotas e 3.963 requisições mostrou que, ao remover todos os select_related() de uma base real, o total de queries subiu de 59.198 para 76.144 — e o FETCH_PEERS recuperou cerca de 69% desse aumento. Leia como dado de projeto de terceiros, não como número oficial: o volume de ganho depende muito de quantos objetos do queryset realmente acessam a relação.

Onde os fetch modes não pegam

Três armadilhas aparecem em praticamente todos os relatos de migração:

Relações to-many continuam fora. FETCH_PEERS age em FK, one-to-one e campos adiados. Para prefetch_related() clássico — reverse FK e many-to-many — você continua escrevendo a chamada. Quem lê "resolve N+1" e apaga todos os prefetch_related() ganha um conjunto de queries pior.

Custo de memória e de banco pode inverter o sinal. O lote carrega a relação para todos os objetos do queryset, inclusive os que você nunca vai usar. Num queryset grande, com filtro depois em Python, o FETCH_PEERS pode buscar dezenas de milhares de linhas para usar dez. Em iterator() sobre tabelas enormes, meça antes.

FETCH_ONE continua o padrão. Ninguém recebe o ganho de graça: é decisão por queryset, o que significa que o time precisa escolher onde aplicar — e deixar isso explícito no código, não na cabeça de quem escreveu a view.

Em times que mantêm APIs Django com DRF, o padrão que tem funcionado é encapsular a política num QuerySet/Manager próprio e propagá-la por ali, em vez de repetir fetch_mode() em cada view:

Esse tipo de decisão — onde a política de carregamento mora, quem é dono dela e como ela é testada — é o que separa um ganho de performance real de uma otimização que some no próximo refactor. Na Maquinaweb, projetos em Python/Django e em stacks Node.js, C#/.NET e Angular costumam passar por essa revisão de camada de acesso a dados antes de escalar tráfego, justamente porque o N+1 aparece quando o volume cresce, não quando o código é escrito.

FETCH_RAISE como guarda-corpo de teste

O uso mais subestimado do recurso não é performance, é regressão. Em vez de confiar em revisão de código, você faz o teste falhar quando alguém introduzir um acesso preguiçoso novo:

O teste falha apontando a linha exata do acesso, o que é muito mais útil do que descobrir meses depois num gráfico de latência. A contrapartida é escopo: aplicar FETCH_RAISE globalmente em uma base legada costuma gerar uma fila enorme de falhas de uma vez. Comece pelas views de listagem com paginação e pelas serializers mais profundas — é onde o N+1 se esconde.

Outras mudanças do 6.1 que mordem no upgrade

Se você está saindo do 6.0, o bloqueio pode vir antes do ORM: o 6.1 exige PostgreSQL 15+ , MySQL 8.4+ e MariaDB 10.11+ . Também mudaram o comportamento de first() / last() e a geração de aliases SQL com case misto, e o EMAIL_BACKEND entrou em depreciação em favor do novo dicionário MAILERS . Vale ler as notas de release antes de rodar pip install -U django no CI — e lembrar que 6.1.3, de 3 de novembro, já trouxe correções de segurança e compatibilidade com Python 3.15.

Fato: os fetch modes existem desde agosto e são estáveis. Avaliação: eles resolvem o caso mais comum do N+1 (FK e one-to-one em listagens) com muito menos ruído do que espalhar select_related() por toda parte — mas não substituem prefetch_related() nem dispensam medir. A recomendação prática é em três passos: mapeie os endpoints com mais queries, aplique FETCH_PEERS nos querysets de listagem, e trave o resultado com FETCH_RAISE em teste. Se o seu time está avaliando migrar de versão do Django ou revisar a camada de dados de um sistema que já cresceu, o time de engenharia da Maquinaweb pode ajudar a levantar o custo real dessa mudança antes de colocar em produção — é só chamar para conversar.

Fontes

#django #python #orm #banco de dados #performance #n+1 queries #backend #testes
Contato

Bora conversar?

Três campos. A resposta vem no WhatsApp.

Ou escreva para contato@maquinaweb.com.br.

Você vai para o WhatsApp com a mensagem pronta. Sem spam, sem lista.

Seus dados seguem a nossa política de privacidade.