kde-apps/akonadi: Update IUSE=mysql instructions using readme.gentoo

Provide detailed instructions for how to fix existing backends.

Bug: https://bugs.gentoo.org/688746
Package-Manager: Portage-3.0.17, Repoman-3.0.2
Signed-off-by: Andreas Sturmlechner <asturm@gentoo.org>

2 files changed, 45 insertions, 9 deletions

diff --git a/kde-apps/akonadi/akonadi-20.12.3.ebuild b/kde-apps/akonadi/akonadi-20.12.3.ebuild
index 6f78d4f5ff9f..293720983608 100644
--- a/kde-apps/akonadi/akonadi-20.12.3.ebuild
+++ b/kde-apps/akonadi/akonadi-20.12.3.ebuild
@@ -9,7 +9,7 @@ KFMIN=5.75.0
 QTMIN=5.15.2
 VIRTUALDBUS_TEST="true"
 VIRTUALX_REQUIRED="test"
-inherit ecm kde.org
+inherit ecm kde.org readme.gentoo-r1
 
 DESCRIPTION="Storage service for PIM data and libraries for PIM apps"
 HOMEPAGE="https://community.kde.org/KDE_PIM/akonadi"
@@ -73,15 +73,9 @@ pkg_setup() {
 	use postgres && DRIVER="QPSQL"
 	use mysql && DRIVER="QMYSQL"
 
-	if use mysql && has_version ">=dev-db/mariadb-10.4"; then
-		ewarn "If an existing Akonadi QMYSQL database is being upgraded using"
-		ewarn ">=dev-db/mariadb-10.4 and KMail stops fetching and sending mail,"
-		ewarn "check ~/.local/share/akonadi/akonadiserver.error for errors like:"
-		ewarn "  \"Cannot add or update a child row: a foreign key constraint fails\""
+	if use mysql && has_version "${CATEGORY}/${PN}[mysql]" && has_version "dev-db/mariadb"; then
 		ewarn
-		ewarn "Manual steps are required to fix it, see also:"
-		ewarn "  https://bugs.gentoo.org/688746 (see Whiteboard)"
-		ewarn "  https://bugs.kde.org/show_bug.cgi?id=409224"
+		ewarn "Attention: Make sure to read README.gentoo after install."
 		ewarn
 	fi
 
@@ -116,6 +110,7 @@ EOF
 	doins "${T}"/akonadiserverrc
 
 	ecm_src_install
+	readme.gentoo_create_doc
 }
 
 pkg_postinst() {
@@ -126,4 +121,6 @@ pkg_postinst() {
 	use postgres && elog "  QPSQL"
 	use sqlite && elog "  QSQLITE3"
 	elog "${DRIVER} has been set as your default akonadi storage backend."
+	use mysql && elog
+	use mysql && FORCE_PRINT_ELOG=1 readme.gentoo_print_elog
 }
diff --git a/kde-apps/akonadi/files/README.gentoo b/kde-apps/akonadi/files/README.gentoo
new file mode 100644
index 000000000000..c778f6d1a211
--- /dev/null
+++ b/kde-apps/akonadi/files/README.gentoo
@@ -0,0 +1,39 @@
+Akonadi QMYSQL backends that were created using <dev-db/mariadb-10.5.9-r3 may
+be in need of a manual fix. Failure to do so could result in akonadi service
+to stop fetching and sending mail for KMail or any other kind of issues in PIM
+applications depending on akonadi like KOrganizer, KAddressBook etc.
+
+Note:
+  - All commands that follow are to be run by a regular user.
+  - They will have to be repeated for any other user of KDE PIM.
+  - Use your favorite terminal.
+
+  1) Check if "mysql" system db is present:
+     $ mysql -S /run/user/$(id -u)/akonadi/mysql.socket -e 'select schema_name \
+         from information_schema.schemata where schema_name = "mysql"'
+
+     The output obtained should look like this:
+        +-------------+
+        | schema_name |
+        +-------------+
+        | mysql       |
+        +-------------+
+
+     If so, then automatic DB upgrades will succeed, no further action necessary.
+
+  2) If, however, the above query returned empty, add the missing database:
+     $ mysql -S /run/user/$(id -u)/akonadi/mysql.socket -e 'create database mysql'
+
+     Future MariaDB releases should upgrade without manual intervention now.
+
+  3) Optional: You may have come here with an already defunct akonadi service.
+     To manually fix the akonadi MariaDB backend:
+     $ mysql_upgrade -S /run/user/$(id -u)/akonadi/default/mysql.socket \
+         --defaults-file=~/.local/share/akonadi/mysql.conf
+
+     Don't forget to restart the akonadi service afterwards:
+     $ akonadictl restart
+
+References:
+  [1] https://bugs.gentoo.org/688746
+  [2] https://bugs.kde.org/show_bug.cgi?id=409224