Add management command to fix UUID fields under MariaDB / Django 5.0 (#11912)

docs/reference/management_commands.md

@@ -164,3 +164,13 @@ Options:
 
 -  `--purge-only` :
     This argument will purge all image renditions without regenerating them. They will be regenerated when next requested.
+
+(convert_mariadb_uuids)=
+
+## convert_mariadb_uuids
+
+```sh
+./manage.py convert_mariadb_uuids
+```
+
+For sites using MariaDB, this command must be run once when upgrading to Django 5.0 and MariaDB 10.7 from any earlier version of Django or MariaDB. This is necessary because Django 5.0 introduces support for MariaDB's native UUID type, breaking backwards compatibility with `CHAR`-based UUIDs used in earlier versions of Django and MariaDB. New sites created under Django 5.0+ and MariaDB 10.7+ are unaffected.

docs/releases/5.2.5.md

@@ -15,3 +15,15 @@ depth: 1
 
  * Respect `WAGTAIL_ALLOW_UNICODE_SLUGS` setting when auto-generating slugs (LB (Ben) Johnston)
  * Use correct URL when redirecting back to page search results after an AJAX search (Sage Abdullah)
+
+## Upgrade considerations
+
+### Changes to UUID fields on MariaDB when upgrading to Django 5.0
+
+Django 5.0 introduces support for MariaDB's native UUID type on MariaDB 10.7 and above. This breaks backwards compatibility with `CHAR`-based UUIDs created on earlier versions of Django and MariaDB, and so upgrading a site to Django 5.0+ and MariaDB 10.7+ is liable to result in errors such as `Data too long for column 'translation_key' at row 1` or `Data too long for column 'uuid' at row 1` when creating or editing pages. To fix this, it is necessary to run the [`convert_mariadb_uuids`](convert_mariadb_uuids) management command (available as of Wagtail 5.2.5) after upgrading:
+
+```sh
+./manage.py convert_mariadb_uuids
+```
+
+This will convert all existing UUID fields used by Wagtail to the new format. New sites created under Django 5.0+ and MariaDB 10.7+ are unaffected.

docs/releases/5.2.md

@@ -219,6 +219,18 @@ As part of our [adoption of Stimulus](https://github.com/wagtail/rfcs/blob/main/
  * Add better deprecation warnings to the `search.Query` & `search.QueryDailyHits` model, move final set of templates from the admin search module to the search promotions contrib module (LB (Ben) Johnston)
 
 
+## Upgrade considerations - changes affecting all projects
+
+### Changes to UUID fields on MariaDB when upgrading to Django 5.0
+
+Django 5.0 introduces support for MariaDB's native UUID type on MariaDB 10.7 and above. This breaks backwards compatibility with `CHAR`-based UUIDs created on earlier versions of Django and MariaDB, and so upgrading a site to Django 5.0+ and MariaDB 10.7+ is liable to result in errors such as `Data too long for column 'translation_key' at row 1` or `Data too long for column 'uuid' at row 1` when creating or editing pages. To fix this, it is necessary to run the [`convert_mariadb_uuids`](convert_mariadb_uuids) management command (available as of Wagtail 5.2.5) after upgrading:
+
+```sh
+./manage.py convert_mariadb_uuids
+```
+
+This will convert all existing UUID fields used by Wagtail to the new format. New sites created under Django 5.0+ and MariaDB 10.7+ are unaffected.
+
 ## Upgrade considerations - deprecation of old functionality
 
 ### Legacy moderation system is deprecated

docs/releases/6.0.3.md

@@ -16,3 +16,15 @@ depth: 1
  * Respect `WAGTAIL_ALLOW_UNICODE_SLUGS` setting when auto-generating slugs (LB (Ben) Johnston)
  * Use correct URL when redirecting back to page search results after an AJAX search (Sage Abdullah)
  * Reinstate missing static files in style guide (Sage Abdullah)
+
+## Upgrade considerations
+
+### Changes to UUID fields on MariaDB when upgrading to Django 5.0
+
+Django 5.0 introduces support for MariaDB's native UUID type on MariaDB 10.7 and above. This breaks backwards compatibility with `CHAR`-based UUIDs created on earlier versions of Django and MariaDB, and so upgrading a site to Django 5.0+ and MariaDB 10.7+ is liable to result in errors such as `Data too long for column 'translation_key' at row 1` or `Data too long for column 'uuid' at row 1` when creating or editing pages. To fix this, it is necessary to run the [`convert_mariadb_uuids`](convert_mariadb_uuids) management command (available as of Wagtail 6.0.3) after upgrading:
+
+```sh
+./manage.py convert_mariadb_uuids
+```
+
+This will convert all existing UUID fields used by Wagtail to the new format. New sites created under Django 5.0+ and MariaDB 10.7+ are unaffected.

docs/releases/6.0.md

@@ -283,6 +283,16 @@ The `use_json_field` argument to `StreamField` is no longer required, and can be
 
 ## Upgrade considerations - changes affecting all projects
 
+### Changes to UUID fields on MariaDB when upgrading to Django 5.0
+
+Django 5.0 introduces support for MariaDB's native UUID type on MariaDB 10.7 and above. This breaks backwards compatibility with `CHAR`-based UUIDs created on earlier versions of Django and MariaDB, and so upgrading a site to Django 5.0+ and MariaDB 10.7+ is liable to result in errors such as `Data too long for column 'translation_key' at row 1` or `Data too long for column 'uuid' at row 1` when creating or editing pages. To fix this, it is necessary to run the [`convert_mariadb_uuids`](convert_mariadb_uuids) management command (available as of Wagtail 6.0.3) after upgrading:
+
+```sh
+./manage.py convert_mariadb_uuids
+```
+
+This will convert all existing UUID fields used by Wagtail to the new format. New sites created under Django 5.0+ and MariaDB 10.7+ are unaffected.
+
 ### `SnippetViewSet` & `ModelViewSet` copy view enabled by default
 
 The newly introduced copy view will be enabled by default for all `ModelViewSet` and `SnippetViewSet` classes.

wagtail/management/commands/convert_mariadb_uuids.py

@@ -0,0 +1,43 @@
+from django.apps import apps
+from django.core.management.base import BaseCommand
+from django.db import connection, models
+
+from wagtail.models import (
+    BaseLogEntry,
+    BootstrapTranslatableMixin,
+    ReferenceIndex,
+    TranslatableMixin,
+)
+
+
+class Command(BaseCommand):
+    help = "Converts UUID columns from char type to the native UUID type used in MariaDB 10.7+ and Django 5.0+."
+
+    def convert_field(self, model, field_name, null=False):
+        if model._meta.get_field(field_name).model != model:
+            # Field is inherited from a parent model
+            return
+
+        if not model._meta.managed:
+            # The migration framework skips unmanaged models, so we should too
+            return
+
+        old_field = models.CharField(null=null, max_length=36)
+        old_field.set_attributes_from_name(field_name)
+
+        new_field = models.UUIDField(null=null)
+        new_field.set_attributes_from_name(field_name)
+
+        with connection.schema_editor() as schema_editor:
+            schema_editor.alter_field(model, old_field, new_field)
+
+    def handle(self, **options):
+        self.convert_field(ReferenceIndex, "content_path_hash")
+
+        for model in apps.get_models():
+            if issubclass(model, BaseLogEntry):
+                self.convert_field(model, "uuid", null=True)
+            elif issubclass(model, BootstrapTranslatableMixin):
+                self.convert_field(model, "translation_key", null=True)
+            elif issubclass(model, TranslatableMixin):
+                self.convert_field(model, "translation_key")