HOWTO · Django

Django에서 원시 쿼리 조작

이 설명을 통해 raw() 메서드가 하는 일과 원시 쿼리를 조작하는 방법을 배웁니다. 또한 Django의 응용 프로그램에 SQL을 삽입하는 방법도 배웁니다.

이 페이지의 내용

Django의 raw() 메서드는 원시 SQL 쿼리를 실행하고 각 결과 행을 모델 인스턴스로 매핑합니다. ORM으로 쿼리를 명확하거나 효율적으로 표현하기 어려울 때 사용하세요. 일반적인 필터링과 업데이트에는 더 풍부하고 조합 가능한 API를 제공하는 ORM을 우선 사용하는 편이 좋습니다. 원시 SQL을 사용할 때도 매개변수를 신중하게 다루고, Django가 모델 인스턴스를 만드는 데 필요한 열을 반환해야 합니다.

Django의 raw()가 하는 일과 사용 시점

모델 관리자에서 Student.objects.raw(sql, params=...)를 호출합니다. 결과는 RawQuerySet입니다. 반복하여 Student 객체를 가져올 수 있지만, 일반 QuerySet에서 사용할 수 있는 모든 작업을 제공하지는 않습니다. 특히 ORM 필터를 이어서 적용하거나 Student.objects.filter(...)를 그대로 대체할 수 있다고 가정하지 마세요.

쿼리는 모델의 기본 키 열을 선택해야 합니다. Django는 이 값을 사용해 각 모델 인스턴스를 식별하고 구성합니다. 기본 키가 없으면 쿼리에서 기대한 모델 결과를 만들 수 없습니다. SQL의 테이블 이름은 앱 레이블과 모델 설정에 따라 달라집니다. 아래 예시에서는 student라는 앱의 Student 모델에 흔히 사용되는 테이블 이름인 student_student를 사용합니다. 예시를 적용하기 전에 모델의 실제 테이블 설정을 확인하세요.

모델 및 뷰 예시 준비

원래 예시처럼 models.py에 FIRST_NAME, SR_NAME, age, CLASS_ROOM, TEACHER 필드를 가진 Student 모델이 정의되어 있다고 가정합니다. 이 모델의 관리자는 Student.objects입니다. views.py에서 앱의 모델 모듈로부터 Student를, Django의 render 도우미를 가져온 다음 Student.objects.raw(sql, params=params)를 호출하고 결과를 render(request, "output.html", {"data": students})에 전달합니다. 예시에서는 SQL과 템플릿이 모델과 일치하도록 기존의 대문자 필드 이름을 사용합니다. 새 모델을 만든다면 필드 이름을 소문자로 짓는 편이 더 일반적입니다.

이 뷰에서는 모델의 기본 키가 id이고 필드가 FIRST_NAME, SR_NAME, age, CLASS_ROOM, TEACHER이며 SQL 테이블 이름이 student_student라고 가정합니다. 간단한 views.py 예시는 다음과 같습니다.

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

# Minimal stand-ins make the view shape runnable outside a Django project.
# Replace these with Django's render helper and your actual Student model.
class StudentManager:
    def raw(self, sql, params):
        return [(sql, params)]


class Student:
    objects = StudentManager()


def render(request, template_name, context):
    return template_name, context


def student_data(request):
    sql = "SELECT id, FIRST_NAME, SR_NAME, age, CLASS_ROOM, TEACHER FROM student_student WHERE age = %s"
    students = Student.objects.raw(sql, params=[21])
    return render(request, "output.html", {"data": students})


student_data(None)

위의 대체 표현은 호출 형태를 보여 주기 위한 것입니다. Django 프로젝트에서는 django.shortcuts에서 render를, 앱의 모델 모듈에서 Student를 가져오세요. 쿼리와 템플릿은 독립 실행 스크립트가 아니라 Django 프로젝트에 두어야 합니다. 테이블 이름을 모델에 설정된 이름에 맞추고 Django가 찾을 수 있는 위치에 템플릿을 배치하세요. 템플릿의 data 컨텍스트 키와 FIRST_NAME, age 필드는 뷰 및 쿼리와 일치합니다.

원시 SQL 쿼리 실행 및 필터링

