ClickHouse Managed Postgres에서 Django 사용하기

​

사전 요구 사항

• Python 3.12 이상(Django 6 요구 사항). 이 가이드는 Python 3.13, Django 6.1.1, psycopg 3.3.6 환경에서 테스트되었습니다.
• ClickHouse Cloud 계정
• 데이터베이스 생성에 사용할 psql. SQL 콘솔에서 CREATE DATABASE SQL 문을 실행해도 됩니다.

​

ClickHouse Managed Postgres 서비스 생성

​

연결 정보 확인하기

​

프로젝트 설정

mkdir django-managed-postgres && cd django-managed-postgres
python3 -m venv .venv
source .venv/bin/activate
pip install django "psycopg[binary]"
django-admin startproject mysite .
python manage.py startapp todos

​

연결 구성하기

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_django;"

CREATE DATABASE

export DB_HOST="your-instance.pg.clickhouse.cloud"
export DB_PASSWORD='<PASSWORD>'

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "HOST": os.environ["DB_HOST"],
        "PORT": "6432",
        "NAME": "guide_django",
        "USER": "postgres",
        "PASSWORD": os.environ["DB_PASSWORD"],
        # Reuse connections across requests instead of opening one per request
        "CONN_MAX_AGE": 600,
        "CONN_HEALTH_CHECKS": True,
        # Server-side cursors don't work with PgBouncer transaction pooling
        "DISABLE_SERVER_SIDE_CURSORS": True,
        "OPTIONS": {
            "sslmode": "verify-full",
            "sslrootcert": BASE_DIR / "ca-certificate.pem",
        },
    }
}

​

모델 생성 및 마이그레이션 실행

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'todos',
]

from django.db import models


class Todo(models.Model):
    title = models.CharField(max_length=200)
    done = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

python manage.py makemigrations todos
python manage.py migrate

Migrations for 'todos':
  todos/migrations/0001_initial.py
    + Create model Todo
Operations to perform:
  Apply all migrations: admin, auth, contenttypes, sessions, todos
Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying admin.0001_initial... OK
  Applying admin.0002_logentry_remove_auto_add... OK
  Applying admin.0003_logentry_add_action_flag_choices... OK
  Applying contenttypes.0002_remove_content_type_name... OK
  Applying auth.0002_alter_permission_name_max_length... OK
  Applying auth.0003_alter_user_email_max_length... OK
  Applying auth.0004_alter_user_username_opts... OK
  Applying auth.0005_alter_user_last_login_null... OK
  Applying auth.0006_require_contenttypes_0002... OK
  Applying auth.0007_alter_validators_add_error_messages... OK
  Applying auth.0008_alter_user_username_max_length... OK
  Applying auth.0009_alter_user_last_name_max_length... OK
  Applying auth.0010_alter_group_name_max_length... OK
  Applying auth.0011_update_proxy_permissions... OK
  Applying auth.0012_alter_user_first_name_max_length... OK
  Applying sessions.0001_initial... OK
  Applying todos.0001_initial... OK

​

JSON 엔드포인트 추가

import json

from django.http import JsonResponse
from django.shortcuts import get_object_or_404
from django.views.decorators.csrf import csrf_exempt

from .models import Todo

FIELDS = ["id", "title", "done", "created_at"]


def as_dict(todo):
    return {field: getattr(todo, field) for field in FIELDS}


# This example API skips CSRF checks; add authentication before you deploy it
@csrf_exempt
def todo_list(request):
    if request.method == "POST":
        # Create
        todo = Todo.objects.create(title=json.loads(request.body)["title"])
        return JsonResponse(as_dict(todo), status=201)
    # Read
    return JsonResponse(list(Todo.objects.order_by("id").values(*FIELDS)), safe=False)


@csrf_exempt
def todo_detail(request, pk):
    todo = get_object_or_404(Todo, pk=pk)
    if request.method == "PATCH":
        # Update: toggle the done flag
        todo.done = not todo.done
        todo.save(update_fields=["done"])
    elif request.method == "DELETE":
        # Delete
        data = as_dict(todo)
        todo.delete()
        return JsonResponse(data)
    return JsonResponse(as_dict(todo))

from django.contrib import admin
from django.urls import path

from todos import views

urlpatterns = [
    path("admin/", admin.site.urls),
    path("todos", views.todo_list),
    path("todos/<int:pk>", views.todo_detail),
]

​

실행 및 확인

python manage.py runserver 3111

Performing system checks...

System check identified no issues (0 silenced).
October 01, 2026 - 14:39:10
Django version 6.1.1, using settings 'mysite.settings'
Starting WSGI development server at http://127.0.0.1:3111/
Quit the server with CONTROL-C.

curl -X POST http://localhost:3111/todos -d '{"title": "Try Django"}'
curl -X POST http://localhost:3111/todos -d '{"title": "Write a migration"}'
curl -X PATCH http://localhost:3111/todos/1
curl -X DELETE http://localhost:3111/todos/2

