Claude Code 플러그인으로 Django/SQLAlchemy 쿼리 튜닝하기

황용호·2026년 10월 12일

query-inspector는 앱을 실행하지 않고 코드의 SQL과 ORM 생성 쿼리를 분석하는 Claude Code 플러그인입니다.

N+1, 인덱스 누락 등 안티패턴을 검출하고 복붙 가능한 수정안을 제시합니다.
코드를 읽어 ORM이 생성할 SQL을 추론하므로 앱 기동이나 운영 DB 접속이 필요 없습니다.

1.1.0부터 기존 JVM 스택에 더해 Python(Django/SQLAlchemy) 을 지원합니다.

문제

ORM이 생성하는 SQL은 코드에 바로 드러나지 않습니다.
기존 솔루션(APM, 슬로우 쿼리 로그, django-debug-toolbar 등)으로 쿼리 문제를 찾으려면 일단 실행을 해야 하고 해당 쿼리가 실행되는 상황을 재연해야 합니다.

게다가 DB 관련 문제들은 대부분 실제 데이터가 많이 쌓이거나 다양한 데이터가 있을 때 발생합니다. 그래서 QA 때도 검증하기 힘들고 주로 운영 환경에서 우연히 또는 거의 장애에 이르렀을 때 발견되는 경우가 많습니다. 이런 문제가 발견되면 서비스 운영 중에 긴급 수정 및 패치를 해야 합니다.

query-inspector는 코드를 정적으로 분석해 실행하지 않고도 SQL의 문제를 제시합니다.

코드를 수정/추가하고 커밋 직전에 한 번 실행하면 변경분만 스캔하기 때문에 빠르고 손쉽게 문제를 파악하고 수정할 수 있습니다.

Python 분석 범위

Django / SQLAlchemy 코드를 분류해 생성 SQL을 재구성하고 스키마와 대조합니다.

  • N+1 - 루프, 템플릿, 시리얼라이저, admin 등 뷰 바깥의 반복 조회를 찾아 줍니다.
  • 인덱스 누락 - WHERE/조인/정렬 컬럼을 모델 또는 마이그레이션과 대조해 추가해야 할 인덱스를 제안합니다.
  • 숨은 정확성/권한 결함 - 컴파일된 SQL에서만 찾을 수 있는 문제(필터가 실제로는 모두 통과 등)를 진단합니다.
  • 방언/마이그레이션 - Alembic / Django 마이그레이션을 인덱스 소스로 함께 분석합니다.

추론 항목은 INFERRED/AMBIGUOUS로 표기하고, 중요한 지점은 직접 컴파일하여 확인합니다.

린터/APM과의 차이

  • 실행 없이 재구성 - 느린 요청을 기다릴 필요가 없습니다.
  • 넓은 N+1 탐지 - 뷰뿐 아니라 템플릿, 시리얼라이저, admin까지 포함합니다.
  • 수정안 제시 - CREATE INDEX, selectinload(...) 등 복붙 가능한 수정안을 제시합니다. 제안만 하며 코드를 직접 수정하지는 않습니다.

동작 방식

조건에 따라 3단계로 자동 강등합니다.

  1. 정적 휴리스틱 - DB 불필요, 항상 동작.
  2. 스키마 대조 - 모델/마이그레이션으로 인덱스 확인, CREATE INDEX 제안.
  3. 실 DB EXPLAIN - --db 지정 시에만, 읽기 전용, 운영 호스트 차단.

이 플러그인은 이전 버전까지는 Kotlin/Java가 주력이었으나 Python은 1.1.0부터 공식 지원하며 실무 오픈소스로 검증해 커버리지를 높였습니다.

설치

claude plugin marketplace add jogakdal/query-inspector
claude plugin install query-inspector@query-inspector-marketplace

프로젝트의 디렉토리에서 새 claude 세션을 열고 실행합니다.

/query-inspector:tuning-report

프로젝트에서 추출한 전체 쿼리 목록은 /query-inspector:inventory-report로 확인할 수 있습니다.

상세 매뉴얼은 아래 저장소의 README나 매뉴얼을 참고해 주세요.

저장소(MIT): https://github.com/jogakdal/query-inspector

사용 중인 프로젝트에 실행해 검출 결과나 오탐을 알려 주시면 Python 어댑터 개선에 반영합니다.

0개의 댓글