Référence des contraintes¶
Les classes définies dans ce module créent des contraintes de base de données. Elles sont ajoutées dans l’option Meta.constraints des modèles.
Référencement des contraintes intégrées
Les contraintes sont définies dans django.db.models.constraints, mais par commodité elles sont importées dans django.db.models. La convention standard est d’utiliser from django.db import models et de se référer aux contraintes avec models.<Telle>Constraint.
Contraintes dans les classes de base abstraites
Les contraintes doivent toujours être nommées de façon unique. Cela signifie qu’il n’est pas possible de définir des contraintes dans une classe de base abstraite, dans la mesure où l’option Meta.constraints est héritée par les sous-classes avec exactement les mêmes valeurs d’attributs (y compris name). Pour éviter des collisions de nom, le nom peut contenir '%(app_label)s' et '%(class)s' qui seront remplacés respectivement par l’étiquette de l’application et le nom de la classe du modèle concret (tout en minuscules). Par exemple, CheckConstraint(check=Q(age__gte=18), name='%(app_label)s_%(class)s_is_adult').
Validation des contraintes
Constraints are checked during the model validation.
Validation of Constraints with JSONField
Constraints containing JSONField may not raise
validation errors as key, index, and path transforms have many
database-specific caveats. This may be fully supported later.
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.
In older versions, constraints were not checked during model validation.
BaseConstraint¶
-
class
BaseConstraint(name, violation_error_message=None)¶ Base class for all constraints. Subclasses must implement
constraint_sql(),create_sql(),remove_sql()andvalidate()methods.
All constraints have the following parameters in common:
name¶
-
BaseConstraint.name¶
Le nom de la contrainte. La contrainte doit toujours posséder un nom unique.
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(*, check, name, violation_error_message=None)¶ Crée une contrainte de vérification dans la base de données.
check¶
-
CheckConstraint.check¶
Un objet Q ou une Expression booléenne qui indique le contrôle que la contrainte souhaitée doit appliquer.
Par exemple, CheckConstraint(check=Q(age__gte=18), name='age_gte_18') s’assure que le champ age n’est jamais au-dessous de 18.
Oracle
Checks with nullable fields on Oracle 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(check=Q(age__gte=18) | Q(age__isnull=True), name='age_gte_18')
The violation_error_message argument was added.
UniqueConstraint¶
-
class
UniqueConstraint(*expressions, fields=(), name=None, condition=None, deferrable=None, include=None, opclasses=(), violation_error_message=None)¶ Crée une contrainte d’unicité dans la base de données.
expressions¶
-
UniqueConstraint.expressions¶
L’argument positionnel *expressions permet de créer des contraintes d’unicité fonctionnelles sur des expressions et des fonctions de base de données.
Par exemple :
UniqueConstraint(Lower('name').desc(), 'category', name='unique_lower_name_category')
crée une contrainte d’unicité sur la valeur en minuscules du champ name dans l’ordre alphabétique inverse et le champ category dans l’ordre alphabétique par défaut.
Les contraintes d’unicité basées sur des fonctions sont soumises aux même restrictions de base de données que Index.expressions.
fields¶
-
UniqueConstraint.fields¶
Une liste de noms de champs qui précise l’ensemble unique de colonnes pour lesquelles la contrainte va assurer l’unicité.
Par exemple, UniqueConstraint(fields=['chambre', 'date'], name='reservation_unique') s’assure que chaque chambre ne peut être réservée qu’une seule fois par date.
condition¶
-
UniqueConstraint.condition¶
Un objet Q qui indique la condition que la contrainte souhaitée doit appliquer.
Par exemple :
UniqueConstraint(fields=['user'], condition=Q(status='DRAFT'), name='unique_draft_user')
s’assure que chaque utilisateur dispose d’un seul brouillon.
Ces conditions sont soumises aux même restrictions de base de données que Index.condition.
deferrable¶
-
UniqueConstraint.deferrable¶
Définissez ce paramètre pour créer une contrainte d’unicité différable. Les valeurs acceptées sont Deferrable.DEFERRED ou Deferrable.IMMEDIATE. Par exemple
from django.db.models import Deferrable, UniqueConstraint
UniqueConstraint(
name='unique_order',
fields=['order'],
deferrable=Deferrable.DEFERRED,
)
Par défaut, les contraintes ne sont pas différées. Une contrainte différée ne sera pas appliquée avant la fin de la transaction. Une contrainte immédiate sera appliquée immédiatement après chaque commande.
MySQL, MariaDB et SQLite.
Les contraintes d’unicité différables sont ignorées avec MySQL, MariaDB et SQLite car ces moteurs ne les prennent pas en charge.
Avertissement
Les contraintes d’unicité différées peuvent amener à des performances réduites.
include¶
-
UniqueConstraint.include¶
Une liste ou un tuple de noms de champs à inclure dans l’index unique couvrant, représentant des colonnes qui ne sont pas des clés. Cela permet des analyses en index pur avec des requêtes qui ne sélectionnent que les champs inclus (include) et qui ne filtrent que sur les champs indexés (fields).
Par exemple :
UniqueConstraint(name='unique_booking', fields=['room', 'date'], include=['full_name'])
permettra le filtrage sur room et date, sélectionnant aussi full_name, tout en ne récupérant les données qu’à partir de l’index.
include n’est pris en charge que par PostgreSQL.
Les colonnes qui ne sont pas des clés sont soumises aux même restrictions de base de données que pour Index.include.
opclasses¶
-
UniqueConstraint.opclasses¶
Les noms des classes d’opérateurs PostgreSQL à utiliser pour cet index unique. Si vous nécessitez une classe d’opérateur personnalisée, vous devez en fournir une pour chaque champ de l’index.
Par exemple :
UniqueConstraint(name='unique_username', fields=['username'], opclasses=['varchar_pattern_ops'])
crée un index unique sur username en utilisant varchar_pattern_ops.
opclasses est ignoré pour les bases de données autres que PostgreSQL.
violation_error_message¶
-
UniqueConstraint.violation_error_message¶
The error message used when ValidationError is raised during
model validation. Defaults to
BaseConstraint.violation_error_message.
This message is not used for UniqueConstraints with
fields and without a
condition. Such UniqueConstraints show the
same message as constraints defined with
Field.unique or in
Meta.unique_together.
