Ограничения базы данных, специфичные для 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. Для их использования необходимо активировать расширение btree_gist в PostgreSQL. Установить его можно с помощью операции миграции BtreeGistExtension.

Если вы попытаетесь вставить новую строку, которая конфликтует с существующей строкой, будет поднято исключение IntegrityError. Аналогично, при обновлении, если происходит конфликт.

Ограничения исключения проверяются во время валидации модели.

name

ExclusionConstraint.name

См. BaseConstraint.name.

expressions

ExclusionConstraint.expressions

Итерируемый набор из 2-х кортежей. Первый элемент — выражение или строка. Второй элемент — оператор SQL, представленный строкой. Чтобы избежать опечаток, вы можете использовать RangeOperators, который сопоставляет операторы со строками. Например:

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

Выражение OpClass() можно использовать для указания настраиваемого класса операторов для выражений ограничения. Например:

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

создаёт ограничение исключения для circle с помощью circle_ops.

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,
)

По умолчанию ограничения не откладываются. Отложенное ограничение не будет принудительно выполнено до конца транзакции. Немедленное ограничение будет принудительно выполнено немедленно после каждой команды.

include

ExclusionConstraint.include

Список или кортеж имён полей, которые должны быть включены в покрывающее ограничение исключения в качестве полей, не являющихся ключами. Это позволяет использовать индекс-только сканирования для запросов, которые выбирают только включённые поля (include) и фильтруют только по индексированным полям (expressions).

include поддерживается для индексов GiST. PostgreSQL 14+ также поддерживает include для индексов SP-GiST.

violation_error_code

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),
            ),
        ]

В случае, если ваша модель определяет диапазон, используя два поля, вместо собственных типов диапазонов 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),
            ),
        ]