NAME

upgrade-database-to-utf8mb4.pl -- Upgrade webwork course database tables from latin1 to utf8mb4.

SYNOPSIS

upgrade-database-to-utf8mb4.pl [options]

Options:
  -c|--course-id [course]   Course id to upgrade the database for.
                            (This option may be given multiple times.)
  -a|--all                  Upgrade the database for all existing courses
                            including the admin course.
                            (Preempts the previous option.)
  -2|--run-second-pass      Run a second pass to change column text types to
                            be the defaults for webwork.  This pass is not run
                            by default.
  -n|--upgrade-non-native   Upgrade the non-native tables
                            (locations, location_addresses, depths)
  --no-backup               Do not backup the database before making changes
                            to the database. (Not recommended)
  -b|--backup-file [file]   Filename for the database backup file.
                            Default: ./webwork.sql
  -v|--verbose              Show progress output.
  -h|--help                 Show full help for this script.

DESCRIPTION

Upgrade webwork course database tables from latin1 to utf8mb4.

This script assumes that you have already properly configured the database to work with the utf8mb4 character set. See https://webwork.maa.org/wiki/Converting_the_webwork_database_from_the_latin1_to_the_utf8mb4_character_set#Check_what_the_default_character_set_is_for_MySQL_on_your_new_or_upgraded_server.

Also, make sure to upgrade the course via webwork2/admin "Upgrade Courses" before running this script for the course.

If you are upgrading a WeBWorK installation from a version prior to version 2.15 use

upgrade-database-to-utf8mb4.pl -na

If you are upgrading a single course that was created with a version of WeBWorK prior to version 2.15, use

upgrade-database-to-utf8mb4.pl -c courseId

If there are errors when running this script, then restore the database using the backup created by the script (unless you used --no-backup) by running

mysql -u webworkWrite -p webwork < webwork.sql

This is where webworkWrite is the $database_username set in site.conf. You may need to change webwork.sql if you used a different name for the database backup file. You will be prompted to enter the password, which should be the value of $database_password in site.conf.

OPTIONS

-c|--course-id [course]

Course id or list of course ids to upgrade the database tables for. Use this option multiple times to upgrade the database tables for multiple courses at one time.

-a|--all

Ignore the previous option and upgrade the database tables for all existing courses, including the admin course.

-2|--run-second-pass

On the first pass this script will change the datatypes of all columns that are different from the datatype defined in the webwork database schema to that in the schema. Then it will convert the table to use the utf8mb4 charset. When this conversion is done the database automatically enlarges text datatypes. If this option is enabled then the second pass will change those back to the smaller text datatypes as defined in the webwork database schema.

This second pass is not strictly neccessary. The larger text datatypes should still work with WeBWorK.

This pass is not run by default. Note that running this script again will also perform this second pass, if desired.

--no-backup

Do not dump the entire webwork database to a backup sql file before performing changes. It is recommended that you make a backup before any of the other changes that this script makes. If you have already created a database backup, then you can use this option to prevent the creation of another backup file.

-b|--backup-file [filename]

Filename for the database backup file. By default the database is dumped to the file ./webwork.sql in the directory the script is run from.

-v|--verbose

Make this script show output for the things that it is doing.