Published
Wiki source code of Convert the MySQL Installation documentation into the documentation tree
Last modified by Eleni Cojocariu on 2026/09/10 20:35
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | Conversion of [[MySQL Installation>>Documentation.AdminGuide.Installation.InstallationWAR.InstallationMySQL.WebHome]] into the documentation tree, following the Documentation Guide. The legacy page was treated as source material: every one of its 89 pieces of content was inventoried, checked against the platform sources and a running XWiki 18.6.0, and then either placed on one of the new pages (65 of them) or dropped as obsolete (24). | ||
| 2 | |||
| 3 | The new subtree takes the shape ##configure-oracle-manually## already sets, under ##install-relational-database##: | ||
| 4 | |||
| 5 | * **##configure-mysql##** (How-to) with the install steps, and below it | ||
| 6 | * **##storage-engine-character-set##** (Explanation) for why InnoDB and the ##utf8mb4_bin## pair are required, | ||
| 7 | * **##optional-indexes##** (Reference) for the indexes XWiki does not create itself, | ||
| 8 | * **##convert-database-utf8mb4##** and **##convert-myisam-tables-innodb##** (How-tos) for repairing a database that was created wrong, | ||
| 9 | * five error pages, one per failure the legacy Troubleshooting section covered: ##server-unreachable##, ##unknown-database##, ##server-timezone-unrecognized##, ##max-allowed-packet## and ##row-size-limit##. | ||
| 10 | |||
| 11 | **##configure-mariadb## is edited rather than created.** It existed already and said that MySQL and MariaDB are configured the same way, which is what let it stay short; it now carries only the differences. Three things it stated turned out to be wrong against the sources: | ||
| 12 | |||
| 13 | * it granted privileges ##ON xwiki.*##, but a farm needs ##ON *.*##: each subwiki is a database of its own, and creating one needs the right. The functional tests run MariaDB through the same ##startMySQLContainer## as MySQL and grant ##on *.*## for exactly that reason. | ||
| 14 | * it called ##utf8mb4## "strongly recommended". It is required, like everywhere else in this tree. | ||
| 15 | * it told the reader to run ##mysql##. Since MariaDB 11.0 that name is gone from the MariaDB images and the client is ##mariadb##. | ||
| 16 | |||
| 17 | The shipped ##hibernate.cfg.xml## template's MariaDB block differs from its MySQL block in exactly two values, the connection URL and the driver class, so those two are what the page shows. | ||
| 18 | |||
| 19 | **The biggest correction is a step that must not be published at all.** The legacy page asked the reader to run four ##ALTER TABLE ... LONGTEXT## statements by hand. Those exact tables and columns are migrated automatically by ##R130200000XWIKI17200DataMigration##, and have been since 12.10.6 / 13.2, so the statements are gone rather than carried over. | ||
| 20 | |||
| 21 | Dropped as obsolete, each because a supported version no longer behaves that way: the "MySQL versions older than 5.0" and "older than 5.7 and utf8mb4" sections, the "Incorrect string value" section (the connector window it describes exists only in the dead ##mysql-connector-java## artifact, and the JIRA issue it cites is closed as Won't Fix and narrower than the page claimed), "Can't create test file" (a 2007 transcript of MySQL 5.0.45 on OS X 10.4, embedding a developer's hostname), the Data Truncation section (pre-##cj## driver and DBCP 1) and the two MySQL 8 tips (##mysql_native_password## is unnecessary with the ##com.mysql.cj## driver, and the driver-class tip prescribes what the shipped configuration already contains). The ##-Dfile.encoding## advice buried in the dropped connector section survives, on ##storage-engine-character-set##. | ||
| 22 | |||
| 23 | There is **one screenshot**, on the root How-to's result step. The rest of the material is ##mysql## shell commands and ##hibernate.cfg.xml## snippets, which the pages show as code examples; the sibling database pages in this tree carry no screenshots either. | ||
| 24 | |||
| 25 | **The legacy page is stripped, not deleted**, the way its converted ##InstallationOracle## sibling already is: 15 of its 19 headings are kept verbatim, each pointing at the page that now carries it, so the anchors saved in old bookmarks and forum posts still resolve. Two of them are load-bearing: ##HTroubleshooting## is linked from the Debian/Ubuntu installation page and ##HIndexes## from Database Administration. The four dropped anchors are exactly the four obsolete sections above. The page has no attachments to delete. | ||
| 26 | |||
| 27 | Its backlinks are triaged in this change request as well: the tree's own hub, ##hsqldb-limitations## and ##backup.database-commands## in the new tree, and the legacy ##InstallationWAR##, ##InstallationViaAPT##, ##InstallationMariaDB## and ##Database Administration## pages. The Database Administration link is the one that asked for the indexes section, so it now points at ##optional-indexes## rather than at the root. The release note for 12.5 is deliberately left alone, since a release note records what was true then, and ##configure-mariadb##'s link disappears with the trim above. | ||
| 28 | |||
| 29 | Two things could not go into this change request, and are noted here so they are not mistaken for oversights: | ||
| 30 | |||
| 31 | * The **Extensions-wiki** backlink, in the ##installation## field of [[Extension.XWikiHelm>>extensions:Extension.XWikiHelm]]. A change request cannot span two wikis, so that one is applied separately on extensions.xwiki.org, pointing at ##convert-database-utf8mb4##, which is the conversion its sentence asks for. | ||
| 32 | * The **parent's navigation pin**. ##install-relational-database.WebPreferences## pins its eight children and also carries an ##XWiki.XWikiPreferences## xobject, which makes the change request application refuse a file change on it. Without that one value, ##configure-mysql## sorts after every pinned sibling and lands at the bottom of the database list instead of next to MariaDB. Could someone with rights on that page set ##pinnedChildPages## to: | ||
| 33 | |||
| 34 | {{code language="none"}} | ||
| 35 | configure-hsqldb/|configure-mariadb/|configure-mysql/|configure-postgresql-manually/|configure-postgresql-docker/|configure-oracle-manually/|configure-oracle-docker/|configure-oracle-vm/|use-container-managed-data-source/ | ||
| 36 | {{/code}} | ||
| 37 | |||
| 38 | The pin for the new subtree's own nine children is in this change request, as a ##configure-mysql.WebPreferences## file change: it puts the Explanation the hub introduces first at the top and the five error pages last, which is the order the hub's own prose and FAQ use, rather than the alphabetical-by-title order the tree would otherwise show. |
