# Django 5.0.9.dev20240806133106 ドキュメント

# PostgreSQL 固有のデータベース制約

PostgreSQL は `django.contrib.postgres.constraints` モジュールから利用できる追加のデータ整合性制約をサポートしています。これらはモデル `Meta.constraints` オプションで追加されます。

## `ExclusionConstraint`

class `ExclusionConstraint`(*, name, expressions, index_type=None, condition=None, deferrable=None, include=None, violation_error_code=None, violation_error_message=None)

  データベースに排他制約を作成します。内部的には、PostgreSQLはインデックスを使用して排他制約を実装しています。デフォルトのインデックス型は GiST です。インデックスを使用するには、PostgreSQLで btree_gist extension を有効にする必要があります。 `BtreeGistExtension` マイグレーションオペレーションを使ってインストールできます。

  既存の行と競合する新しい行を挿入しようとすると、`IntegrityError` が発生します。更新が既存の行と競合する場合も同様です。

  排他制約は モデル バリデーション の間にチェックされます。

### `name`

`ExclusionConstraint.``name`

`BaseConstraint.name` を参照。

### `expressions`

`ExclusionConstraint.``expressions`

2値タプルのイテラブル。最初の要素は式または文字列。2番目の要素は文字列で表現された SQL 演算子です。タイプミスを避けるために、演算子を文字列でマップする `RangeOperators` を使用できます。たとえば:

    expressions = [
        ("timespan", RangeOperators.ADJACENT_TO),
        (F("room"), RangeOperators.EQUAL),
    ]

演算子の制約

排他制約には可換演算子のみ使用できます。

`OpClass()` 式は、制約式のカスタム operator class を指定するために使用できます。たとえば:

    expressions = [
        (OpClass("circle", name="circle_ops"), RangeOperators.OVERLAPS),
    ]

これは `circle_ops` を使用して `circle` 上に排他制約を作成します。

### `index_type`

`ExclusionConstraint.``index_type`

制約のインデックスタイプです。受け入れられる値は `GIST` または `SPGIST` です。大文字小文字を区別しません。指定されていない場合、デフォルトのインデックスタイプは `GIST` です。

### `condition`

`ExclusionConstraint.``condition`

行の一部に制約をかける条件を指定する `Q` オブジェクト。たとえば、 `condition=Q(cancelled=False)` 。

これらの条件は、 `django.db.models.Index.condition` と同じデータベースの制約事項を持ちます。

### `deferrable`

`ExclusionConstraint.``deferrable`

遅延可能な排他制約を作成するには、このパラメータを設定します。使用可能な値は `Deferrable.DEFERRED` または `Deferrable.IMMEDIATE` です。例:

    from django.contrib.postgres.constraints import ExclusionConstraint
    from django.contrib.postgres.fields import RangeOperators
    from django.db.models import Deferrable

    ExclusionConstraint(
        name="exclude_overlapping_deferred",
        expressions=[
            ("timespan", RangeOperators.OVERLAPS),
        ],
        deferrable=Deferrable.DEFERRED,
    )

デフォルトでは、制約は遅延 (DEFERRED) されません。遅延された制約は、トランザクションが終了するまで実行されません。即時 (IMMEDIATE) 制約は、すべてのコマンドの直後に実行されます。

警告

排他制約の遅延は、パフォーマンスの悪化 performance penalty につながるかも知れません。

### `include`

`ExclusionConstraint.``include`

非キー列としてカバリング排他制約に含めるフィールド名のリストまたはタプル。これにより、含まれるフィールドのみを選択し (`include`)、インデックス化されたフィールドのみでフィルタリングする (`expressions`) クエリにインデックスのみのスキャンを使用できます。

`include` は GiST インデックスでサポートされています。PostgreSQL 14+ では、SP-GiST インデックスでも `include` がサポートされています。

### `violation_error_code`

New in Django 5.0.

`ExclusionConstraint.``violation_error_code`

モデルのバリデーション 中に `ValidationError` が発生した場合に使用されるエラーコードです。デフォルトは `None` です。

### `violation_error_message`

モデルのバリデーション 中に `ValidationError` が発生した場合に使用されるエラーメッセージです。デフォルトは `BaseConstraint.violation_error_message` です。

### 例

次の例では、キャンセルされた予約を考慮せずに、同じ部屋での重複する予約を制限しています。

    from django.contrib.postgres.constraints import ExclusionConstraint
    from django.contrib.postgres.fields import DateTimeRangeField, RangeOperators
    from django.db import models
    from django.db.models import Q

    class Room(models.Model):
        number = models.IntegerField()

    class Reservation(models.Model):
        room = models.ForeignKey("Room", on_delete=models.CASCADE)
        timespan = DateTimeRangeField()
        cancelled = models.BooleanField(default=False)

        class Meta:
            constraints = [
                ExclusionConstraint(
                    name="exclude_overlapping_reservations",
                    expressions=[
                        ("timespan", RangeOperators.OVERLAPS),
                        ("room", RangeOperators.EQUAL),
                    ],
                    condition=Q(cancelled=False),
                ),
            ]

モデルが2つのフィールドを使用して範囲を定義する場合、PostgreSQLのネイティブな範囲型ではなく、同等の関数 (例えば `TsTzRange()`) を使用する式を記述し、フィールドの区切り文字を使用する必要があります。ほとんどの場合、区切り文字は `'[)'` となり、下限は包括的で上限は排他的であることを意味します。 範囲境界 の式マッピングを提供する `RangeBoundary` を使用できます。たとえば:

    from django.contrib.postgres.constraints import ExclusionConstraint
    from django.contrib.postgres.fields import (
        DateTimeRangeField,
        RangeBoundary,
        RangeOperators,
    )
    from django.db import models
    from django.db.models import Func, Q

    class TsTzRange(Func):
        function = "TSTZRANGE"
        output_field = DateTimeRangeField()

    class Reservation(models.Model):
        room = models.ForeignKey("Room", on_delete=models.CASCADE)
        start = models.DateTimeField()
        end = models.DateTimeField()
        cancelled = models.BooleanField(default=False)

        class Meta:
            constraints = [
                ExclusionConstraint(
                    name="exclude_overlapping_reservations",
                    expressions=[
                        (
                            TsTzRange("start", "end", RangeBoundary()),
                            RangeOperators.OVERLAPS,
                        ),
                        ("room", RangeOperators.EQUAL),
                    ],
                    condition=Q(cancelled=False),
                ),
            ]