Gitea with MariaDB: Proper UTF8MB4 Collation Configuration
Background
When running Gitea with MariaDB, the Admin Self-Check may display a warning about the expected database collation.
Typical message:
Expected database collation: utf8mb4_0900_as_cs
This collation exists only in MySQL 8. MariaDB instead uses modern UCA 14 collations (e.g. utf8mb4_uca1400_as_cs).
Technical Difference
- MySQL 8 → utf8mb4_0900_as_cs (UCA 9.0)
- MariaDB 10.6+ / 11.x → utf8mb4_uca1400_as_cs (UCA 14.0)
Both variants are functionally equivalent:
- UTF8MB4
- Case-sensitive
- Accent-sensitive
- Modern Unicode sorting
Objective
- Enforce consistent UTF8MB4 usage
- Maintain uniform collation across all tables
- Avoid implicit character set conversions
- Ensure future-proof configuration for MariaDB
Recommended Configuration (MariaDB)
In the Gitea configuration file /path/to/app.ini:
[database] CHARSET = utf8mb4 CHARSET_COLLATION = utf8mb4_uca1400_as_cs
Important: The correct parameter is CHARSET_COLLATION. The older key „COLLATION“ is not used in newer versions.
Validation
1. Verify database default
in SQL Console
SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = 'giteadb';
Expected result:
utf8mb4 + utf8mb4_uca1400_as_cs
2. Verify table collations
SELECT TABLE_NAME, TABLE_COLLATION FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'giteadb' ORDER BY TABLE_NAME;
All tables should use the same collation.
3. Verify server defaults
SHOW VARIABLES LIKE 'character_set%'; SHOW VARIABLES LIKE 'collation%';
Important:
character_set_server = utf8mb4
The server default may differ from the database collation. What matters is consistency within the Gitea database.
Gitea Doctor Check
To verify configuration:
sudo -u git gitea doctor check --config /etc/gitea/app.ini
Expected result:
All checks OK No collation-related warnings
Note: The warning regarding utf8mb4_0900_as_cs is not applicable when using MariaDB, as that collation is MySQL 8 specific.
Troubleshooting
Warning still appears
- Ensure the correct app.ini file is being used
- Confirm CHARSET_COLLATION is properly set
- Restart the Gitea service after changes
- Re-run the Self-Check from the Admin panel
Multiple app.ini files exist
find /etc /var/lib -name app.ini
Only the configuration file referenced by the systemd service is relevant.
Tables use different collations
In this case, perform a uniform conversion:
ALTER TABLE <table> CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_uca1400_as_cs;
Result
- Gitea operates fully MariaDB-compliant
- No MySQL 8 dependency
- Consistent sorting and indexing
- No collation mismatch warnings
- Stable and future-proof deployment
Conclusion
When using MariaDB, do not attempt to enforce utf8mb4_0900_as_cs.
For MariaDB 10.6+ and 11.x, utf8mb4_uca1400_as_cs is the technically correct choice.