Règles de la base de données MediaWiki

Cette page décrit le code officiel des règles de la base de données MediaWiki. Il a été approuvé en décembre 2019 via le processus des RFC TechCom par la RFC T220056.

Requêtes dans la base de données

• Tout code nouveau qui envoie des requêtes SQL à partir de MediaWiki ne doit générer aucun avertissement en mode strict MariaDB / MySQL (d'après la RFC T112637).
  • WMF va activer le mode strict MariaDB / MySQL (T108255), qui sera dans tous les cas le mode par défaut de MySQL 5.7. Avant cela, le code doit être exempt de tout avertissement.
  • Le code qui accède à la base de données doit être compatible avec les modes SQL de MySQL suivants :
    • TRADITIONAL (équivalent à : STRICT_TRANS_TABLES, STRICT_ALL_TABLES, NO_ZERO_IN_DATE, NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO, NO_AUTO_CREATE_USER)
    • ONLY_FULL_GROUP_BY
• Le code de la base de données doit être compatible avec les anciennes versions des bases comme indiqué dans les contraintes d'installation MediaWiki pour le serveur de bases de données. Néanmoins les améliorations de performances qui ne s'appliquent uniquement qu'aux versions supportées les plus récentes (ou celles par défaut, ou largement recommandées par défaut) doivent être favorisées par rapport à celles qui concernent les versions non supportées.
• Les requêtes non déterministes ainsi que les commandes non sécurisées sur le binlog doivent être évitées parce qu'elles risquent de renvoyer ou d'écrire des résultats différents dans un environnement répliqué. Ce dernier cas peut être détecté par les avertissements concernant le binlog et dont le texte est « [Warning] Unsafe statement written to the binary log using statement format since BINLOG_FORMAT = STATEMENT ». Cela comprend INSERT ... SELECT lorsqu'une clé d'auto-incrémentation est utilisée, UPDATE ... LIMIT sans ORDER BY, et l'utilisation de fonctions non déterministes telles que SYSDATE(). Informations supplémentaires ici.

Modifications du schéma

• Chaque nouvelle table doit avoir une clé primaire. Lorsqu'un candidat ne peut être créé pour une clé primaire (par exemple, quand toutes les colonnes peuvent être répétées), il faut ajouter une colonne séparée d'auto-incrémentation, ou un autre champ arbitraire (selon le cas).
• Les clés primaires ainsi que les champs qui les référencent, doivent être non signés, afin d'augmenter les valeurs maximales.
• Toutes les tables du noyau MediaWiki et des extensions Wikimedia déployées, ainsi que celles des extensions MediaWiki embarquées, doivent être implémentées en utilisant le système de schéma abstrait et les nouvelles modifications du schéma à appliquer sur ces tables doivent être générées automatiquement.

Compatibilité des modifications du schéma

Les modifications du schéma doivent fournir un chemin pour la mise à jour de toutes les versions, à partir des deux versions LTS précédentes (voir phab:T259771).

Corrections dans la base de données

Si vous modifiez le schéma de la base de données, observez les règles suivantes :

• Mise à jour de installer – Mettez à jour includes/installer et ajoutez un fichier de patch approprié dans sql/abstractSchemaChanges/. La convention de nommage, si vous ajoutez un champ, est patch-{table}-{field}.sql. Pour la supression d'un champ utilisez patch-drop-{table}-{field}.sql. Pour ajouter une table, utilisez patch-{table}.sql. Voyez l'historique des commits de includes/installer/(MySQL|Postgres|SQLite)Updater.php pour avoir des exemple sur la manière de faire. Si vous ajoutez plusieurs champs à une même table, faites toutes les modifications dans une seule requête et dans un même fichier de correction.
• Rendez optionnels vos modifications de schéma – Chaque modification du schéma doit passer une période pendant laquelle elle est considérée facultative. Quelques exemples :
  • Au lieu de modifier le format d'une colonne, créez-en une nouvelle, faites que toutes les écritures se fassent sur l'ancienne et la nouvelle colonne (si elle existe), puis rendez obsolète l'utilisation de l'ancienne colonne. Vérifiez que la nouvelle colonne existe avant de supposer aveuglément qu'elle l'est réellement. Ne supprimez le support de l'ancienne colonne que lorsqu'il est clair que la migration du schéma est complètement terminée et qu'il n'y a aucune chance que l'on ait à revenir en arrière sur l'ancienne version du code. Si cela ne semble pas possible, envoyez un courriel à Wikitech-l pour demander conseil.
  • Vous pouvez déclarer que votre nouvelle fonction est opérationnelle que si une option de configuration vaut true, et initialiser cette dernière à false par défaut. Ensuite le commit peut être déployé sans crainte avant de faire la modification du schéma. Pour déployer votre fonction sur la grappe Wikimedia, remplissez un ticket sur Phabricator pour le projet concerné avec l'étiquette #schema-change . Une fois avoir confirmé que la modification a été faite, vous pouvez supprimer l'option de configuration permettant d'activer votre fonction.
  • Notez que cela signifie que vos modifications du schéma doivent être facultatives dans le code - pour les déploiements WikiMedia, il est attendu que chaque wiki avec ses tables de base de données se verra appliquer les corrections. Si vous avez besoin de schémas différents pour différents wikis, appliquez les modifications en utilisant une extension et la création des nouvelles tables dépendra de cette extension.

Il y a des cas où la règle « rendez facultatives vos modifications de schéma » serait contraire du point de vue des performances ou logistique. Néanmoins de telles modifications du schéma restent rares si on veut commencer par elles et doivent faire l'objet d'importantes discussions sur la liste de diffusion wikitech-l. Dans le cas où il est impossible de rendre facultatives les modifications de votre schéma, l'écriture de scripts pour restituer l'état antérieur reste discutable.

• Rechercher les entrées venant d'un administrateur de base de données de la WMF – MediaWiki est déployé chaque semaine sur les sites web Wikimedia, et cela demande une planification importante pour appliquer les modifications du schéma sur les sites basés sur MySQL représentant la taille de Wikipedia. Comme depuis janvier 2020 Jaime Crespo (jcrespo sur LDAP, jynus sur irc et Manuel Arostegui, marostegui) sont les meilleures personnes à ajouter aux relecteurs de la base de données. Dans la plupart des cas, l'entrée est simplement nécessaire pour la logistique des modifications.
• Testez vos modifications sur Bêta - en particulier, une erreur habituelle consiste à modifier les index et la définition des colonnes qui résulterait en différents plans de requêtes. Essayez de tester le plan des requêtes généré avec les outils tels que EXPLAIN; ne pas le faire pourrait signifier, quand porté à l'échelle de la production, que les requêtes qui ne prennent qu'une seconde localement, vont s'accumuler en production lorsqu'elles recevront davantage de traffic et utiliseront des tables plus grandes.

Note

Depuis MediaWiki 1.36, il ne prend en charge que les mises à jour effectuées depuis au plus, les deux dernières versions LTS uniquement (voir phab:T259771). Les mises à niveau à partir d'anciennes versions de MediaWiki devront être effectuées en plusieurs étapes. Ceci signifie que si vous voulez mettre à niveau avec 1.43 depuis 1.34 ou une version antérieure, vous devrez d'abord mettre à jour votre wiki 1.34 à 1.35 (ou 1.43), et, de 1.35 (ou 1.43), vous pourrez passer à 1.43.