Open edX forum migration from MongoDB to MySQL: what the move involves
If your self-hosted Open edX site still stores forum discussions in MongoDB, you need to move that data to MySQL before you upgrade to a forum release that no longer supports MongoDB. The work is a bounded data migration: discussion threads and replies move from the legacy backend into MySQL using the forum migration commands documented for your target release, followed by testing and a planned cutover. The effort scales with four inputs: how much discussion data you hold, how heavily your site customizes forum behavior, how many environments need the move (production, staging and any sandboxes), and how much downtime your learners can accept during cutover.
Treat effort as a range that narrows once those inputs are known. Ask whoever scopes the work to record the size of the discussion store in each environment, list every forum customization or plugin, and confirm which Open edX release each environment runs today and which release it will run after the forum upgrade. Cost follows from who performs each part: migration engineering, test runs, cutover support, and any fixes to custom forum code. Separate what is one-time (the migration, testing and cutover) from what recurs (keeping the upgraded forum current and backed up). Ask for a written scope with deliverables and an agreed timeline before work starts.
Several details must be confirmed against the official upgrade notes for your target release before you plan anything: the exact migration command names, their prerequisites and their run order, and the release that removed MongoDB support from the forum. Do not rely on memory or on older community posts for these, because the notes for each release are the authority. Also confirm your release target. Open edX states that the latest named release is the only supported release and that it cannot support more than one release at a time, so the upgrade plan should end on that release. Verawood is the current named release, published on 30 July 2026, and the next releases are Willow and Xylon. Confirm which one your upgrade path should reach.
Three decisions shape the plan early. First, decide whether the migration runs as one cutover window or in stages across environments, based on how much learners rely on discussions during that window. Second, decide who performs each step, your team, a partner or a mix, and write the split into the scope. Third, decide how you will prove the result: compare thread and reply counts between the MongoDB source and the MySQL target, spot-check content and permissions, and confirm that learners can read, post and search in a staging copy before production is touched. Keep a tested backup of the MongoDB data and a documented rollback point, because a failed cutover without them leaves the site with no working forum.
What maps cleanly from the MongoDB forum backend to MySQL
This table compares how common forum data in the legacy MongoDB backend lines up with its MySQL counterpart during an Open edX forum migration. Read each row as a checklist: the core discussion records usually map directly, while the final rows need checking against your own data before cutover. The main takeaway is that the migration commands move the core records, but local plugin fields, external attachment links and direct queries from other tools remain your responsibility.
| Source capability (MongoDB) | Target equivalent (MySQL) | Migration notes |
|---|---|---|
| Threads and course or unit context | Relational thread records keyed to course and unit identifiers | Confirm each thread still resolves to a valid course key and unit reference after conversion. |
| Comments and replies | Child records linked to a parent thread or parent comment | Compare reply nesting and ordering on a sample of long threads before accepting the migration. |
| User references tied to LMS accounts | User ID columns matching LMS account identifiers | Check that threads from deleted, merged or renamed accounts still resolve. Decide how orphaned references are handled. |
| Subscriptions and follows | Subscription records keyed to user and thread | Compare subscription counts before and after. Test that notifications still reach the expected learners and staff. |
| Votes and flags | Vote and flag records keyed to user and content | Verify that flag reasons and moderator actions carried over, not only the counts. |
| Pinned and closed states | Status fields on thread records | Confirm pinned and closed states on a sample of threads. A closed thread must remain closed for learners. |
| Attachments or links stored outside the forum | Stored references to external file storage, not database content | The forum commands do not move the files. Confirm that stored links still resolve in the new environment. |
| Custom fields added by local plugins | No automatic target. Requires a column or table you design | Verify: every field added by a local plugin needs a planned destination before the migration runs. |
| Queries or direct database access used by other tools | No direct equivalent. Queries and scripts must be rewritten for MySQL | Verify: reports, scripts or integrations that read MongoDB directly will break and need individual review. |
Documented forum migration commands and the upgrade docs that call them
Each card pairs a forum migration step with the upgrade document that requires it, the configuration that points the forum at MySQL, and the check you run afterward. The exact commands and their order come from the release documentation for your target version, and the Tutor documentation and the edx-platform repository are the places to confirm the current procedure before you schedule any work.
Forum migration management step
The forum migration runs as a documented management step against the discussion data, not as a manual copy of MongoDB collections. Take the exact command, its arguments and its position in the sequence from the release documentation for your target version, and rehearse it on a staging copy first. Ask your engineers to save the full output of every run, including any records the step skipped or could not convert, so you can explain the results to instructors and administrators.
Upgrade notes that require it
The upgrade notes for the named release you are moving to state when the forum migration must run and whether it blocks the upgrade. Open edX supports only its latest named release, so the notes for the version you are targeting govern the order of steps. Read the breaking changes and data migration sections together, and confirm the sequence against the release notes index before you fix a date for the work.
Tutor forum backend setting
Tutor, the official Docker-based distribution, is where you should look first for the setting that selects MySQL as the forum backend in a Tutor deployment. Find the setting or plugin hook in the Tutor documentation for your version, apply it in the configuration that generates your environment, and redeploy in staging before production. Keep the configuration in version control so the setting survives later Tutor upgrades and can be reviewed by your security team.
edx-platform forum configuration
When you run edx-platform outside Tutor, the forum backend is selected through the platform's own configuration. Confirm the setting names in the repository for your release, and check the database versions the development requirements list, including MySQL 8.0 and MongoDB 7.x, against what your target release expects. Keep the MongoDB source reachable and unchanged until verification passes, because the export depends on it.
Backup and rollback point
Take a verified backup of the MongoDB discussion data and of the MySQL target before any run, and record the point you would return to if the migration fails. During staging rehearsal, test whether the step can be repeated safely against partially migrated data, and confirm that answer with the release documentation. Decide who owns the go or no-go decision and how forum posts written during the cutover window will be handled.
Post-migration verification checks
Verify the migration by comparing thread, comment and author-linked records between MongoDB and MySQL, using counts recorded from the source before the run. Then open a sample of course discussions as a learner, an instructor and a staff user. Confirm that posts display with their authors, timestamps and course scope, and that moderation actions such as flagging and editing still work.
How a forum migration runs from inventory to decommissioning the old backend
The migration moves forum discussions from MongoDB to MySQL in eight stages, with a rehearsal, a timed dry run and a parallel comparison before anyone freezes posting. Each stage closes with a record your team can check. The duration of each step comes from your own dry run.
Inventory forum data and customizations
Your team and DeployOpen list the forum data in scope: thread and comment counts per course and organization, subscriptions, attachment references and the forum settings in the LMS. Record every custom forum change, such as altered templates, plugins or patched code, and decide for each one whether to keep, port or retire it. Confirm the volume figures with counts taken from the live MongoDB database. The output is a signed inventory that sets the scope for every later step.
Rehearse the migration on a staging copy
Restore a recent copy of the production MongoDB forum data and the LMS database into a staging environment. Run the documented forum migration commands for your target release against that copy, and log every error with the thread or record it affected. Group the failures by cause, fix the cause, and repeat the rehearsal until the remaining exceptions are understood. The output is a rehearsal log with error categories and the fixes applied, plus confirmation of the release notes for the version you will run.
Time a full dry run
Run the complete migration sequence on a copy sized like production and on infrastructure matching the production setup. Record elapsed time for each command and each phase, along with the checkpoints where a failure would stop the run. The durations you measure here are the only basis for sizing the posting freeze, so do not borrow times from another installation. The output is a timed runbook with named checkpoints and a go or no-go estimate for the cutover window.
Compare the MySQL backend with MongoDB in parallel
Stand up the MySQL-backed forum in a non-production environment fed by the migrated data, and keep the MongoDB backend running for comparison. For a sample of threads across courses, compare post identifiers, authors, timestamps, reply counts, edit history and body content in both backends. Investigate every difference and document each accepted exception. The output is a comparison report with no unexplained differences, and each known behavior difference confirmed against the release documentation.
Make the rollback decision before cutover
Write the go and no-go criteria before the window opens. Include the maximum acceptable failures from the dry run, the comparison results, a verified MongoDB backup, a tested restore procedure and the named owner who can call the rollback. Decide before posting is frozen, because the rollback path changes once production writes start on MySQL. The output is a signed decision record that states the rollback path: keep the LMS on MongoDB and restore from the pre-cutover backup if needed.
Freeze posting and cut over
Announce the window to learners and course teams, then disable posting in the forum. Take a final backup of the MongoDB data, run the migration commands against production, and switch the LMS to the MySQL backend. Reopen posting only after the operator confirms each checkpoint from the timed runbook. The output is a cutover log with timestamps for every checkpoint and a named operator who recorded the outcome of each one.
Verify counts and sample threads after cutover
Compare thread and comment counts per course with the pre-cutover inventory. Open a sample of threads across courses, including threads with attachments, edits and moderation history, and confirm that search, notifications and moderation tools work. Keep the MongoDB data read-only until this verification passes. The output is a signed verification record that the course teams and platform owner accept, and that authorizes the next stage.
Decommission MongoDB after the retention period
Keep the MongoDB data and its backups for a retention period that your organization sets with its records and data governance owners. When that period ends, remove the MongoDB service, revoke its access, delete backups according to policy, and update configuration files and runbooks. The output is a decommissioning record listing what was removed, when, and who approved it. Any legal or regulatory retention duty comes from your own policies, not from this page.
What drives the effort of an Open edX forum migration
This table lists the factors that change the labor and calendar for moving Open edX discussion data from MongoDB to MySQL, with the effect of each and what to request in a written quote. Read it before comparing quotes, because two forums of similar size can need very different effort depending on how many instances, reports and rehearsals are in scope. The main takeaway is that labor for analysis, rehearsal, testing and cutover drives most of the cost, while MySQL hosting and backups are the recurring costs to plan for.
| Driver | Effect on cost or duration | What to ask for in a quote |
|---|---|---|
| Total discussion volume | More threads, replies and attachments lengthen export, import, validation and each rehearsal run. | Thread, reply and attachment counts per deployment from a current export, and the run time assumed for each rehearsal. |
| Courses and deployments (production, staging, sandbox) | Each instance needs its own analysis, migration run and cutover checks, so effort scales with the count. | Effort shown per environment, and whether sandbox instances are migrated or rebuilt from production data. |
| Data quality of existing threads | Orphaned threads, deleted posts, unusual characters or broken course references add cleanup and exception handling. | A pre-migration data scan, the cleanup rules proposed, and who approves records that cannot be converted. |
| Custom forum code or plugins | Forks, custom discussion fields or theme code that reads MongoDB collections must be rewritten and tested against MySQL. | An inventory of custom code, a test plan for each item, and whether changes are in fixed scope or billed separately. |
| Integrations or reports that read MongoDB directly | Dashboards, scripts or warehouse jobs that query collections need new queries and their own testing. | A list of every consumer of forum data, the owner of each, and the change each one needs. |
| Target release and coupling with an upgrade | Pairing the forum move with a named release upgrade adds upgrade testing and shares the freeze window. | Confirmation of the target release, whether the quote covers the forum move alone, and how upgrade testing is scoped. |
| Hosting and backups for both databases | MongoDB must stay recoverable until cutover is accepted, and MySQL adds recurring hosting and backup cost. | The MongoDB retention period during the parallel run, MySQL backup and restore tests, and who pays for each hosting line. |
| Number of rehearsals in the parallel run | Each rehearsal repeats export, import and comparison, so the count is a direct multiplier on labor. | The number of rehearsals included in fixed scope, and the acceptance criteria that close each one. |
| Length of the freeze window | A shorter accepted freeze window usually needs more rehearsal and more automated checks before cutover. | The freeze window the business accepts, the timing of cutover, and the rollback plan if cutover overruns. |
What goes wrong in forum migrations and how to prevent it
Forum migrations usually fail in the gaps between the copy, the accounts, the reports and the rollback path. Each risk below is tied to a check you can run before cutover, so the team can confirm the data, the timing and the fallback before the MongoDB source is retired.
Posts missing after the copy
Discussion threads contain posts, replies and nested comments, and a copy can complete without moving every level. Before cutover, compare post and comment counts per course between MongoDB and MySQL, including replies and posts that learners or moderators flagged or deleted. Write down how each deleted or hidden state is handled so that a missing post is a decision, not a surprise.
User references that do not resolve
Forum records point to learners by identifier. If accounts were merged, renamed, re-created or deleted after the export was taken, authors can appear as unknown users or as the wrong learner. Before cutover, join every migrated author reference against the LMS user table, list the orphans, and agree on a mapping for each group of unmatched records.
Dry run never timed
A dry run proves the commands work, but it does not prove the cutover window is long enough unless it is timed. Run the full sequence on a copy of production-sized data, record how long each stage takes, and compare the total with the maintenance window the platform owners agreed to. Keep the timings in the runbook so the team can see which stage will grow as the course count grows.
Reporting still queries MongoDB
Dashboards, scheduled exports and analytics jobs that read forum collections will fail or go stale after the backend changes, and they often sit outside the LMS team's view. Inventory every consumer of forum data, including ad hoc scripts, repoint each one to the MySQL schema, and run each report against the dry-run target. Confirm the results match the source before cutover.
Backups without a tested restore
A backup that has never been restored is an assumption. Before the migration starts, take backups of both the MongoDB source and the MySQL target, restore them to a separate host, and check that the forum loads and that post and user counts match the originals. Write the restore steps and their duration into the runbook, because the team will need them if cutover has to be reversed.
Forum upgrade before verification
Forum releases that dropped MongoDB require the data to be in MySQL before the upgrade runs, so upgrading early can leave no working copy of the discussions. Make verification a written sign-off gate: the counts, author mapping and reports must pass before the forum release is installed. Keep the MongoDB source readable until that sign-off, and confirm with the documented upgrade notes for your release which steps cannot be reversed.
Open edX forum migration questions buyers ask before hiring help
How much does an Open edX forum migration cost to hire out?
No price is stated here, and a quote follows a written scope. The main cost drivers are the size and shape of your discussion data, how many environments need a rehearsal before production, and how much validation your course teams expect. Most of the cost is one-time effort for planning, staging dry runs, the production cutover and verification. Recurring cost appears only if you add a support retainer afterward. Ask any provider for an itemized scope covering discovery, staging rehearsals, production steps, rollback, validation, documentation and handover, along with the assumptions behind each line, such as data volume and the number of course runs in scope. Ask who performs each task, what you must supply, and what changes if the data is messier than expected. Compare quotes only when they cover the same written scope.
How long does an Open edX forum migration take to complete?
No duration is published here, and the timeline comes from the written scope. Duration depends on how much discussion data exists, how many environments must be rehearsed, how many validation rounds your testers need, and how long change approvals and maintenance windows take to schedule. Planning and staging rehearsals usually consume the most calendar time, because each dry run surfaces issues that must be fixed before the next one. The production cutover is normally a scheduled window, but only if the rehearsals were clean. If you combine the migration with a platform upgrade, the sequence adds effort and dependencies. Ask for a plan with named phases, the number of rehearsal cycles assumed, the dates each phase depends on from your side, and what triggers an extra cycle. Confirm your target release and maintenance windows early, since they often set the schedule.
What access and people does a forum migration need from our team?
Expect to supply staging and production access, including network paths and credentials for the MongoDB and MySQL backends and the LMS hosts. Data owners must decide retention rules, how deleted or flagged posts are handled, and how learner identities should map between systems. You need a change window with formal approval, a backup owner who can confirm restore points, and someone authorized to call a rollback. Course teams should name testers who can check threads, replies and search results in staging, since platform engineers cannot judge whether a discussion looks correct to instructors and learners. Also confirm who receives alerts during the cutover and who signs off on completion. Write these responsibilities into the scope so that delays on your side are visible in the plan rather than discovered during the window.
Can our own Open edX team handle the forum migration alone?
Yes, a team with Open edX operations experience can run the migration alone if it works from the documented forum migration commands, rehearses on a copy of production, and has verification steps and a tested rollback. The questions to answer honestly are whether the team has run data migrations on Open edX before, whether it can keep the platform stable during the window, and who owns validation of learner-facing results. A partner adds capacity, an independent reviewer and written documentation and handover, which matters when the team is small or already committed to an upgrade. Assess your team against the written steps, identify the gaps, and decide which gaps to fill internally and which to scope externally. Any engagement with DeployOpen would be defined in a written scope before work starts.
Do we need a forum migration before an Open edX upgrade?
Yes, if your forum still stores data in MongoDB and the release you are moving to no longer supports that backend. This migration is a required step before upgrading to forum v2 releases that dropped MongoDB. Open edX states that the latest named release is the only supported release, and Verawood is the current named release, published on 30 July 2026. Willow and Xylon are listed for December 2026 and June 2027. Confirm which release and forum version your target needs, because the order of work depends on it. Plan the migration against the release you will actually run, check the upgrade notes for any required sequence, and avoid running the forum migration on a platform version that will be replaced before cutover.
What usually goes wrong in a forum migration and how do we catch it?
Common failures include threads or replies attached to course or unit identifiers that no longer resolve, user references that fail to match after the move, lost timestamps or subscription records, attachments that do not carry over, and moderation state that changes without notice. Catch these with record counts per course before and after the move, sampled threads checked by named testers in staging, and search results compared against the source. Keep a read-only copy of the MongoDB data until sign-off, and rehearse the rollback before the production window rather than assuming it will work. Ask the documentation or your provider which fields the commands transform and which they leave untouched, so your validation checks cover what actually changes.
Does a forum migration move learner data along with courses?
Forum data is discussion content, and it is handled separately from course content. Forum records link users, courses and posts, so the mapping between user identities on the old and new platforms matters for every thread. Course export and import do not carry learner data, so plan forum migration as its own workstream with its own checks. Confirm which learner records reference posts, how your identity provider maps accounts into the new environment, and how personal data in posts is retained or removed. Your privacy and legal owners should approve those decisions before the rehearsal, because changing the mapping after cutover is harder to reverse.
How DeployOpen scopes and runs an Open edX forum migration
DeployOpen treats the forum move as a scoped piece of work inside your own Open edX environment, starting from your current MongoDB-backed discussion data and ending with a MySQL-backed forum that your team operates. Engagements are fixed-scope, so the written scope sets what is migrated, tested and handed over before any work begins.
How we scope
- Inventory your current Open edX release, forum version and MongoDB deployment before agreeing the upgrade target.
- Confirm which discussion data, courses and environments the written scope covers, including staging and production copies.
- Agree the rollback point, maintenance window and sign-off owners in writing before any migration command runs.
How we build
- Stand up a staging copy with MySQL and MongoDB reachable, configured as closely as possible to production.
- Run the documented forum migration commands against staging and record counts and errors at each stage.
- Test threads, replies and course-level discussion access in the LMS after the migration completes.
How we hand over
- Deliver a runbook with the exact command sequence, prerequisites, expected output and checks at each step.
- Document before-and-after data comparisons as verification evidence for your change records and internal review.
- Walk your operations team through cutover, the rollback procedure and retirement of the MongoDB forum backend.
How we support
- Plan the migration against the release you will run afterward, since Open edX supports only its latest named release.
- Confirm with the Open edX project which forum and MySQL versions your target release supports before scoping starts.
- Keep MongoDB backups until your rollback window closes and data owners approve removing the legacy backend. Ongoing support is available as a retainer.
