Django 6.1 N+1 방어선: FETCH_PEERS와 FETCH_RAISE 활용법

Django 6.1에서 목록 화면의 N+1 쿼리를 줄이려면 FETCH_PEERS를, 정해진 조회 범위를 벗어나는 필드 접근을 발견하려면 FETCH_RAISE를 검토할 수 있습니다. 응답에 필요한 관계가 확실한 API라면 select_related()로 미리 읽고, FETCH_RAISE와 쿼리 수 테스트를 함께 적용하는 구성을 추천합니다.

예를 들어 고객 문의 목록에 고객 이름을 표시하는 경우를 생각해 봅시다. 문의 50건을 가져온 뒤 각 문의에서 고객을 따로 조회하면, 목록 조회 한 번이 수십 번의 데이터베이스 왕복으로 늘어납니다. 조회 코드는 그대로인데 응답 필드 하나를 추가하면서 이런 문제가 생기기도 합니다. 이번 글은 이 상황을 작은 예제로 다룹니다.

기준일: 2026년 10월 5일. Fetch mode는 2026년 8월 5일 출시된 Django 6.1에 추가됐습니다. 6.1은 Python 3.12·3.13·3.14를 지원합니다. 6.1.1 패치 릴리스는 2026년 9월 2일 공개됐습니다. 아래 코드는 6.1 API를 기준으로 작성했고 Python 3.12 문법 검사를 수행했습니다. Django를 설치해 데이터베이스와 함께 실행한 예제는 아니며, 제시한 쿼리 수는 문서상 동작에 따른 예상값입니다.

목록의 관련 데이터를 묶어서 조회하는 방식과 계획 밖의 지연 필드 조회를 감지하는 방식을 나타낸 개념도
AI로 생성한 설명용 이미지입니다. 관계 데이터 일괄 조회와 지연 필드 조회 감지를 표현했으며, 실제 쿼리 수나 성능 측정 결과를 보여 주지 않습니다.

1. 세 가지 모드에서 바뀌는 것

Fetch mode는 모델에 아직 로드되지 않은 필드를 읽을 때의 동작을 정합니다. 기본 동작을 유지할지, 같은 조회 결과의 다른 객체까지 묶어서 가져올지, 추가 조회를 막을지 선택합니다.

  • FETCH_ONE: 기본값입니다. 현재 객체의 누락된 필드를 가져옵니다.
  • FETCH_PEERS: 같은 QuerySet에서 만들어진 객체들을 함께 고려해 해당 필드를 일괄 조회합니다.
  • FETCH_RAISE: 필요한 필드를 뒤늦게 조회하려 하면 FieldFetchBlocked 예외를 발생시킵니다.

외래 키, 일대일 관계와 그 역방향 접근, only()·defer()로 제외한 필드 등이 적용 대상입니다. 상세 범위는 공식 Fetch modes 문서에서 확인할 수 있습니다.

2. 고객 문의 목록으로 비교하기

이미 생성한 Django 프로젝트에 support 앱이 있고, 앱 등록과 마이그레이션을 완료했다고 가정합니다. 모델은 고객 이름과 문의 제목만 남겨 단순하게 구성합니다.

# support/models.py
from django.db import models


class Customer(models.Model):
    name = models.CharField(max_length=100)


class Ticket(models.Model):
    subject = models.CharField(max_length=200)
    customer = models.ForeignKey(
        Customer,
        on_delete=models.PROTECT,
        related_name="tickets",
    )

다음 함수는 문의를 간단한 응답 데이터로 바꿉니다. 기본 모드에서는 ticket.customer.name이 추가 조회의 출발점입니다.

# support/selectors.py
from django.db import models

from .models import Ticket


def ticket_rows(tickets):
    return [
        {"subject": ticket.subject, "customer": ticket.customer.name}
        for ticket in tickets
    ]


def peer_ticket_rows():
    tickets = (
        Ticket.objects.order_by("pk")
        .fetch_mode(models.FETCH_PEERS)[:50]
    )
    return ticket_rows(tickets)

이처럼 비어 있지 않은 작은 목록에서 단일 고객 관계를 순회하면, 문의 목록 조회 1회와 고객 일괄 조회 1회를 예상할 수 있습니다. 기본 모드라면 문의 N건에 대해 1+N회가 발생하는 형태입니다. 이는 6.1 릴리스 노트의 단일 외래 키 예시와 같은 구조입니다.

