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.
 * 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.
 * Once it looks done, update the "Manual:Database layout/diagram" redirect to this new version.

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 it to  MediaWiki.
 * 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.