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.

rename_index()

New in Django 4.1.

BaseDatabaseSchemaEditor.rename_index(model, old_index, new_index)

Renomme old_index de la table model vers new_index.

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_table_comment()

New in Django 4.2.

BaseDatabaseSchemaEditor.alter_db_table_comment(model, old_db_table_comment, new_db_table_comment)

Modifie le commentaire de la table du model en utilisant new_db_table_comment.

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.