Migrate databases between tutor platforms

tech_mil · July 16, 2025, 5:46pm

Hello

I am trying to migrate databases from one openedx platform to another. It sucessfully updated everything in mysql and mongodb. After refreshing the page and I was able to access the courses etc. But when I tried to restart the containers, it would crash and not load. I’ll put my process below but I currently do not have access to the servers so can’t provide the debug logs right now.

My process:
Get MySQL dump

tutor local exec \
    -e USERNAME="$(tutor config printvalue MYSQL_ROOT_USERNAME)" \
    -e PASSWORD="$(tutor config printvalue MYSQL_ROOT_PASSWORD)" \
    mysql sh -c 'mysqldump --all-databases --user=$USERNAME --password=$PASSWORD > /var/lib/mysql/dump.sql'

Run the following command on the second instance

docker compose -f /home/jan/.local/share/tutor/env/local/docker-compose.yml \
-f /home/jan/.local/share/tutor/env/local/docker-compose.prod.yml \
--project-name tutor_local   exec -i -T mysql   sh -c 'mysql --user=root \
--password=pass< /dev/stdin'   < dump.sql

Get MongoDB dump from first instance

tutor local exec mongodb mongodump --out=/data/db/dump.mongodb

Then copy the Mongo dump into mongodb container on second instance and run:

mongorestore --drop /tmp/dump.mongodb/

I believe the first instance is v18 tutor and the second one is v19 if that makes a difference.

If anyone has some experience with this I would appreicate it.

joel.edwards · July 17, 2025, 6:30am

Part of the process of upgrading often involves changes to the databases.

You should either restore your v18 database on a new v18 instance of the same subversion, or you can upgrade your existing instance to the new version prior to migrating it to the new instance.

You should always upgrade incrementally to ensure all updates and migrations happen in the expected order, eg if you are on 18.0.0 now, then you should upgrade 18.1.{0,1,2,3,4} → 18.2.{0,1,2} → 19.0.{0,1,2,3,4,5} and finally the latest v20.0.0, so that’s 15 versions to upgrade if you’re coming from v18.0.0 and go to latest/current supported version.

I recommend always creating a backup of your system before each upgrade in case of anything breaking along the way

Always carefully review the changelogs for information about any breaking changes you need to be aware of

tech_mil · July 17, 2025, 10:31am

Hi

Thanks for the reply. I investigated a bit further today and the issue seems to be that the second instance inhertited the MySQL password from the first instance when the sql dump was migrated. Now I am just looking into how to change the password back.

Let me know if there is a procedure for this.

I have tried running tutor local launch and tutor images build openedx but it did not help.

joel.edwards · July 17, 2025, 11:08am

as far as I’m aware, it should not have inherited the old password on the new server. The password is created when you set up your instance:

sources:

github.com/overhangio/tutor

tutor/templates/config/base.yml

release


      
          ---
          CMS_OAUTH2_SECRET: "{{ 24|random_string }}"
          ID: "{{ 24|random_string }}"
          JWT_RSA_PRIVATE_KEY: "{{ 2048|rsa_private_key }}"
          MEILISEARCH_MASTER_KEY: "{{ 24|random_string }}"
          MEILISEARCH_API_KEY_UID: "{{ 4|uuid }}"
          MEILISEARCH_API_KEY: "{{ MEILISEARCH_MASTER_KEY|uid_master_hash(MEILISEARCH_API_KEY_UID) }}"
          MYSQL_ROOT_PASSWORD: "{{ 8|random_string }}"
          OPENEDX_MYSQL_PASSWORD: "{{ 8|random_string }}"
          OPENEDX_SECRET_KEY: "{{ 24|random_string }}"
          PLUGINS:
            # enabled by default
            - mfe
            - indigo
          PLUGIN_INDEXES:
            # Indexes in this list will be suffixed with the Open edX named version and
            # "plugins.yml". E.g: https://overhang.io/tutor/main/sumac/plugins.yml
            - https://overhang.io/tutor/main

tech_mil · July 17, 2025, 11:58am

So all my passwords look fine, in the config and in the output for tutor local launch. However when I run that command, I get this:

