Ограничения базы данных, специфичные для PostgreSQL

PostgreSQL поддерживает дополнительные ограничения целостности данных, доступные из модуля django.contrib.postgres.constraints. Они добавляются в модели в опции Meta.constraints.

ExclusionConstraint

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

Создаёт ограничение исключения в базе данных. Внутри PostgreSQL ограничения исключения реализуются с помощью индексов. Тип индекса по умолчанию — GiST. Для их использования необходимо активировать расширение btree_gist в PostgreSQL. Его можно установить с помощью операции миграции BtreeGistExtension.

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

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

Изменено в Django 4.1:

В более старых версиях ограничения исключения не проверялись во время валидации модели.

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.

opclasses

ExclusionConstraint.opclasses

Имена классов операторов PostgreSQL, которые нужно использовать для этого ограничения. Если вам нужен настраиваемый класс оператора, вы должны указать один для каждого выражения в ограничении.

Например:

ExclusionConstraint(
    name="exclude_overlapping_opclasses",
    expressions=[("circle", RangeOperators.OVERLAPS)],
    opclasses=["circle_ops"],
)

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

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