다만 모든 목록이 항상 두 번의 쿼리로 끝나는 것은 아닙니다. 여기서는 고객 관계 하나만 읽고, 추가 쿼리를 수행하는 속성이나 사용자 정의 매니저도 없다고 가정했습니다. 빈 목록에서는 고객을 읽을 일이 없으며, 다른 관계를 더 읽으면 계산도 달라집니다.

3. 응답 필드가 정해졌다면 미리 읽고, 누락을 감지하기

고객 이름이 항상 필요한 화면이라면 조회 의도를 코드에 직접 적을 수 있습니다. select_related("customer")는 SQL 조인으로 문의와 고객을 함께 가져옵니다. 여기에 FETCH_RAISE를 더하면 응답을 만드는 중에 놓친 필드를 뒤늦게 읽는 상황을 감지할 수 있습니다. 두 API의 역할은 QuerySet 공식 문서에 설명돼 있습니다.

# support/selectors.py에 추가
def strict_ticket_rows():
    tickets = (
        Ticket.objects.select_related("customer")
        .fetch_mode(models.FETCH_RAISE)
        .order_by("pk")[:50]
    )
    return ticket_rows(tickets)

위 모델과 응답 구조에서는 조인 쿼리 1회를 예상합니다. 나중에 다른 관계의 값을 응답에 추가했다면, 그 관계도 조회 계획에 포함해야 합니다. 이때 발생하는 FieldFetchBlocked를 무조건 잡아서 기본값으로 숨기기보다는, 필요한 데이터를 어디서 읽어야 하는지 먼저 확인하는 편이 좋습니다.

운영 중인 모든 모델의 기본 모드를 한꺼번에 바꾸는 접근은 신중해야 합니다. 템플릿이나 관리자 화면에서 지금까지 허용되던 지연 조회가 예외로 바뀔 수 있습니다. 먼저 하나의 조회 함수와 그 테스트에서 시작하면 영향 범위를 파악하기 쉽습니다.

4. 쿼리 수와 차단 동작을 테스트로 남기기

아래는 프로젝트에서 실행해 볼 수 있도록 작성한 테스트입니다. 서로 다른 고객에게 문의 한 건씩, 총 3건을 만듭니다. 데이터 준비는 측정 구간 밖에 두고, 각 테스트에서 새 QuerySet을 평가합니다. assertNumQueries()는 해당 구간의 쿼리 수가 예상과 같은지 검사합니다.

# support/tests.py
from django.core.exceptions import FieldFetchBlocked
from django.db import models
from django.test import TestCase

from .models import Customer, Ticket
from .selectors import (
    peer_ticket_rows,
    strict_ticket_rows,
    ticket_rows,
)


class TicketQueryTests(TestCase):
    @classmethod
    def setUpTestData(cls):
        for number in range(3):
            customer = Customer.objects.create(name=f"고객 {number}")
            Ticket.objects.create(
                subject=f"문의 {number}",
                customer=customer,
            )

    def test_default_mode_uses_four_queries(self):
        with self.assertNumQueries(4):
            rows = ticket_rows(Ticket.objects.order_by("pk"))
        self.assertEqual(len(rows), 3)

    def test_peers_mode_uses_two_queries(self):
        with self.assertNumQueries(2):
            rows = peer_ticket_rows()
        self.assertEqual(len(rows), 3)

    def test_explicit_join_uses_one_query(self):
        with self.assertNumQueries(1):
            rows = strict_ticket_rows()
        self.assertEqual(rows[0]["customer"], "고객 0")

    def test_missing_relation_is_blocked(self):
        ticket = (
            Ticket.objects.fetch_mode(models.FETCH_RAISE)
            .order_by("pk").first()
        )
        with self.assertNumQueries(0):
            with self.assertRaises(FieldFetchBlocked):
                _ = ticket.customer.name

테스트 명령은 python manage.py test support입니다. 이 글에서는 이 명령을 실행하지 않았습니다. 기존 프로젝트에 옮길 때는 앱 이름과 모델 구조를 맞춘 뒤, 실제 사용하는 데이터베이스 설정에서도 확인해야 합니다.