기본 키와 페이지에 필요한 필드를 함께 선택하세요. 학습할 때는 SELECT *가 편리하지만, 열을 명시하면 모델 매핑과 데이터 전송을 더 쉽게 검토할 수 있습니다. 필터는 SQL 문에 넣습니다. 예를 들면 SELECT id, FIRST_NAME, SR_NAME, age, CLASS_ROOM, TEACHER FROM student_student WHERE age = %s와 같습니다. 열 이름은 데이터베이스 스키마와 일치해야 합니다. 데이터베이스 열 이름이 모델 필드 이름과 다르면 db_column 매핑이나 SQL 별칭을 사용하세요.

이 예시를 실행해 보세요.

이 섹션의 코드와 표시되는 레이블 또는 출력은 영어로 유지됩니다.

sql = "SELECT id, FIRST_NAME, age FROM student_student WHERE age = %s"
params = [21]
print(sql)
print(params[0])
SELECT id, FIRST_NAME, age FROM student_student WHERE age = %s
21

이 독립 실행 예시는 SQL 문과 별도로 바인딩된 값을 표시합니다. Django에 연결하거나 데이터베이스 쿼리를 실행하지 않으며, 코드와 출력 블록은 영어 형식 그대로 유지됩니다. 뷰에서는 두 값을 모두 Student.objects.raw(sql, params=params)에 전달합니다.

디버깅할 때 django.db.connection.queries를 사용하면 쿼리 로깅이 활성화된 경우(일반적으로 DEBUG가 켜진 경우) Django가 기록한 쿼리를 확인할 수 있습니다. 이는 쿼리를 살펴보는 도구이지 성능 벤치마크가 아닙니다. 로깅에는 오버헤드가 발생하며, 기록된 목록만으로 운영 환경 부하에서 쿼리가 어떻게 동작하는지 알 수는 없습니다.

매개변수를 안전하게 사용하고 반환된 모델 인스턴스 이해하기

값은 params로 전달하세요. 사용자 입력을 SQL 문자열에 포맷하거나 이어 붙이지 마세요. Django는 SQL과 값을 따로 데이터베이스 드라이버에 전달합니다. 데이터베이스 백엔드의 기본 플레이스홀더 문법이 다르더라도 위치 기반 매개변수에는 Django의 %s 플레이스홀더 문법을 사용하고, 플레이스홀더를 따옴표로 감싸지 마세요. 뷰에서는 Student.objects.raw(sql, params=params)처럼 값을 별도로 전달합니다.

선택한 열은 이름을 기준으로 모델 필드에 매핑됩니다. 필드를 생략하면 Django는 해당 필드의 로딩을 지연합니다. 나중에 그 속성에 접근하면 데이터베이스 쿼리가 추가로 실행될 수 있습니다. 예상치 못한 후속 쿼리를 피하려면 응답에 필요한 필드를 포함하고, 기본 키는 항상 선택하세요.

원시 쿼리 결과 반복 처리 및 제한하기

예를 들어 for student in Student.objects.raw(sql, params=params)처럼 결과를 반복하며 모델 인스턴스를 처리할 수 있습니다. RawQuerySet은 반복할 수 있지만 전체 QuerySet API를 지원하지는 않습니다. 원시 결과를 슬라이싱해도 데이터베이스 작업량이 안정적으로 제한되지는 않습니다. 이미 행을 읽은 뒤 슬라이스가 적용될 수 있기 때문입니다. 대신 LIMIT을 지원하는 데이터베이스에서는 params=[21]과 함께 ... WHERE age = %s LIMIT 2처럼 SQL에 제한을 넣으세요. SQL 페이지네이션 문법은 백엔드마다 다르므로 프로젝트에 설정된 데이터베이스에 맞는 문법을 사용해야 합니다.

특정한 첫 행들이 중요하다면 쿼리에 정렬 기준을 명시하세요. ORDER BY가 없으면 데이터베이스는 안정적인 행 순서를 보장하지 않습니다.

Django 템플릿에서 결과 렌더링하기

뷰는 RawQuerySet을 data라는 이름으로 전달합니다. output.html에서 이 컨텍스트 값을 반복하여 모델 필드를 표시할 수 있습니다. 예를 들면 {% for student in data %}<div>{{ student.FIRST_NAME }} — {{ student.age }}</div>{% endfor %}와 같습니다. Django 템플릿은 기본적으로 변수 출력을 이스케이프하므로 일반 텍스트 필드에 적절합니다. 이렇게 하면 선택한 열과 모델 필드가 페이지에 표시되는 방식이 연결됩니다. 템플릿에서 접근하는 필드는 모두 쿼리에 포함해 필드 로딩 지연으로 추가 쿼리가 발생하지 않도록 하세요.