制約 (Constraint) リファレンス¶
このモジュールで定義されたクラスはデータベース制約を作成します。これらはモデルの Meta.constraints オプションで追加されます。
組み込みの制約への参照について
制約は django.db.models.constraints で定義されていますが、利便性のために django.db.models にインポートされています。標準的な規約は from django.db import models を使い、制約を models.<Foo>Constraint と呼ぶことです。
抽象基底クラスにおける制約
制約には常にユニークな名前を指定する必要があります。また、通常は抽象基底クラスで制約を指定することはできません。なぜなら Meta.constraints オプションはサブクラスに継承され、そのたびに（ name を含む）属性がまったく同じ値になってしまうからです。名前の衝突を回避するために、名前の一部に '%(app_label)s' と '%(class)s' を含めることができ、これにより小文字化されたアプリラベルと具体モデルのクラス名に置き換えられます。
CheckConstraint(condition=Q(age__gte=18), name="%(app_label)s_%(class)s_is_adult")
制約のバリデーション
制約は モデルのバリデーション の間にチェックされます。
BaseConstraint¶
- class BaseConstraint(*name, violation_error_code=None, violation_error_message=None)[ソース]¶
すべての制約の基底クラスです。サブクラスは
constraint_sql(),create_sql(),remove_sql(),validate()メソッドを実装しなければなりません。
すべての制約 (constraint) に共通するパラメータは以下の通りです：
name¶
- BaseConstraint.name¶
制約の名前。制約には常に一意な名前を指定する必要があります。
violation_error_code¶
- BaseConstraint.violation_error_code¶
モデルのバリデーション 中に ValidationError が発生した場合に使用されるエラーコードです。デフォルトは None です。
violation_error_message¶
- BaseConstraint.violation_error_message¶
モデルのバリデーション の実行中に ValidationError が発生した場合に表示されるエラーメッセージです。デフォルトは "Constraint "%(name)s" is violated." です。
validate()¶
モデル model で定義された制約がインスタンス instance で守られているかどうかを検証します。これは、制約が守られていることを確認するために、データベースに対してクエリを実行します。制約を検証するために exclude リストのフィールドが必要な場合、制約は無視されます。
制約に違反した場合は ValidationError を発生させます。
このメソッドはサブクラスで実装する必要があります。
CheckConstraint¶
- class CheckConstraint(*, condition, name, violation_error_code=None, violation_error_message=None)[ソース]¶
データベースにチェック制約を作成します。
condition¶
- CheckConstraint.condition¶
制約が強制する条件チェックを指定する Q オブジェクトまたは真偽値の Expression です。
例:
CheckConstraint(condition=Q(age__gte=18), name="age_gte_18")
年齢フィールドが18未満にならないことを保証します。
式の順序
Q の引数の順番は必ずしも保持されるわけではありませんが、 Q 式の順番自体は保持されます。これは、パフォーマンス上の理由からチェック制約式の順序を保持するデータベースにとって、重要なことです。例えば、順序が重要な場合は以下の形式を使用します。
CheckConstraint(
condition=Q(age__gte=18) & Q(expensive_check=condition),
name="age_gte_18_and_others",
)
Oracle 23c 未満の場合
Oracle 23c 未満で null 許可フィールドを持つチェック制約は、NULL 値を許可する条件を含める必要があります。これにより、validate() がチェック制約の検証と同じように動作します。例えば、age が null 許可フィールドである場合は、次のように記述します：
CheckConstraint(condition=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18")
UniqueConstraint¶
- class UniqueConstraint(*expressions, fields=(), name=None, condition=None, deferrable=None, include=None, opclasses=(), nulls_distinct=None, violation_error_code=None, violation_error_message=None)[ソース]¶
Creates a uniqueness guarantee in the database, enforced by either a unique constraint or a unique index depending on the options used.
Constraint vs. index implementation
Setting only UniqueConstraint.fields creates a true database
constraint (ADD CONSTRAINT ... UNIQUE). Specifying any of
UniqueConstraint.expressions, UniqueConstraint.opclasses,
UniqueConstraint.condition, or UniqueConstraint.include
creates a unique index (CREATE UNIQUE INDEX) instead.
In this documentation, the term "unique constraint" is used for both cases to mean a uniqueness guarantee enforced by the database.
expressions¶
- UniqueConstraint.expressions¶
位置引数 *expressions により、式やデータベース関数に対する関数的なユニーク制約を作成できます。
例:
UniqueConstraint(Lower("name").desc(), "category", name="unique_lower_name_category")
これは name フィールドの小文字の値を降順で、category フィールドの値をデフォルトの昇順でユニーク制約を作成します。
関数的なユニーク制約は Index.expressions と同じデータベース制約を持ちます。
fields¶
- UniqueConstraint.fields¶
制約を適用したい一意な列のセットを表すフィールド名のリスト。
例:
UniqueConstraint(fields=["room", "date"], name="unique_booking")
それぞれの部屋がそれぞれの日付で1度だけ予約できることを保証します。
condition¶
- UniqueConstraint.condition¶
制約を適用したい条件を指定する Q オブジェクト。
例:
UniqueConstraint(fields=["user"], condition=Q(status="DRAFT"), name="unique_draft_user")
これは、各ユーザーが1つの DRAFT しか持たないことを保証します。
これらの condition は Index.condition と同じデータベースの制限を持ちます。
deferrable¶
- UniqueConstraint.deferrable¶
このパラメータを指定すると、遅延可能なユニーク制約を作成できます。使用可能な値は Deferrable.DEFERRED または Deferrable.IMMEDIATE です。例えば：
from django.db.models import Deferrable, UniqueConstraint
UniqueConstraint(
name="unique_order",
fields=["order"],
deferrable=Deferrable.DEFERRED,
)
デフォルトでは、制約は遅延 (DEFERRED) されません。遅延された制約は、トランザクションが終了するまで実行されません。即時 (IMMEDIATE) 制約は、すべてのコマンドの直後に実行されます。
Unique constraints with condition,
include, opclasses, or
expressions may be implemented as unique indexes
rather than unique constraints. In that case, deferrable cannot be set.
MySQL, MariaDB, SQLite の場合
MySQL、MariaDB、SQLite では、遅延可能な一意性制約はサポートされていないため無視されます。
警告
遅延ユニーク制約は、パフォーマンスへのペナルティ を引き起こす可能性があります。
include¶
- UniqueConstraint.include¶
ユニークなカバリングインデックス (covering index) に非キー列として含めるフィールド名のリストまたはタプル。これにより、include されたフィールドだけを SELECT するクエリと、 (include)、ユニークなフィールドだけでフィルタリングする(fields) クエリにインデックスだけのスキャンを使用できます。
例:
UniqueConstraint(name="unique_booking", fields=["room", "date"], include=["full_name"])
この設定では、room と date によるフィルタリング、full_name の SELECT の際にデータをインデックスからのみ取得します。
PostgreSQL以外のデータベースでは、非キー列を持つユニーク制約は無視されます。
非キーカラムは Index.include と同じデータベース制約を持ちます。
opclasses¶
- UniqueConstraint.opclasses¶
この一意なインデックスに使用する PostgreSQL operator クラス の名前です。カスタム演算子クラスが必要な場合は、インデックスの各フィールドに1つずつ指定しなければなりません。
例:
UniqueConstraint(
name="unique_username", fields=["username"], opclasses=["varchar_pattern_ops"]
)
これは username に varchar_pattern_ops を使用する一意なインデックスを作成します。
opclasses はPostgreSQL以外のデータベースでは無視されます。
nulls_distinct¶
- UniqueConstraint.nulls_distinct¶
ユニーク制約の対象となる NULL 値を含む行を、互いに異なる行とみなすかどうかを指定します。デフォルト値は None で、ほとんどのバックエンドで True となるデータベースのデフォルト値を使用します。
例:
UniqueConstraint(name="ordering", fields=["ordering"], nulls_distinct=False)
これは、 ordering カラムに NULL 値を格納できるのは1行だけというユニーク制約を作成します。
nulls_distinct によるユニーク制約は、PostgreSQL 15+ 以外のデータベースでは無視されます。
violation_error_code¶
- UniqueConstraint.violation_error_code¶
model validation 中に ValidationError が発生した場合に使用されるエラーコードです。
UniqueConstraint.condition が設定されているか、 UniqueConstraint.fields が設定されていない場合、デフォルトで BaseConstraint.violation_error_code になります。
UniqueConstraint.condition を伴わずに UniqueConstraint.fields が設定された場合、フィールドが複数あるときは Meta.unique_together のエラーコードがデフォルトとなり、フィールドが単一のときは Field.unique のエラーコードがデフォルトとなります。
古いバージョンでは、UniqueConstraint.condition が設定されずに UniqueConstraint.fields のみが指定された場合には、指定された UniqueConstraint.violation_error_code は使用されません。
violation_error_message¶
- UniqueConstraint.violation_error_message¶
model validation 中に ValidationError が発生した場合に使用されるエラーメッセージです。
UniqueConstraint.condition が設定されているか、 UniqueConstraint.fields が設定されていない場合、 BaseConstraint.violation_error_message がデフォルトになります。
UniqueConstraint.condition を伴わずに UniqueConstraint.fields が設定された場合、フィールドが複数あるときは Meta.unique_together のエラーメッセージがデフォルトとなり、フィールドが単一のときは Field.unique のエラーメッセージがデフォルトとなります。
古いバージョンでは、UniqueConstraint.condition が設定されずに UniqueConstraint.fields のみが指定された場合には、指定された UniqueConstraint.violation_error_message は使用されません。
