FOG has no guidance on upgrading the database server underneath it, and there is one FOG-specific hazard that makes the generic vendor instructions insufficient.
Framing matters here: the hazard is not "MariaDB 12/13 is unsupported." It is specifically that crossing the 11.4 boundary flips the default collation underneath an existing install.
What needs documenting
The mariadb-upgrade dance itself does not — that is standard and vendor-documented. The FOG-specific part is the collation trap:
commons/schema.php declares 71 tables as bare DEFAULT CHARSET=utf8 with no COLLATE, so they inherit the server default.- Before MariaDB 11.4 that resolves to
utf8mb3_general_ci. On 11.4+ it resolves to utf8mb3_uca1400_ai_ci.
- Upgrading MariaDB does not rewrite existing tables. So after the upgrade the schema is split: everything that already existed stays
general_ci, anything created afterward comes out uca1400_ai_ci.
- The split is silent until a varchar join crosses it, then it is
Illegal mix of collations. Most joins that would expose it are int-keyed and never will — which is exactly why it would sit undetected rather than failing loudly at upgrade time.
A fresh install on 11.4+ is self-consistent and unaffected. It is the upgrade path that splits.
Shape of the safe path
Roughly: back up -> upgrade -> mariadb-upgrade -> then explicitly pin the collation, either by setting
collation-server = utf8mb3_general_ci
in the FOG server's my.cnf, or by converting the schema wholesale to uca1400. Doing neither is the failure case.
Which of those FOG blesses is a maintainer decision and should not be guessed at in the doc. That is tracked in FOGProject/fogproject#1152, and this page should not assert an answer ahead of it.
Two things that block writing this today
1. It would be documenting around an open code gap. FOGProject/fogproject#1147 pins the collation on the tables FOG names explicitly; it does not touch the 71 bare declarations. Until those either name a collation or the server default is pinned by the installer, "upgrade MariaDB past 11.4" has no safe documented answer — the doc would be describing a workaround for something that arguably belongs in code. Worth waiting on #1152, or writing the page as an explicit warning-with-workaround and revising once #1152 lands.
2. No tested version floor exists. The claim that CHARSET=utf8mb3 works on MariaDB 10.5 is currently inference — it rests on an observed error being 1273 Unknown collation rather than 1115 Unknown character set, which is sound reasoning about resolution order but was never actually probed. Any doc asserting a supported-version range should rest on a real test matrix, not on that.
Source material
FOGProject/fogproject#1147 documents the mechanism and the full failure chain in a form that can be lifted directly — including the observed 1273 error, the 308 redirect it cascaded into, and why SHOW CREATE TABLE propagates an inherited collation into checked-in DDL.
Real-world case behind it: an update install on Rocky 9 / MariaDB 10.5.29 against FOG 1.6.0-beta.3572, where the schema manifest had been generated on MariaDB 11.8.8. It surfaced only as * Backing up database...Failed with nothing in any log.
Related: FOGProject/fogproject#1148, FOGProject/fogproject#1149.
FOG has no guidance on upgrading the database server underneath it, and there is one FOG-specific hazard that makes the generic vendor instructions insufficient.
Framing matters here: the hazard is not "MariaDB 12/13 is unsupported." It is specifically that crossing the 11.4 boundary flips the default collation underneath an existing install.
What needs documenting
The
mariadb-upgradedance itself does not — that is standard and vendor-documented. The FOG-specific part is the collation trap:commons/schema.phpdeclares 71 tables as bareDEFAULT CHARSET=utf8with noCOLLATE, so they inherit the server default.utf8mb3_general_ci. On 11.4+ it resolves toutf8mb3_uca1400_ai_ci.general_ci, anything created afterward comes outuca1400_ai_ci.Illegal mix of collations. Most joins that would expose it are int-keyed and never will — which is exactly why it would sit undetected rather than failing loudly at upgrade time.A fresh install on 11.4+ is self-consistent and unaffected. It is the upgrade path that splits.
Shape of the safe path
Roughly: back up -> upgrade ->
mariadb-upgrade-> then explicitly pin the collation, either by settingcollation-server = utf8mb3_general_ciin the FOG server's my.cnf, or by converting the schema wholesale to uca1400. Doing neither is the failure case.
Which of those FOG blesses is a maintainer decision and should not be guessed at in the doc. That is tracked in FOGProject/fogproject#1152, and this page should not assert an answer ahead of it.
Two things that block writing this today
1. It would be documenting around an open code gap. FOGProject/fogproject#1147 pins the collation on the tables FOG names explicitly; it does not touch the 71 bare declarations. Until those either name a collation or the server default is pinned by the installer, "upgrade MariaDB past 11.4" has no safe documented answer — the doc would be describing a workaround for something that arguably belongs in code. Worth waiting on #1152, or writing the page as an explicit warning-with-workaround and revising once #1152 lands.
2. No tested version floor exists. The claim that
CHARSET=utf8mb3works on MariaDB 10.5 is currently inference — it rests on an observed error being1273 Unknown collationrather than1115 Unknown character set, which is sound reasoning about resolution order but was never actually probed. Any doc asserting a supported-version range should rest on a real test matrix, not on that.Source material
FOGProject/fogproject#1147 documents the mechanism and the full failure chain in a form that can be lifted directly — including the observed
1273error, the 308 redirect it cascaded into, and whySHOW CREATE TABLEpropagates an inherited collation into checked-in DDL.Real-world case behind it: an update install on Rocky 9 / MariaDB 10.5.29 against FOG 1.6.0-beta.3572, where the schema manifest had been generated on MariaDB 11.8.8. It surfaced only as
* Backing up database...Failedwith nothing in any log.Related: FOGProject/fogproject#1148, FOGProject/fogproject#1149.