Ограничения базы данных, специфичные для 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 12+ и индексов SP-GiST в PostgreSQL 14+.

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