Django 터미널에서 데이터베이스 쿼리 수 확인하기 – django-querycount 디버깅 가이드

Django 쿼리 수를 터미널에서 확인하기

데이터베이스 쿼리 최적화는 Django 애플리케이션 성능 개선의 핵심 요소입니다. 이 글에서는 django-querycount 라이브러리를 활용해 터미널에 간결한 데이터베이스 쿼리 보고서를 출력하고, 이를 디버깅에 활용하는 방법을 알아봅니다.

이 라이브러리는 모델 객체에 대한 모든 접근(읽기 또는 쓰기)마다 표 형태의 보고서를 생성하여 매번 터미널에 출력해 줍니다. 또한 요청과 응답 정보까지 함께 계산해 주기 때문에, 어떤 코드 경로가 과도한 쿼리를 유발하는지 빠르게 파악할 수 있습니다.

설치 및 설정 방법

먼저 앱 등록과 URL 설정 같은 기본적인 프로젝트 세팅을 마친 뒤, 다음 명령어로 django-querycount 모듈을 설치합니다.

pip install django-querycount

그다음 settings.py 파일의 MIDDLEWARE 목록에 아래 미들웨어를 추가합니다.

MIDDLEWARE += [
    'querycount.middleware.QueryCountMiddleware',
]

이 설정만으로 라이브러리 기능이 활성화되며, 프로젝트 실행 중 실시간으로 쿼리 카운트를 확인할 수 있습니다. 복잡한 구성 없이 몇 줄의 코드만 추가하면 되기 때문에 개발 생산성 측면에서 매우 유용합니다.

디버깅 채널 설정하기

설정이 완료되면 디버깅 채널을 준비하세요. 이후 모델에 쿼리가 발생할 때마다 터미널에 표 형태의 보고서가 출력됩니다.

주의할 점은 이 기능이 DEBUG = True일 때만 동작한다는 것입니다. 또한 모델과 어떤 형태로든 상호작용(조회, 저장, 수정, 삭제 등)이 있을 때만 보고서가 나타납니다. 어디까지나 디버깅 전용 도구이기 때문입니다.

또 한 가지 기억할 점은 특정 모델에 접근했을 때 해당 모델에 대한 보고서가 출력된다는 것입니다. 덕분에 어떤 뷰나 로직이 불필요하게 반복되는 쿼리(N+1 문제 등)를 유발하는지 손쉽게 진단할 수 있습니다.

출력 예시

아래는 터미널에 출력되는 쿼리 카운트 보고서의 예시 화면입니다.