LMS Migration Without Losing a Single Grade

Content moves easily. Records don't. Every migration rescue we've been called into — and we've done plenty — traces back to one of three gaps that standard export tools simply don't cover.

1. SCORM packages don't carry runtime history. The .zip you export from Blackboard or Brightspace contains the course itself. The tracking data — cmi.core.lesson_status, cmi.completion_status, scores, attempt timestamps — lives in the platform's database and never travels with the package. Re-upload that package on the new platform and every learner starts from zero.

2. Most platforms have no historical-import API. Canvas will happily accept a current grade through its Submissions API. It has no endpoint for "this student scored 71% on attempt two in March 2024." Neither does Blackboard. Neither does Brightspace. If a vendor tells you history "comes across automatically," ask them to show you the endpoint. There isn't one.

3. Moodle keeps grade history — and its own backup tool skips it by default. Every change to every grade in Moodle is written to mdl_grade_grades_history. But course backups honor a site setting called backup_general_histories, and it ships disabled. A naive backup-and-restore migration drops every historical grade event without a single warning. Most shops never notice, because the current grades look fine.

For a school district or a compliance-training operation, that history is the audit trail. Losing it isn't cosmetic.

Here's the actual playbook for the most common case — moving a self-hosted Moodle site to new infrastructure or a new host. We're publishing it because most of it isn't secret; it's just tedious, and tedious is where shortcuts get taken.

1. Baseline the source. Before anything else, capture the numbers you'll verify against later:

   SELECT COUNT(*) FROM mdl_grade_grades;
   SELECT COUNT(*) FROM mdl_grade_grades_history;
   SELECT COUNT(*) FROM mdl_scorm_scoes_track;
   SELECT COUNT(*) FROM mdl_user WHERE deleted = 0;

   Save the output. Both sides sign it.
2. Pick the right method. A full-site clone — database dump plus the moodledata directory — preserves everything, including history and SCORM attempts. Per-course .mbz backups do not, unless backup_general_histories was enabled before the backups were made. Flipping it on afterward doesn't retroactively fix backups you already created. For anything beyond a handful of courses, we clone.
3. Match versions, then upgrade. A database restore must land on the exact same Moodle version it came from — you upgrade after the move, not during. Sites still on 4.1 or 4.4 have been past security EOL since December 8, 2025, so we fold the upgrade into the same project: restore on the matching version, then step up to 4.5 LTS, which is supported into October 2027. We steer institutions away from 5.0 — its end-of-support lands this October, which makes it a strange target for a fresh migration.
4. Dry run and checksum. Run the whole migration into staging. Re-run the baseline queries. Then, for each course, concatenate userid:finalgrade for every graded item, sort, and hash. Same hash on both sides means that gradebook survived byte-for-byte. Different hash means we find out why before you ever see the new site.
5. Chase the mismatches. There are almost always a few: grade items pointing at long-deleted activities, mdl_scorm_scoes_track rows from abandoned attempts, users suspended mid-course years ago. This is the tedious part. It's also the whole job — every mismatch gets a documented explanation or a fix, never a shrug.
6. Cut over. Enable maintenance mode, sync the moodledata delta, take a final dump, restore, repoint DNS, and run the verification pass one last time against the live database. Then unlock.