{"id": 1, "title": "Try Django", "done": true, "created_at": "2026-10-01T14:38:51.036Z"}

[{"id": 1, "title": "Try Django", "done": true, "created_at": "2026-10-01T14:38:51.036Z"}]

​

Django를 위한 PgBouncer 설정

• DISABLE_SERVER_SIDE_CURSORS: QuerySet.iterator는 서버 측 커서를 통해 행을 청크 단위로 읽습니다. 트랜잭션 외부에서는 Django가 커서를 WITH HOLD로 선언하고 청크를 하나씩 따로 가져오므로, PgBouncer를 거치면 가져오기 요청이 해당 커서가 없는 Postgres 연결로 전달되어 cursor "_django_curs_..." does not exist 오류와 함께 실패할 수 있습니다. 이 문제는 다른 클라이언트가 동시에 풀을 사용할 때만 발생하므로 개발 환경에서는 드러나지 않는 경우가 많습니다. 이 설정을 켜면 .iterator()는 일반 커서를 사용하며, psycopg가 전체 결과를 메모리에 로드합니다. 매우 큰 테이블을 스트리밍해야 한다면 이 설정을 끈 상태에서 포트 5432의 직접 연결로 해당 코드를 실행하십시오.
• CONN_MAX_AGE: 기본값(0)에서는 Django가 요청마다 새 연결을 엽니다. TLS 연결은 PgBouncer를 거치든 직접 연결하든 연결을 여는 데 여러 번의 네트워크 왕복이 필요하므로, 연결을 재사용하면 요청 속도가 크게 빨라집니다. 노트북에서 4개의 Gunicorn worker로 테스트한 결과, CONN_MAX_AGE를 600으로 설정하자 요청 시간 중앙값이 약 670 ms에서 95 ms로 줄었습니다. PgBouncer를 거치면 열려 있는 Django 연결이 트랜잭션 사이에 Postgres 연결을 점유하지 않으므로, 영구 연결을 사용해도 max_connections가 소진되지 않습니다. CONN_HEALTH_CHECKS를 사용하면 Django가 각 요청을 시작할 때 재사용하는 연결을 확인하고, 연결이 끊어졌으면 다시 연결합니다.
• 연결 풀(Connection pool): Django의 내장 풀(OPTIONS의 "pool": True, pip install "psycopg[binary,pool]" 필요)도 비슷한 속도 향상 효과가 있으며 PgBouncer를 거쳐도 동작합니다. 내장 풀을 사용하려면 CONN_MAX_AGE를 0으로 설정해야 하며, 프로세스당 최소 4개의 연결이 항상 열려 있습니다. PgBouncer를 사용한다면 대부분의 앱은 CONN_MAX_AGE만으로 충분하며, 스레드 기반 서버나 ASGI 서버에서는 풀 사용을 고려하십시오.
• Prepared statement: 별도의 설정이 필요하지 않습니다. Django는 기본적으로 psycopg의 prepare_threshold를 None으로 설정하고 쿼리 매개변수를 클라이언트에서 바인딩하므로 서버 측 prepared statement를 생성하지 않습니다. OPTIONS에서 "server_side_binding": True를 켜고 "prepare_threshold"를 설정하는 경우에도 prepared statement는 PgBouncer를 거쳐 정상적으로 동작합니다. psycopg[binary]에는 libpq 18이 번들로 포함되어 있어 프로토콜 수준의 Close 메시지로 SQL 문을 해제하기 때문입니다. 반면 libpq 16 이하로 빌드된 psycopg에서는 트랜잭션 내부에서 SQL 문을 해제할 때 prepared statement "_pg3_0" does not exist 오류가 발생합니다. 버전을 확인하려면 python -c "import psycopg; print(psycopg.pq.version())"를 실행하십시오. 결과가 170000 이상이어야 합니다.
• 세션 상태(Session state): SET search_path와 같은 SET 문은 해당 문을 실행한 Postgres 연결에만 적용됩니다. 따라서 이후 쿼리에는 반영되지 않을 수 있으며, 오히려 다른 클라이언트에 반영될 수도 있습니다. PgBouncer는 Django의 "options": "-c search_path=..." 설정을 unsupported startup parameter in options: search_path 오류와 함께 거부합니다. 대신 ALTER DATABASE guide_django SET search_path = myschema, public;처럼 데이터베이스 수준에서 기본값을 설정하십시오. SET ROLE을 실행하는 assume_role 옵션은 사용하지 마십시오. Django 자체의 TIME_ZONE 처리와 isolation_level 옵션은 PgBouncer를 거쳐도 정상적으로 동작합니다.

​

다음 단계

• 연결: 연결 문자열, PgBouncer, TLS
• 설정: max_connections 등 Postgres 및 PgBouncer 매개변수
• 읽기 레플리카: Django의 다중 데이터베이스 기능을 활용해 읽기 요청을 레플리카로 분산
• 보안: IP 액세스 목록 및 프라이빗 네트워킹