# Documentation Django 3.1.9.dev

# `SchemaEditor`

class `BaseDatabaseSchemaEditor`

Le système des migrations de Django est partagé en deux parties : la logique pour le calcul et le stockage des opérations à exécuter (`django.db.migrations`) et la couche d’abstraction de base de données qui transforme des choses du genre « créer un modèle » ou « supprimer un champ » en code SQL, ce qui est le travail de `SchemaEditor`.

Il est peu probable que vous deviez interagir directement avec une instance `SchemaEditor` en tant que développeur régulier de Django, mais si vous souhaitez écrire votre propre système de migrations ou que vous avez des besoins plus pointus, c’est beaucoup plus agréable que d’avoir à écrire du code SQL.

Chae moteur de base de données dans Django fournit sa propre version de `SchemaEditor`, qui est toujours accessible via le gestionnaire de contexte `connection.schema_editor()`:

    with connection.schema_editor() as schema_editor:
        schema_editor.delete_model(MyModel)

Il doit être utilisé via le gestionnaire de contexte car cela permet de gérer des éléments comme les transactions et le code SQL différé (comme pour créer des contraintes de clé étrangère).

Cet éditeur expose toutes les opérations possibles sous forme de méthodes qui doivent être appelées dans l’ordre voulu d’application des changements. Certaines opérations ou types de modification ne sont pas toujours possibles en fonction de la base de données ; par exemple, le moteur MySQL `MyISAM` ne gère pas les contraintes de clé étrangère.

Si vous écrivez ou maintenez une moteur de base de données hors du code Django, vous allez devoir fournir une implémentation de `SchemaEditor` afin de pouvoir prendre en charge la fonctionnalité des migrations de Django. Toutefois, tant que la base de données en question respecte globalement les standards en terme de SQL et de conception relationnelle, il doit être possible d’hériter de l’une des classes `SchemaEditor` de Django et d’adapter légèrement la syntaxe.

## Méthodes

### `execute()`

`BaseDatabaseSchemaEditor.``execute`(sql, params=[])

Exécute l’instruction SQL transmise, compte tenu des paramètres s’il y en a. Il s’agit d’une adaptation autour des curseurs normaux des bases de données qui ajoute la possibilité de capturer le code SQL produit dans un fichier `.sql` si l’utilisateur le souhaite.

### `create_model()`

`BaseDatabaseSchemaEditor.``create_model`(model)

Crée une nouvelle table de base de données correspondant au modèle indiqué, y compris les contraintes d’unicité et les index nécessaires.

### `delete_model()`

`BaseDatabaseSchemaEditor.``delete_model`(model)

Supprime la table de base de données correspondant au modèle indiqué, ainsi que les éventuels contraintes d’unicité et index existants.

### `add_index()`

`BaseDatabaseSchemaEditor.``add_index`(model, index)

Ajoute `index` à la table de `model`.

### `remove_index()`

`BaseDatabaseSchemaEditor.``remove_index`(model, index)

Supprime `index` de la table de `model`.

### `add_constraint()`

`BaseDatabaseSchemaEditor.``add_constraint`(model, constraint)

Ajoute `constraint` à la table de `model`.

### `remove_constraint()`

`BaseDatabaseSchemaEditor.``remove_constraint`(model, constraint)

Supprime `constraint` de la table de `model`.

### `alter_unique_together()`

`BaseDatabaseSchemaEditor.``alter_unique_together`(model, old_unique_together, new_unique_together)

Modifie la valeur `unique_together` d’un modèle ; cette opération ajoute ou supprime les contraintes d’unicité de la table correspondant au modèle jusqu’à ce que la nouvelle valeur soit complètement reflétée dans la base de données.

### `alter_index_together()`

`BaseDatabaseSchemaEditor.``alter_index_together`(model, old_index_together, new_index_together)

Modifie la valeur `index_together` d’un modèle ; cette opération ajoute ou supprime les index de la table correspondant au modèle jusqu’à ce que la nouvelle valeur soit complètement reflétée dans la base de données.

### `alter_db_table()`

`BaseDatabaseSchemaEditor.``alter_db_table`(model, old_db_table, new_db_table)

Renomme la table correspondant au modèle de `old_db_table` vers `new_db_table`.

### `alter_db_tablespace()`

`BaseDatabaseSchemaEditor.``alter_db_tablespace`(model, old_db_tablespace, new_db_tablespace)

Déplace la table correspondant au modèle d’un espace de tables vers un autre.

### `add_field()`

`BaseDatabaseSchemaEditor.``add_field`(model, field)

Ajoute une colonne (ou parfois plusieurs) à la table correspondant au modèle pour représenter le champ indiqué. Cette opération peut aussi ajouter un index ou une contrainte d’unicité en fonction des paramètres `db_index` et `unique` du champ.

Si le champ est une instance `ManyToManyField` sans valeur spécifique pour `through`, cette méthode crée une table pour représenter la relation au lieu de créer une colonne. Si `through` est spécifié pour ce champ, il s’agit d’une opération blanche.

Si le champ est une instance `ForeignKey`, cette méthode ajoute aussi les contraintes de clé étrangère pour la colonne concernée.

### `remove_field()`

`BaseDatabaseSchemaEditor.``remove_field`(model, field)

Enlève la ou les colonnes représentant le champ dans la table correspondant au modèle, ainsi que toutes éventuelles contraintes d’unicité, de clé étrangère ou d’index qui auraient été créés pour ce champ.

Si le champ est une instance `ManyToManyField` sans valeur spécifique pour `through`, cette méthode supprime la table créée pour établir la relation. Si `through` est spécifié pour ce champ, il s’agit d’une opération blanche.

### `alter_field()`

`BaseDatabaseSchemaEditor.``alter_field`(model, old_field, new_field, strict=False)

Cette méthode transforme le champ de modèle `old_field` pour qu’il corresponde à `new_field`. Cela inclut le changement de nom de colonne (l’attribut `db_column`), le changement de type de champ (si la classe du champ est différente), le changement de l’état `NULL` du champ, l’ajout ou la suppression de contraintes d’unicité ou d’index liés à un seul champ, le changement de l’état clé primaire et le changement de la destination d’une contrainte `ForeignKey`.

La transformation la plus courante que cette méthode ne peut pas faire est la transformation d’un champ `ManyToManyField` en un champ normal et inversement ; Django ne peut pas faire cela sans perdre des données, il va donc refuser de le faire. Pour le faire quand même, il faut ajouter séparément des opérations de suppression (`remove_field()`) et d’ajout (`add_field()`) de champ.

Si la base de données prend en charge les modifications combinées (drapeau `supports_combined_alters`), Django essaie de faire autant que possible ces opérations dans un seul appel à la base de données ; sinon, il émet une instruction ALTER séparée pour chaque modification, mais il n’émet pas d’instruction ALTER lorsqu’aucun changement n’est nécessaire.

## Attributs

Tous les attributs doivent être considérés en lecture seule, sauf mention contraire.

### `connection`

`SchemaEditor.``connection`

Un objet de connexion à la base de données. Un attribut utile de la connexion est `alias` qui peut être utilisé pour déterminer le nom de la base de données en cours d’accès.

C’est pratique lors de migrations de données pour des migrations avec plusieurs bases de données.