Manual:Database layout/diagram instructions

Wiki-based diagram
Since January 2020, there is a wiki-based workflow that automates most of the diagram-drawing process.

How it works
There is a Lua module called  which is capable of parsing the SQL file that is part of the MediaWiki software. This file is used by MediaWiki to define the real tables and their structure, and the same file is used to visualise the diagram.

Pages such as Manual:Database layout/diagram invoke this Lua module with a reference to the SQL source, and a JSON structure that controls how to visualise it.

Create updated diagram
Use the below instructions to create a diagram for MediaWiki core (latest stable is currently: )


 * Create Template:SchemaDiagram/sql/mediawiki-.txt, and fill it with the contents of mediawiki/core.git@:/maintenance/tables.sql and mediawiki/core.git@:/maintenance/tables-generated.sql.
 * Go to "Page information" for Template:SchemaDiagram/sql/mediawiki-.txt, and change the content model from "wikitext" to "plain text".
 * Create Manual:Database layout/diagram/, using the contents of Manual:Database layout/diagram as starting point.
 * Make sure the  parameters referes to the correct MediaWiki version and release month (see MediaWiki version information).
 * Update  to point to SchemaDiagram/sql/mediawiki-.txt.
 * Use "Show preview" and look for any errors from Lua and address them before saving. The most common error is that the layout specifies a table that was removed in the latest version. Simply remove it from the  structure.
 * Also look out for Lua warnings of the form "Database table … not in the current layout". This indicates a new table was introduced, for which we will need to find a suitable place in the layout. If you are unfamiliar with this database table, there is likely a documentation page about it at Manual:Database layout which might explain more. If you're still unsure or if you want help deciding which group the new table fits in then ask MediaWiki developers via Wikitech-l or in the #mediawiki chat on IRC.
 * Feel free to add yourself to the  line.
 * Once it looks done, update the "Manual:Database layout/diagram" redirect to this new version.

Upload diagram to Wikimedia Commons
For archival reasons and for display on other wikis, you may want to ocasionally also capture a screenshot and upload it to Commons:


 * Go to Manual:Database layout/diagram/ and activate the "Full screen" button.
 * Use the browser's developer tools to capture a screenshot of the entire page
 * Firefox: Open the three-dots "Page action" menu, choose "Take a Screenshot". Then "Save full page".
 * Chrome: Menu bar "View" and choose "Developer" and "Developer Tools". Then open the command menu via ctrl-shift-P (Linux/Windows) or cmd-shift-P (macOS), and type "full size screen", and press Enter.
 * Upload to Commons via UploadWizard.
 * File name should be "MediaWiki database schema.png".
 * Make sure the right license and attribution are set (see bottom-right corner of the diagram).
 * Add category Category:MediaWiki database schemas.
 * After upload:
 * Edit the description page and add  to   in the Information template.
 * Update this redirect: File:MediaWiki database schema latest.svg (Yes, from svg to png. It's okay!)

Workbench diagram
From 2011 to 2019, schema diagrams were made using MySQL Workbench. The resulting workbench files have been published on GitHub at Krinkle/mwDatabaseSchema

Update the layout
Given that the workbench are hard-exported to Commons and can take a while to work through, it is recommended to figure out the layout before starting.


 * Compare  to the  below.
 * Remove any tables from the layout that no longer exist.
 * Any new tables need to be given a place in the layout. If the table has more than 10 fields, also create a "N fields" placeholder block. This is to help figure out which groups are very tall, which helps determine where to put the smaller tables.
 * If you're not sure what a table is about and in which group it belongs, reach out to other MediaWiki developers via Wikitech-l or in the #mediawiki chat on IRC.
 * Keep groups on the same row roughly the same height to avoid wasted space, for example by moving tables next to each other as needed.

Create the diagram

 * 1) Download and install MySQL Workbench.
 * 2) Download   (raw) from the latest stable MediaWiki version (currently:  ). Checkout the tag using Git, or download the tarball. If downloading from the web viewer, be sure to save as ".sql" instead of ".txt".
 * 3) Create new MySQL Workbench Model document.
 * 4) Look out for a "Templates" section that may contain an example "user" or "category" table by default. Delete these examples before the next step. Due to a bug, importing the MediaWiki schema will fail partially if these example templates are not deleted. (Workbench Version 6.3)
 * 5) Use "File / Import / Reverse Engineer SQL Script" to import MediaWiki's  . Be sure to use UTF-8 encoding and tick "Place imported objects on a diagram".Import of SQL script file '~/Downloads/.tables.sql' has finished. 40 tables, 0 views and 0 stored procedures were imported in 0 schemas.
 * 6) The tables are now drawn on the canvas. However, they are not yet organised or grouped. Use the  section as your guide, and create the necessary "Layer" objects.
 * 7) Export to SVG.
 * 8) Edit SVG and trim the excessive space from the  's ,  , and    attributes. Easiest is to open it in a browser, lower the   values until there is little space left on the right and bottom (but not cropped). Then update the width and height attributes as well. For example, for mediawiki-schema-1.24.1   was the generated element, and trimmed to.
 * 9) Upload to Commons as   (Do not overwrite any existing diagram on Commons).
 * 10) *Add  to the Information template.
 * 11) *Add the image to Category:MediaWiki database schemas.
 * 12) Update the commons: File:MediaWiki database schema latest.svg redirect.

Layout
This is a description of the annotations and composition we use to visualise the relationships between tables.

Credits

 * Dprutean, started this in 2009 with the MediaWiki 1.10 schema diagram, using the DbSchema software.
 * Nickj, re-created the MediaWiki 1.10 schema diagram using MySQL Workbench and started documenting how to update it.
 * Krinkle, updating the schema diagrams and documentation 2011–2019.