# Django 6.0.7 - dokumentacja

# Constraints reference

The classes defined in this module create database constraints. They are added in the model `Meta.constraints` option.

Referencing built-in constraints

Constraints are defined in `django.db.models.constraints`, but for convenience they’re imported into `django.db.models`. The standard convention is to use `from django.db import models` and refer to the constraints as `models.<Foo>Constraint`.

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 `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(condition=Q(age__gte=18), name="%(app_label)s_%(class)s_is_adult")

Validation of Constraints

Constraints are checked during the model validation.

## `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.

All constraints have the following parameters in common:

### `name`

BaseConstraint.name

The name of the constraint. You must always specify a unique name for the constraint.

### `violation_error_code`

BaseConstraint.violation_error_code

The error code used when `ValidationError` is raised during model validation. Defaults to `None`.

### `violation_error_message`

BaseConstraint.violation_error_message

The error message used when `ValidationError` is raised during model validation. Defaults to `"Constraint “%(name)s” is violated."`.

### `validate()`

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(*, condition, name, violation_error_code=None, violation_error_message=None)

  Creates a check constraint in the database.

### `condition`

CheckConstraint.condition

A `Q` object or boolean `Expression` that specifies the conditional check you want the constraint to enforce.

For example:

    CheckConstraint(condition=Q(age__gte=18), name="age_gte_18")

ensures the age field is never less than 18.

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(
        condition=Q(age__gte=18) & Q(expensive_check=condition),
        name="age_gte_18_and_others",
    )

Oracle < 23c

Checks with nullable fields on Oracle < 23c must include a condition allowing for `NULL` values in order for `validate()` to behave the same as check constraints validation. For example, if `age` is a nullable field:

    CheckConstraint(condition=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18")

## `UniqueConstraint`

class UniqueConstraint(*expressions, fields=(), name, condition=None, deferrable=None, include=None, opclasses=(), nulls_distinct=None, violation_error_code=None, violation_error_message=None)

  Creates a uniqueness guarantee in the database, enforced by either a unique constraint or a unique index depending on the options used.

Constraint vs. index implementation

Setting only `UniqueConstraint.fields` creates a true database constraint (`ADD CONSTRAINT ... UNIQUE`). Specifying any of `UniqueConstraint.expressions`, `UniqueConstraint.opclasses`, `UniqueConstraint.condition`, or `UniqueConstraint.include` creates a unique index (`CREATE UNIQUE INDEX`) instead.

In this documentation, the term „unique constraint” is used for both cases to mean a uniqueness guarantee enforced by the database.

### `expressions`

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 `Index.expressions`.

### `fields`

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`

UniqueConstraint.condition

A `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 `Index.condition`.

### `deferrable`

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.

Unique constraints with `condition`, `include`, `opclasses`, or `expressions` may be implemented as unique indexes rather than unique constraints. In that case, `deferrable` cannot be set.

MySQL, MariaDB, and SQLite.

Deferrable unique constraints are ignored on MySQL, MariaDB, and SQLite as they do not support them.

Ostrzeżenie

Deferred unique constraints may lead to a performance penalty.

### `include`

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 (`include`) and filter only by unique fields (`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 `Index.include`.

### `opclasses`

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`

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.

### `violation_error_code`

UniqueConstraint.violation_error_code

The error code used when a `ValidationError` is raised during model validation.

Defaults to `BaseConstraint.violation_error_code`, when either `UniqueConstraint.condition` is set or `UniqueConstraint.fields` is not set.

If `UniqueConstraint.fields` is set without a `UniqueConstraint.condition`, defaults to the `Meta.unique_together` error code when there are multiple fields, and to the `Field.unique` error code when there is a single field.

### `violation_error_message`

UniqueConstraint.violation_error_message

The error message used when a `ValidationError` is raised during model validation.

Defaults to `BaseConstraint.violation_error_message`, when either `UniqueConstraint.condition` is set or `UniqueConstraint.fields` is not set.

If `UniqueConstraint.fields` is set without a `UniqueConstraint.condition`, defaults to the `Meta.unique_together` error message when there are multiple fields, and to the `Field.unique` error message when there is a single field.