Python Django N+1 쿼리 에러 완벽 해결: select_related와 prefetch

Python Django N+1 쿼리 에러 완벽 해결: select_related와 prefetch_related 아키텍처

9월 16, 2026

[Troubleshooting] Python Django N+1 쿼리 에러 완벽 해결: select_related 아키텍처

"게시판 목록을 불러오는 간단한 API를 만들었는데, 데이터가 100개로 늘어나자 데이터베이스 CPU가 치솟고 응답 시간이 5초를 넘어가며 서버가 마비되었습니다. 로그를 보니 똑같은 쿼리가 100번 넘게 반복 실행되고 있었습니다."

파이썬 Django 웹 프레임워크를 사용하여 백엔드를 구축하는 개발자들이 100% 겪게 되는 치명적인 성능 저하, 바로 'N+1 쿼리 문제'입니다. Django ORM(Object-Relational Mapping)은 개발자가 SQL을 직접 짜지 않아도 되게 해주는 마법 같은 도구지만, 그 내부의 '지연 평가(Lazy Loading)' 메커니즘을 이해하지 못하면 서비스의 숨통을 끊어놓는 독약이 됩니다.

초보자들은 서버 인스턴스 사양을 올리거나 데이터베이스 인덱스를 추가하며 헛수고를 반복합니다. 하지만 이는 인프라의 문제가 아니라 애플리케이션의 데이터 접근 아키텍처 결함입니다. 본 가이드에서는 Django ORM이 쿼리를 날리는 시점을 해체하고, 쿼리 횟수를 1번으로 압축하는 무결점 최적화 기법을 단호하게 제시합니다.

📌 이 글의 핵심 포인트

지연 평가(Lazy Loading)의 함정: 객체의 속성에 접근할 때마다 무자비하게 발생하는 추가 쿼리의 원리

정방향 참조(1:N, 1:1) 해결: SQL의 JOIN 연산을 미리 수행하여 데이터를 캐싱하는 select_related 활용법

역방향 참조(M:N, N:1) 해결: 추가 쿼리를 하나만 발생시켜 파이썬 메모리에서 매핑하는 prefetch_related 적용법

1단계: 핵심 원인 분석 - 지연 평가와 무한 쿼리의 굴레

N+1 문제의 원리는 간단합니다. 예를 들어 Post(게시글) 모델과 User(작성자) 모델이 외래 키(Foreign Key)로 연결되어 있다고 가정합시다. Post.objects.all()을 호출하면 Django는 게시글 100개를 가져오기 위해 쿼리를 1번(1) 날립니다.

문제는 화면에 작성자의 이름을 보여주기 위해 for문을 돌며 post.author.name에 접근할 때 발생합니다. Django는 이때마다 작성자 정보를 가져오기 위해 SELECT * FROM user WHERE id = ? 쿼리를 100번(N) 추가로 날립니다. 즉, 100개의 글을 보기 위해 101번의 쿼리가 데이터베이스를 때리게 되며 시스템이 무너지는 것입니다.

2단계: 완벽한 트러블슈팅 1 - select_related 도입 (정방향 조인)

가장 강력하고 깔끔한 해결책은 데이터베이스에서 처음 게시글을 가져올 때, 작성자 정보까지 한 번에 JOIN 해서 가져오라고 명시적으로 지시하는 것입니다. 외래 키(Foreign Key)나 1:1 관계처럼 데이터가 1개로 확정되는 정방향 관계에서는 select_related를 사용해야 합니다.


# ❌ 최악의 코드: 100개의 게시글을 가져올 때 총 101번의 쿼리 발생
posts = Post.objects.all()
for post in posts:
    print(post.author.name)  # 이 순간마다 DB를 찌름

# ✅ 완벽한 코드: INNER JOIN을 사용하여 단 1번의 쿼리로 모든 데이터 적재
posts = Post.objects.select_related('author').all()
for post in posts:
    # 이미 메모리에 author 정보가 캐싱되어 있어 DB를 다시 찌르지 않음
    print(post.author.name)

이 코드 한 줄을 추가하는 순간, 101번의 쿼리가 1번의 쿼리로 압축되며 API 응답 속도가 수십 배 이상 빨라집니다.

3단계: 완벽한 트러블슈팅 2 - prefetch_related (다대다, 역방향)

만약 게시글(Post)에 달린 수많은 댓글(Comment)을 가져와야 한다면 어떨까요? 이는 1:N 관계의 역방향 참조이므로 JOIN을 사용하면 데이터가 중복 뻥튀기되는 문제가 발생합니다. 이때는 select_related 대신 prefetch_related를 사용해야 합니다.


# ✅ 1:N 관계에서의 완벽한 쿼리 최적화
# 1번 쿼리: 모든 게시글 조회
# 2번 쿼리: 위 게시글들의 ID를 모아 조건문(IN)으로 모든 댓글을 한 번에 조회
posts = Post.objects.prefetch_related('comments').all()

for post in posts:
    # 파이썬 레벨에서 이미 매핑이 완료되었으므로 추가 쿼리가 발생하지 않음
    for comment in post.comments.all():
        print(comment.content)

prefetch_related는 총 2번의 쿼리(게시글 1번, 관련된 모든 댓글 1번)만 발생시킨 뒤, 파이썬 메모리 단에서 두 데이터를 똑똑하게 매핑해 줍니다. N+1 문제를 2개의 쿼리로 틀어막는 최고의 아키텍처입니다.

🙋‍♂️ 자주 묻는 질문 (FAQ)

Q. 언제 select_related를 쓰고, 언제 prefetch_related를 써야 하나요?
A. 내가 조회하려는 대상이 항상 1개(외래 키가 있는 쪽)라면 select_related(JOIN 방식)를 쓰고, 대상이 여러 개(역방향 참조나 다대다 관계)라면 prefetch_related(추가 쿼리 후 파이썬 매핑 방식)를 사용하면 됩니다.

💡 핵심 정리 및 마무리

ORM은 훌륭한 도구지만, 그 이면에 숨겨진 SQL의 생성 원리를 통제하지 못하면 재앙을 초래합니다. 백엔드 아키텍트라면 겉으로 드러나는 파이썬 코드의 간결함에 취하지 말고, 그 코드가 데이터베이스에 어떤 무자비한 망치질(Query)을 가하는지 직시해야 합니다. 쿼리 최적화는 선택이 아니라 생존입니다.

이 블로그 검색

HAGOCUBE | 디지털 생산성 아키텍트