ClickHouse Managed Postgres で Django を使用する

​

前提条件

• Python 3.12 以降 (Django 6 の要件) 。本ガイドは Python 3.13、Django 6.1.1、psycopg 3.3.6 で動作確認しています。
• ClickHouse Cloud アカウント
• データベース作成用の psql。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 は、サーバー側カーソルを介して行を chunk 単位で読み込みます。トランザクション外では、Django はカーソルを WITH HOLD として宣言し、各 chunk を個別にフェッチします。そのため PgBouncer 経由では、フェッチがそのカーソルを持たない Postgres 接続に割り当てられ、cursor "_django_curs_..." does not exist というエラーで失敗することがあります。この問題は他のクライアントが同時に pool を使用している場合にのみ発生するため、開発環境では表面化しないことがよくあります。この設定を有効にすると、.iterator() は通常のカーソルを使用し、psycopg は結果全体をメモリに読み込みます。非常に大きなテーブルをストリーミングする場合は、この設定を無効にしたうえで、ポート 5432 の直接接続を使ってそのコードを実行してください。
• CONN_MAX_AGE: デフォルト (0) では、Django はリクエストごとに新しい接続を開きます。TLS 接続の確立には、PgBouncer 経由でも直接接続でも複数回のネットワークラウンドトリップが必要なため、接続を再利用するとリクエストが大幅に高速化されます。ノート PC から 4 つの Gunicorn worker を使用して行ったテストでは、CONN_MAX_AGE を 600 に設定すると、リクエスト時間の中央値が約 670 ms から 95 ms に短縮されました。PgBouncer 経由の場合、開いたままの Django の接続はトランザクション間で Postgres 接続を保持しないため、永続接続によって max_connections を使い切ることはありません。CONN_HEALTH_CHECKS を有効にすると、Django は各リクエストの開始時に再利用する接続をチェックし、切断されていれば再接続します。
• 接続プール: Django の組み込みプール (OPTIONS 内の "pool": True。pip install "psycopg[binary,pool]" が必要) でも同程度の高速化が得られ、PgBouncer 経由でも動作します。ただし CONN_MAX_AGE を 0 に設定する必要があり、プロセスごとに最低 4 つの接続を開いたままにします。PgBouncer を使用する場合、ほとんどのアプリケーションでは CONN_MAX_AGE で十分です。スレッド型サーバーや ASGI サーバーではプールの利用を検討してください。
• プリペアドステートメント: 設定は不要です。Django はデフォルトで psycopg の prepare_threshold を None に設定し、クエリパラメータをクライアント側でバインドするため、サーバー側のプリペアドステートメントは作成されません。OPTIONS で "server_side_binding": True を有効にして "prepare_threshold" を設定した場合でも、プリペアドステートメントは PgBouncer 経由で動作します。これは、psycopg[binary] に libpq 18 が同梱されており、プロトコルレベルの Close メッセージでステートメントを解放するためです。libpq 16 以前に対してビルドされた psycopg では、トランザクション内でステートメントを解放すると prepared statement "_pg3_0" does not exist というエラーで失敗します。バージョンを確認するには、python -c "import psycopg; print(psycopg.pq.version())" を実行してください。170000 以降が必要です。
• セッション状態: 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 アクセスリストとプライベートネットワーク接続