Initialising MySQL...
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 1045 (28000): Access denied for user 'root'@'172.19.0.11' (using password: YES)
    [1/10] Waiting for MySQL service (this may take a while)...
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 1045 (28000): Access denied for user 'root'@'172.19.0.11' (using password: YES)
    [2/10] Waiting for MySQL service (this may take a while)...
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 1045 (28000): Access denied for user 'root'@'172.19.0.11' (using password: YES)
    [3/10] Waiting for MySQL service (this may take a while)...
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 1045 (28000): Access denied for user 'root'@'172.19.0.11' (using password: YES)
    [4/10] Waiting for MySQL service (this may take a while)...
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 1045 (28000): Access denied for user 'root'@'172.19.0.11' (using password: YES)
    [5/10] Waiting for MySQL service (this may take a while)...
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR 1045 (28000): Access denied for user 'root'@'172.19.0.11' (using password: YES)
    [6/10] Waiting for MySQL service (this may take a while)...

I have tried stopping and removing the mysql container but this keeps repeating.

tech_mil · July 17, 2025, 12:45pm

Got it working! I was changing only ‘root’@‘localhost’ password when I should have changed ‘root’@‘%’ too. It is strange that I have to change the passwords back but it is working eitherway! After that I also had an issue with Meilisearch erroring on launch. Fixed this by removing the data.ms folder from the tutor config to let it regenerate.

joel.edwards · July 17, 2025, 1:34pm

glad to hear you got it working for what it’s worth regarding Meilisearch, it’s never considered a ‘source of truth’ in Tutor so always safe to trash Meilisearch and regenerate it (source)

KFC_kenneth · July 18, 2025, 5:00am

Hi @tech_mil & @joel.edwards,

Our organization planning on upgrade from 17.0.2 to 18.2.2 using tutor k8s and PaaS CosmoDB & data-center MariaDB, there are 13 version involve to upgrade. Does it mean I need to do upgrade 13 times? Or I can upgrade just once to 18.2.2? Thank you for your reply. Btw, the tutor command for DB migrate start from tutor v18

Does anyone know the discussion threads related to Topic: security risk assessment or security audit

Many thanks,
Kenneth

joel.edwards · July 18, 2025, 10:20am

Hi @KFC_kenneth, yes that’s correct, you should preferably step iteratively through each subversion until you’ve reached your target version. you can see a list of all the versions on PyPi here: tutor · PyPI

so for you coming from 17.0.2 you’ll next go to 17.0.3 then 17.0.4 etc etc…
I haven’t done k8s myself yet, but on local I’d do it like this (my understanding is that the process should be the same though)

pip install tutor==17.0.3
tutor {local|dev|k8s} launch
pip install tutor==17.0.4
tutor {local|dev|k8s} launch
pip install tutor==17.0.5
tutor {local|dev|k8s} launch
pip install tutor==17.0.6
tutor {local|dev|k8s} launch
pip install tutor==18.0.0
tutor {local|dev|k8s} launch
pip install tutor==18.1.0
tutor {local|dev|k8s} launch
pip install tutor==18.1.1
tutor {local|dev|k8s} launch

…etc until you’re done…

pay close attention to any issues/errors that come up along the way, and at the very minimum perform a complete backup of your installation before you upgrade, and (recommended) after each successful upgrade, just in case you have to revert on a failure (not very common but better safe than sorry!)

note that the latest version is v20, so you may have limited community support on older releases going forward…

Fox_Piacenti · September 8, 2025, 7:11pm

This happened because you dumped all the databases in your original dump command, and that includes the core mysql database, which contains information such as user accounts for MySQL itself.

Topic		Replies	Views
Migrating from Open edX native Tutor Help tutor	2	533	January 20, 2023
Moving tutor based Open edX Maple from server 1 to server 2 Mysql Errors Tutor Help	8	411	October 5, 2022
Migrating Tutor to another server Tutor Help	2	796	January 28, 2023
About Making database dumps Tutor Help	3	497	March 3, 2024
MongoDB Error when upgrading from tutor 17 to 18 Tutor Help tutor , quince , redwood	13	477	September 18, 2024

Migrate databases between tutor platforms

Related topics