From 3eb9ccd93823c2ded8828ece65e1206a8fccba06 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 16 Nov 2026 17:59:13 +0100 Subject: [PATCH] docs: add a how-to to recover failed course scope migrations Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.rst | 2 +- docs/how-tos/index.rst | 1 + ...recover-failed-course-scope-migrations.rst | 41 +++++++++++++++++++ 3 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 docs/how-tos/recover-failed-course-scope-migrations.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 97764558..9c256be0 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -76,7 +76,7 @@ Fixed conflict regardless of priority, matching schema validation; only ``role_extensions`` are resolved by priority. This aligns the compiler with ADR 0031 and removes a path where a higher-priority file could silently replace a role's base definition. -* Migration ``0007_coursescope`` no longer fails with MySQL error 3780 when the platform's course table has a collation other than ``utf8mb4_unicode_ci``, because on MySQL it gives ``course_overview_id`` the collation of the course column it references before creating the foreign key (`#593 `_). +* Migration ``0007_coursescope`` no longer fails with MySQL error 3780 when the platform's course table has a collation other than ``utf8mb4_unicode_ci``, because on MySQL it gives ``course_overview_id`` the collation of the course column it references before creating the foreign key (`#593 `_). Databases where an earlier run of ``0007`` failed need the steps in :doc:`Recover From Failed Course Scope Migrations ` first. Changed ======== diff --git a/docs/how-tos/index.rst b/docs/how-tos/index.rst index 20f845d2..bb9c416e 100644 --- a/docs/how-tos/index.rst +++ b/docs/how-tos/index.rst @@ -5,3 +5,4 @@ How-tos :maxdepth: 1 use-built-in-constants + recover-failed-course-scope-migrations diff --git a/docs/how-tos/recover-failed-course-scope-migrations.rst b/docs/how-tos/recover-failed-course-scope-migrations.rst new file mode 100644 index 00000000..394aab22 --- /dev/null +++ b/docs/how-tos/recover-failed-course-scope-migrations.rst @@ -0,0 +1,41 @@ +Recover From Failed Course Scope Migrations +########################################### + +Recover From a Failed ``0007_coursescope`` Migration +**************************************************** + +Releases of openedx-authz before the fix for `issue #593`_ could stop ``./manage.py lms migrate`` at ``openedx_authz.0007_coursescope`` on MySQL databases whose default collation is not ``utf8mb4_unicode_ci``, such as the MySQL 8 default ``utf8mb4_0900_ai_ci``. The error looks like this: + +.. code-block:: text + + django.db.utils.OperationalError: (3780, "Referencing column 'course_overview_id' and referenced column 'id' in foreign key constraint 'openedx_authz_course_course_overview_id_e73fe24b_fk_course_ov' are incompatible.") + +MySQL does not run schema changes inside a transaction (see `Django migrations on MySQL`_), so the failed run leaves the ``openedx_authz_coursescope`` table behind without recording ``0007`` as applied. Every later ``migrate`` then fails with ``(1050, "Table 'openedx_authz_coursescope' already exists")``. Follow these steps to remove that table and apply the fixed migration. + +#. Back up the database. + +#. Open a MySQL shell on the LMS database and confirm that ``0007`` is not recorded as applied. This query must return no rows: + + .. code-block:: sql + + SELECT name FROM django_migrations + WHERE app = 'openedx_authz' AND name = '0007_coursescope'; + +#. Confirm that the table is empty. This query must return ``0``: + + .. code-block:: sql + + SELECT COUNT(*) FROM openedx_authz_coursescope; + + Stop here if either check fails, because the database is not in the state this procedure covers. + +#. Drop the table: + + .. code-block:: sql + + DROP TABLE openedx_authz_coursescope; + +#. Upgrade openedx-authz to a release that includes the fix, and run ``./manage.py lms migrate`` again. + +.. _issue #593: https://github.com/openedx/openedx-authz/issues/593 +.. _Django migrations on MySQL: https://docs.djangoproject.com/en/5.2/topics/migrations/#mysql