- The schemas and queries part of MediaWiki core and WMF-maintained and -deployed extensions/skins should adhere to a set of common standards.
- The DBA review process from WMF for schema changes should be mandatory for these schema changes.
- Contributors should be able to find the workflow for proposing and implementing a schema change.
Previous policy (from 2015)
If you change the database schema, follow these rules:
- Update the installer – Please update includes/installer and add an appropriate SQL update file to maintenance/archives/. The naming convention, if you're adding a field, is patch-[table]-[field].sql. If you're removing a field, it's patch-drop-[table]-[field].sql. If you're adding a table, it's patch-[table].sql. Look at the commit history of includes/installer/ to find examples of how it's done. If you're adding a bunch of fields to the same table, make all those changes in one query in one patch file.
- Make your schema change optional – All schema changes must go through a period of being optional. Some examples:
- Instead of changing the format of a column, create a new column, make all writes happen to the old and new column (if it exists) and deprecate use of the old column. Check if the new column exists before blindly assuming that it does. Only eliminate support for the old column after it's clear the schema migration has completed and there's no chance that we'll need to roll back to the old version of the software. If this doesn't seem feasible, send mail to Wikitech-l asking for advice.
- You could set your new feature to only work if a config option is set to true, and set the option to false by default. Then the commit can be safely deployed before the schema change is made. To deploy your feature to the Wikimedia cluster, file a ticket in Phabricator in the relevant project with the #schema-change tag. Once you've confirmed the change has been made, you can remove the config option to enable your feature.
- Note that this means your schema change should be optional in code - for Wikimedia deployments, it is expected that every wiki with the relevant database table(s) will have the schema change applied to them. If you need different schema for different wikis, then apply the change using an extension and creating new tables dependent on that extension.
There might be cases where the "make your schema change optional" rule will be prohibitive from a performance or logistics perspective. However, schema changes like that should be rare to begin with, and should have prominent discussion on the Wikitech-l mailing list. In the case where it's impossible to make your schema change optional, it is still critical to write scripts to roll back to the pre-change state.
- Search for input from a WMF Database Administrator – MediaWiki is deployed to Wikimedia websites every week, and it takes considerable planning to apply schema changes to MySQL-based sites the size of Wikipedia. As of September 2017, Jaime Crespo (jcrespo on LDAP, jynus on irc and Manuel Arostegui, marostegui) are the best people to add to database reviews. In most cases, input is just needed on the logistics of the change.
- Test your changes on Beta - in particular, it is a common mistake to change indexes and column definitions that would result in different query plans. Try to test the generated queries' plan with tools such as EXPLAIN; not doing so could mean that, when scaled to production, queries that only take 1 second locally, they pileup on production when they receive much more traffic and have larger tables.