OED Upgrades Through OED v1.0.0

If you are migrating though v1.0.0 then special steps are needed. This is due to the need for a major database upgrade. You are doing this type of migration if the current version is below v1.0.0 but the new version is v1.0.0 or above. This is a onetime process so it is not needed if you are upgrading starting with a version at or beyond v1.0.0.

Introduction

The following steps are meant to migrate OED's Postgres version across multiple major versions, specifically from 10.13 to 15.3 when going to OED v1.0.0, with the help of two scripts to automate as much of the process as possible. Before starting, make sure OED and its Docker containers are running. As with other migration work, be sure to be working in the main OED directory.

Since this is a unique step and some sites may have difficulties, you are welcome to reach out to the OED project to get help in doing this or address any concerns you may have.

Getting the scripts

You need two scripts from OED v1.0.0 to perform this migration. Unfortunately, they are used before the software is updated. Use the links for each file to go to the GitHub repository. Place each file in the OED main directory by doing one of the following (in likely order of what is easiest to hardest to do):

1. Use the "download raw file" button to get the file. You will likely need to then move file from wherever your web browser downloads files to the main OED directory.
2. Use the "copy raw file" button to get the file. In the terminal/shell in the main OED directory do the following:
   1. cat > restoreDatabase.sh
   2. Paste the file contents copied from GitHub in the previous step.
   3. Enter control-d meaning control and d keys at the same time. This will end the input of the file contents.
3. As a last resort, you can create a new directory and clone OED v1.0 into that directory. You should then be able to copy the files from src/server/migrations/scripts/ into the main directory of OED you are upgrading. You will not need this clone after this so you can delete this clone.

The links for the two files are:

• dumpDatabase.sh
• restoreDatabase.sh

Running the first script

The first script is called dumpDatabase.sh and it should be in the main OED directory after the steps above. Run the script in the main OED directory by running the command:
bash dumpDatabase.sh

The script will then run the first steps of the database migration, eventually prompting the user to reset the passwords for the database users oed and postgres. It will display the passwords that it should be reset to based on the environment variables, and the user must enter it in twice and make sure that no error messages occur. It is okay to copy the password shown and paste it into the requested password. Afterwards, the script will create a database dump file called script_database_dump.sql in the main OED directory where the script was run from.

Shutting down OED

The first script requires OED to be running but the second script requires OED to be shut down. Please shut down OED before running the next script. See the step in the admin upgrading page for details on doing this.

Running the second script

The second script is called restoreDatabase.sh and it should be in the main OED directory after the steps above. Run the script in the main OED directory by running the command:
bash restoreDatabase.sh

The second script will remove the postgres version 10.13 database container and bring up a container with postgres version 15.3. It will restore the dump to the new database container and bring it back down again, leaving OED in a shut down state. This can take a couple of minutes. After script finishes running successfully, the database migration is complete. If you are asked about descending and/or removing a write protected directory (postgres-data) then you should answer 'y' (without the quotes).

Removing files

This process created three files that are no longer needed. To keep your software directory clean and to save space, it is best to remove them before continuing with a standard upgrade. Do the following in a terminal/shell in the main OED directory:
rm dumpDatabase.sh restoreDatabase.sh script_database_dump.sql
Note that not doing this could cause a git merge issue when you do the rest of the upgrade.

Continuing upgrade

At this point you can continue the standard upgrade process from the next step.