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

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

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

name

ExclusionConstraint.name

См. BaseConstraint.name.

expressions

ExclusionConstraint.expressions

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

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

Ограничения для операторов.

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

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

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

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

Предупреждение

Отложенные ограничения исключения могут привести к performance penalty.

include

ExclusionConstraint.include

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

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

violation_error_code

ExclusionConstraint.violation_error_code

Код ошибки, используемый при возникновении ValidationError во время выполнения model validation. По умолчанию равен None.

violation_error_message

Сообщение об ошибке, используемое, когда ValidationError возникает во время model validation. По умолчанию используется 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, который обеспечивает отображение выражения для range boundaries. Например:

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),
            ),
        ]
Функции агрегации, специфичные для PostgreSQL
Выражения запросов, специфичные для PostgreSQL
Вернуться на верх