# Django 6.0.7 ドキュメント

# 制約 (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()`

BaseConstraint.validate(model, instance, exclude=None, using=DEFAULT_DB_ALIAS)

モデル `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, 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行だけというユニーク制約を作成します。

Unique constraints with `nulls_distinct` are ignored for databases besides PostgreSQL.

### `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` のエラーコードがデフォルトとなります。

### `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` のエラーメッセージがデフォルトとなります。