마지막 테스트는 최초 문의 조회를 측정에서 제외하고, 고객에 접근하는 순간 추가 SQL 없이 예외가 나는지를 검사합니다. 앞의 세 테스트는 데이터 로딩부터 응답 변환까지를 측정합니다. 서로 다른 범위를 검사한다는 점을 의도적으로 드러낸 구성입니다.

5. 적용 전에 확인할 한계

  • 관계 매니저의 조회는 별도로 봐야 합니다. customer.tickets.all() 같은 역방향 일대다 조회나 다대다 매니저의 쿼리는 fetch mode가 직접 제어하지 않습니다. 컬렉션이 필요하면 prefetch_related() 등을 검토하고 쿼리 수를 측정해야 합니다. 관련 객체에 모드가 전달되는 것과 매니저의 조회를 막는 것은 구분해야 합니다. 적용 범위 근거
  • FETCH_RAISE가 모든 SQL을 차단하지는 않습니다. 필드의 지연 로딩을 제어하므로, 함수 내부에서 명시적으로 실행한 다른 QuerySet까지 금지하는 장치로 생각하면 안 됩니다. 따라서 전체 처리 구간의 쿼리 수 테스트를 함께 둡니다.
  • 한 객체만 필요해도 같은 배치가 영향을 받습니다. FETCH_PEERS의 일괄 조회 특성상, 대부분 사용하지 않을 관계 데이터를 읽는 경우도 생각해야 합니다. 조회 범위를 먼저 좁히고 실제 메모리 사용량을 확인하는 이유입니다.
  • 쿼리 수 감소와 응답 시간 개선은 각각 확인합니다. 큰 조인, 가져오는 데이터의 양, 인덱스와 DB 실행 계획에 따라 결과가 달라집니다. 이 글의 4회·2회·1회는 속도 배수나 실측 벤치마크가 아닙니다. 공식 최적화 가이드도 변경 전후 측정을 먼저 권합니다.

6. 기존 프로젝트에는 이렇게 도입하기

  1. 버전과 의존성을 확인합니다. fetch_mode()는 Django 6.1에서 추가됐으므로 5.2나 6.0에 그대로 붙일 수 없습니다. 업그레이드가 필요하면 Python 및 주요 패키지 호환성과 변경 사항부터 확인합니다.
  2. 작은 조회 한 곳을 고릅니다. 사용자가 자주 보는 목록 API나 조회가 반복되는 화면을 골라, 현재 쿼리와 응답 시간을 기록합니다.
  3. 화면이 요구하는 데이터를 기준으로 선택합니다. 접근할 관계가 유동적이면 FETCH_PEERS를 실험하고, 응답 구조가 고정돼 있다면 명시적 사전 조회와 FETCH_RAISE 조합을 비교합니다.
  4. 응답 내용과 쿼리 예산을 함께 검사합니다. 빈 목록, 여러 건의 목록, 새 응답 필드가 추가되는 경우까지 테스트한 뒤 적용 범위를 넓힙니다.

첫 단계의 호환성 점검과 전체 테스트 절차는 Django 공식 업그레이드 가이드를 참고하면 됩니다. 이 기능 하나만을 이유로 운영 프로젝트의 업그레이드를 서두르기보다는, 현재 병목과 유지보수 계획에 맞춰 판단하는 것이 좋습니다.

작게 시작할 때의 추천은 명확합니다. 먼저 한 목록에서 필요한 관계를 정리하고 쿼리 수 테스트를 만듭니다. 그다음 Fetch mode를 적용해 숨은 조회를 찾거나 묶어 처리합니다. 이렇게 해야 응답 필드가 늘어날 때도 데이터 접근 비용을 놓치지 않을 수 있습니다.

이 글은 공식 문서를 바탕으로 AI의 도움을 받아 자료를 조사하고 정리했습니다. 실제 서비스 성능이나 통합 테스트 결과를 보고한 글은 아닙니다.

댓글

  1. 고객 문의 50건 목록에서 고객 이름을 읽는 예시로 N+1 문제가 언제 생기는지 바로 이해됐습니다. 응답 필드가 고정된 화면은 select_related로 의도를 명시하고 FETCH_RAISE로 뒤늦은 조회를 잡는 구분도 좋네요. 말씀하신 대로 쿼리 4·2·1회는 예상값이니, 실제 DB에서 빈 목록과 필드 추가 사례까지 테스트한 결과를 함께 기록하면 도입 판단이 더 쉬워질 것 같습니다.

    답글삭제

댓글 쓰기