===================== Constraints reference ===================== .. module:: django.db.models.constraints .. currentmodule:: django.db.models The classes defined in this module create database constraints. They are added in the model :attr:`Meta.constraints ` option. .. admonition:: Referencing built-in constraints Constraints are defined in ``django.db.models.constraints``, but for convenience they're imported into :mod:`django.db.models`. The standard convention is to use ``from django.db import models`` and refer to the constraints as ``models.Constraint``. .. admonition:: Constraints in abstract base classes You must always specify a unique name for the constraint. As such, you cannot normally specify a constraint on an abstract base class, since the :attr:`Meta.constraints ` option is inherited by subclasses, with exactly the same values for the attributes (including ``name``) each time. To work around name collisions, part of the name may contain ``'%(app_label)s'`` and ``'%(class)s'``, which are replaced, respectively, by the lowercased app label and class name of the concrete model. For example ``CheckConstraint(check=Q(age__gte=18), name='%(app_label)s_%(class)s_is_adult')``. .. admonition:: Validation of Constraints Constraints are checked during the :ref:`model validation `. .. admonition:: Validation of Constraints with ``JSONField`` Constraints containing :class:`~django.db.models.JSONField` may not raise validation errors as key, index, and path transforms have many database-specific caveats. This :ticket:`may be fully supported later <34059>`. You should always check that there are no log messages, in the ``django.db.models`` logger, like *"Got a database error calling check() on …"* to confirm it's validated properly. ``BaseConstraint`` ================== .. class:: BaseConstraint(* name, violation_error_code=None, violation_error_message=None) Base class for all constraints. Subclasses must implement ``constraint_sql()``, ``create_sql()``, ``remove_sql()`` and ``validate()`` methods. .. deprecated:: 5.0 Support for passing positional arguments is deprecated. All constraints have the following parameters in common: ``name`` -------- .. attribute:: BaseConstraint.name The name of the constraint. You must always specify a unique name for the constraint. ``violation_error_code`` ------------------------ .. versionadded:: 5.0 .. attribute:: BaseConstraint.violation_error_code The error code used when ``ValidationError`` is raised during :ref:`model validation `. Defaults to ``None``. ``violation_error_message`` --------------------------- .. attribute:: BaseConstraint.violation_error_message The error message used when ``ValidationError`` is raised during :ref:`model validation `. Defaults to ``"Constraint “%(name)s” is violated."``. ``validate()`` -------------- .. method:: BaseConstraint.validate(model, instance, exclude=None, using=DEFAULT_DB_ALIAS) Validates that the constraint, defined on ``model``, is respected on the ``instance``. This will do a query on the database to ensure that the constraint is respected. If fields in the ``exclude`` list are needed to validate the constraint, the constraint is ignored. Raise a ``ValidationError`` if the constraint is violated. This method must be implemented by a subclass. ``CheckConstraint`` =================== .. class:: CheckConstraint(*, check, name, violation_error_code=None, violation_error_message=None) Creates a check constraint in the database. ``check`` --------- .. attribute:: CheckConstraint.check A :class:`Q` object or boolean :class:`~django.db.models.Expression` that specifies the check you want the constraint to enforce. For example, ``CheckConstraint(check=Q(age__gte=18), name='age_gte_18')`` ensures the age field is never less than 18. .. admonition:: Expression order ``Q`` argument order is not necessarily preserved, however the order of ``Q`` expressions themselves are preserved. This may be important for databases that preserve check constraint expression order for performance reasons. For example, use the following format if order matters:: CheckConstraint( check=Q(age__gte=18) & Q(expensive_check=condition), name="age_gte_18_and_others", ) .. admonition:: Oracle Checks with nullable fields on Oracle must include a condition allowing for ``NULL`` values in order for :meth:`validate() ` to behave the same as check constraints validation. For example, if ``age`` is a nullable field:: CheckConstraint(check=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18") ``UniqueConstraint`` ==================== .. class:: UniqueConstraint(*expressions, fields=(), name=None, condition=None, deferrable=None, include=None, opclasses=(), nulls_distinct=None, violation_error_code=None, violation_error_message=None) Creates a unique constraint in the database. ``expressions`` --------------- .. attribute:: UniqueConstraint.expressions Positional argument ``*expressions`` allows creating functional unique constraints on expressions and database functions. For example:: UniqueConstraint(Lower("name").desc(), "category", name="unique_lower_name_category") creates a unique constraint on the lowercased value of the ``name`` field in descending order and the ``category`` field in the default ascending order. Functional unique constraints have the same database restrictions as :attr:`Index.expressions`. ``fields`` ---------- .. attribute:: UniqueConstraint.fields A list of field names that specifies the unique set of columns you want the constraint to enforce. For example, ``UniqueConstraint(fields=['room', 'date'], name='unique_booking')`` ensures each room can only be booked once for each date. ``condition`` ------------- .. attribute:: UniqueConstraint.condition A :class:`Q` object that specifies the condition you want the constraint to enforce. For example:: UniqueConstraint(fields=["user"], condition=Q(status="DRAFT"), name="unique_draft_user") ensures that each user only has one draft. These conditions have the same database restrictions as :attr:`Index.condition`. ``deferrable`` -------------- .. attribute:: UniqueConstraint.deferrable Set this parameter to create a deferrable unique constraint. Accepted values are ``Deferrable.DEFERRED`` or ``Deferrable.IMMEDIATE``. For example:: from django.db.models import Deferrable, UniqueConstraint UniqueConstraint( name="unique_order", fields=["order"], deferrable=Deferrable.DEFERRED, ) By default constraints are not deferred. A deferred constraint will not be enforced until the end of the transaction. An immediate constraint will be enforced immediately after every command. .. admonition:: MySQL, MariaDB, and SQLite. Deferrable unique constraints are ignored on MySQL, MariaDB, and SQLite as neither supports them. .. warning:: Deferred unique constraints may lead to a `performance penalty `_. ``include`` ----------- .. attribute:: UniqueConstraint.include A list or tuple of the names of the fields to be included in the covering unique index as non-key columns. This allows index-only scans to be used for queries that select only included fields (:attr:`~UniqueConstraint.include`) and filter only by unique fields (:attr:`~UniqueConstraint.fields`). For example:: UniqueConstraint(name="unique_booking", fields=["room", "date"], include=["full_name"]) will allow filtering on ``room`` and ``date``, also selecting ``full_name``, while fetching data only from the index. Unique constraints with non-key columns are ignored for databases besides PostgreSQL. Non-key columns have the same database restrictions as :attr:`Index.include`. ``opclasses`` ------------- .. attribute:: UniqueConstraint.opclasses The names of the `PostgreSQL operator classes `_ to use for this unique index. If you require a custom operator class, you must provide one for each field in the index. For example:: UniqueConstraint( name="unique_username", fields=["username"], opclasses=["varchar_pattern_ops"] ) creates a unique index on ``username`` using ``varchar_pattern_ops``. ``opclasses`` are ignored for databases besides PostgreSQL. ``nulls_distinct`` ------------------ .. versionadded:: 5.0 .. attribute:: UniqueConstraint.nulls_distinct Whether rows containing ``NULL`` values covered by the unique constraint should be considered distinct from each other. The default value is ``None`` which uses the database default which is ``True`` on most backends. For example:: UniqueConstraint(name="ordering", fields=["ordering"], nulls_distinct=False) creates a unique constraint that only allows one row to store a ``NULL`` value in the ``ordering`` column. Unique constraints with ``nulls_distinct`` are ignored for databases besides PostgreSQL 15+. ``violation_error_code`` ------------------------ .. versionadded:: 5.0 .. attribute:: UniqueConstraint.violation_error_code The error code used when ``ValidationError`` is raised during :ref:`model validation `. Defaults to ``None``. This code is *not used* for :class:`UniqueConstraint`\s with :attr:`~UniqueConstraint.fields` and without a :attr:`~UniqueConstraint.condition`. Such :class:`~UniqueConstraint`\s have the same error code as constraints defined with :attr:`.Field.unique` or in :attr:`Meta.unique_together `. ``violation_error_message`` --------------------------- .. attribute:: UniqueConstraint.violation_error_message The error message used when ``ValidationError`` is raised during :ref:`model validation `. Defaults to :attr:`.BaseConstraint.violation_error_message`. This message is *not used* for :class:`UniqueConstraint`\s with :attr:`~UniqueConstraint.fields` and without a :attr:`~UniqueConstraint.condition`. Such :class:`~UniqueConstraint`\s show the same message as constraints defined with :attr:`.Field.unique` or in :attr:`Meta.unique_together `.