--- title: "Référence des contraintes" version: 6.1 locale: fr source: https://docs.djangoproject.com/fr/6.1/ref/models/constraints/ canonical: https://djangodocs.dev/fr/6.1/ref/models/constraints/ --- # 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`](/fr/6.1/ref/models/options/#django.db.models.Options.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`](/fr/6.1/topics/db/models/#module-django.db.models). La convention standard est d’utiliser `from django.db import models` et de se référer aux contraintes avec `models.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`](/fr/6.1/ref/models/options/#django.db.models.Options.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(condition=Q(age__gte=18), name="%(app_label)s_%(class)s_is_adult") > ``` > **Validation des contraintes** > > Les contraintes sont vérifiées durant la [validation des modèles](/fr/6.1/ref/models/instances/#validating-objects). ## `BaseConstraint` #### `class BaseConstraint(*name, violation_error_code=None, violation_error_message=None)` Classe de base pour toutes les contraintes. Les sous-classes doivent implémenter les méthodes `constraint_sql()`, `create_sql()`, `remove_sql()` et `validate()`. Toutes les contraintes partagent les paramètres suivants : ### `name` #### `BaseConstraint.name` Le nom de la contrainte. La contrainte doit toujours posséder un nom unique. ### `violation_error_code` #### `BaseConstraint.violation_error_code` Le code d’erreur utilisé lorsque `ValidationError` est générée pendant la [phase de validation des modèles](/fr/6.1/ref/models/instances/#validating-objects). Contient `None` par défaut. ### `violation_error_message` #### `BaseConstraint.violation_error_message` Le message d’erreur utilisé lorsque `ValidationError` est générée pendant la [phase de validation des modèles](/fr/6.1/ref/models/instances/#validating-objects). Contient par défaut `"La contrainte %(name)sn'est pas respectée"`. ### `validate()` #### `BaseConstraint.validate(model, instance, exclude=None, using=DEFAULT_DB_ALIAS)` Valide que la contrainte définie sur le modèle est respectée pour l’instance. Cela produira une requête vers la base de données pour s’assurer que la contrainte est bien respectée. Si des champs de la liste `exclude` sont nécessaires pour valider la contrainte, celle-ci sera ignorée. Génère `ValidationError` lorsque la contrainte n’est pas respectée. Cette méthode doit être implémentée par les sous-classes. ## `CheckConstraint` #### `class CheckConstraint(* (Keyword-only parameters separator (PEP 3102)), condition, name, violation_error_code=None, violation_error_message=None)` Crée une contrainte de vérification dans la base de données. ### `condition` #### `CheckConstraint.condition` Un objet [`Q`](/fr/6.1/ref/models/querysets/#django.db.models.Q) ou une [`Expression`](/fr/6.1/ref/models/expressions/#django.db.models.Expression) booléenne qui indique le contrôle conditionnel que la contrainte souhaitée doit appliquer. Par exemple : ``` CheckConstraint(condition=Q(age__gte=18), name="age_gte_18") ``` assure que le champ `age` n’est jamais plus petit que 18. > **Ordre des expressions** > > L’ordre des arguments `Q` n’est pas forcément préservé. Toutefois, l’ordre des expressions `Q` elles-mêmes est conservé. Cela peut être important pour les bases de données qui préservent l’ordre des expressions de contrôle de contrainte pour des raisons de performance. Par exemple, utilisez le format suivant si l’ordre est important : > > ``` > CheckConstraint( > condition=Q(age__gte=18) & Q(expensive_check=condition), > name="age_gte_18_and_others", > ) > ``` > **Oracle < 23c** > > Les contrôles avec des champs possiblement nuls avec Oracle \< 23c doivent inclure une condition autorisant les valeurs `NULL` afin que [`validate()`](#django.db.models.BaseConstraint.validate) se comporte de la même façon que la validation des contraintes de contrôle. Par exemple, si `age` est un champ pouvant être nul : > > ``` > 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`](#django.db.models.UniqueConstraint.fields) creates a true database > constraint (`ADD CONSTRAINT ... UNIQUE`). Specifying any of > [`UniqueConstraint.expressions`](#django.db.models.UniqueConstraint.expressions), [`UniqueConstraint.opclasses`](#django.db.models.UniqueConstraint.opclasses), > [`UniqueConstraint.condition`](#django.db.models.UniqueConstraint.condition), or [`UniqueConstraint.include`](#django.db.models.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` 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`](/fr/6.1/ref/models/indexes/#django.db.models.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=["room", "date"], name="unique_booking") ``` assure que chaque chambre ne peut être réservée qu’une seule fois par date. ### `condition` #### `UniqueConstraint.condition` Un objet [`Q`](/fr/6.1/ref/models/querysets/#django.db.models.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`](/fr/6.1/ref/models/indexes/#django.db.models.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. Unique constraints with [`condition`](#django.db.models.UniqueConstraint.condition), [`include`](#django.db.models.UniqueConstraint.include), [`opclasses`](#django.db.models.UniqueConstraint.opclasses), or [`expressions`](#django.db.models.UniqueConstraint.expressions) may be implemented as unique indexes rather than unique constraints. In that case, `deferrable` cannot be set. > **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. > **Warning** > > Les contraintes d’unicité différées peuvent amener à des [performances réduites](https://www.postgresql.org/docs/current/sql-createtable.html#id-1.9.3.85.9.4). ### `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`](#django.db.models.UniqueConstraint.include)) et qui ne filtrent que sur les champs indexés ([`fields`](#django.db.models.UniqueConstraint.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. Les contraintes d’unicité sur des colonnes n’étant pas des clés sont ignorées dans les bases de données autres que 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`](/fr/6.1/ref/models/indexes/#django.db.models.Index.include). ### `opclasses` #### `UniqueConstraint.opclasses` Les noms des [classes d’opérateurs PostgreSQL](https://www.postgresql.org/docs/current/indexes-opclass.html) à 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. ### `nulls_distinct` #### `UniqueConstraint.nulls_distinct` Indique si les lignes contenant des valeurs `NULL` couvertes par la contrainte d’unicité doivent être considérées comme distinctes les unes des autres. La valeur par défaut est `None`, ce qui indique que la valeur par défaut de la base de données est utilisée, celle-ci étant `True` pour la majorité des moteurs. Par exemple : ``` UniqueConstraint(name="ordering", fields=["ordering"], nulls_distinct=False) ``` crée une contrainte d’unicité qui n’autorise qu’une seule ligne à contenir une valeur `NULL` dans la colonne `ordering`. Unique constraints with `nulls_distinct` are ignored for databases besides PostgreSQL. ### `violation_error_code` #### `UniqueConstraint.violation_error_code` Le code d’erreur utilisé lorsque une erreur `ValidationError` est générée pendant la [phase de validation des modèles](/fr/6.1/ref/models/instances/#validating-objects). Vaut par défaut [`BaseConstraint.violation_error_code`](#django.db.models.BaseConstraint.violation_error_code), quand soit [`UniqueConstraint.condition`](#django.db.models.UniqueConstraint.condition) est définie ou que [`UniqueConstraint.fields`](#django.db.models.UniqueConstraint.fields) n’est pas définie. Si [`UniqueConstraint.fields`](#django.db.models.UniqueConstraint.fields) est défini sans attr:.UniqueConstraint.condition, la valeur par défaut est le code d’erreur de [`Meta.unique_together`](/fr/6.1/ref/models/options/#django.db.models.Options.unique_together) quand il y a plusieurs champs, et le code d’erreur de [`Field.unique`](/fr/6.1/ref/models/fields/#django.db.models.Field.unique) lorsqu’il n’y a qu’un seul champ. ### `violation_error_message` #### `UniqueConstraint.violation_error_message` Le message d’erreur utilisé lorsque une erreur `ValidationError` est générée pendant la [phase de validation des modèles](/fr/6.1/ref/models/instances/#validating-objects). Vaut par défaut [`BaseConstraint.violation_error_message`](#django.db.models.BaseConstraint.violation_error_message), quand soit [`UniqueConstraint.condition`](#django.db.models.UniqueConstraint.condition) est définie ou que [`UniqueConstraint.fields`](#django.db.models.UniqueConstraint.fields) n’est pas définie. Si [`UniqueConstraint.fields`](#django.db.models.UniqueConstraint.fields) est défini sans attr:.UniqueConstraint.condition, la valeur par défaut est le message d’erreur de [`Meta.unique_together`](/fr/6.1/ref/models/options/#django.db.models.Options.unique_together) quand il y a plusieurs champs, et le message d’erreur de [`Field.unique`](/fr/6.1/ref/models/fields/#django.db.models.Field.unique) lorsqu’il n’y a qu’un seul champ.