3 If you did not start by reading the F<README> file, please start there; these
4 steps do not list the full upgrading process, merely a part which is sometimes
7 This file applies if either:
13 You are upgrading RT from a version prior to 3.8.0, on any version
18 You are migrating from MySQL 4.0 to MySQL 4.1 or above
22 If neither of the above cases apply, your should upgrade as per the
23 instructions in the README.
25 These changes are necessary because MySQL 4.1 and greater changed some aspects
26 of character set handling that may result in RT failures; this will manifest
27 as multiple login requests, corrupted binary attachments, and corrupted image
28 custom fields, among others. In order to resolve this issue, the upgrade
29 process will need to modify the schema.
35 If you are moving the database and/or upgrading MySQL
41 Dump the database; with MySQL 4.1 and greater be sure to pass the mysqldump
42 command the --default-character-set=binary option. This is necessary because
43 the data was originally encoded in Latin1.
47 Configure the new MySQL to use Latin1 as the default character set everywhere,
48 not UTF-8. This is necessary so the import in the next step assumes the data
53 Import the dump made in step 1a into the new MySQL server, using the
54 --default-character-set=binary option on restore. This will ensure that the
55 data is imported as bytes, which will be interpreted as Latin1 thanks to step
60 Test that your RT works as expected on this new database.
66 Backup RT's database using --default-character-set=binary Furthermore, test
67 that you can restore from this backup.
71 Follow instructions in the README file to step 6b.
75 Apply changes described in the README's step 6b, but only up to version
80 Apply the RT 3.8 schema upgrades. Included in RT is the script
81 etc/upgrade/upgrade-mysql-schema.pl that will generate the appropriate SQL
84 perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql
86 If your mysql database is on a remote host, you can run the script like this
89 perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
93 Check the sanity of the SQL queries in the queries.sql file yourself, or
94 consult with your DBA.
98 Apply the queries. Note that this step can take a while; it may also require
99 additional space on your hard drive comparable with size of your tables.
101 mysql -u root -p rt3 < queries.sql
103 NOTE that 'rt3' is the default name of the RT database, change it in the
104 command above if your database is named differently.
106 This step should not produce any errors or warnings. If you see any, restore
107 your database from the backup you made at step 1 and examine the errors to
108 determine the cause. Consult your DBA for MySQL-specific issues. For RT
109 issues, you can post to the community forum at L<https://forum.bestpractical.com>
110 for help or send email to sales@bestpractical.com for professional assistance.
114 Re-run the `make upgrade-database` command from step 6b of the README,
115 applying the rest of the upgrades, starting with 3.7.87, and follow the
116 README's remaining steps.
120 Test everything. The most important parts you have to test:
126 binary attachments, like docs, PDFs, and images
134 everything that may contain characters other than ASCII
141 If you were upgrading from MySQL 4.0, you may now, if you wish, reconfigure
142 your newer MySQL instance to use UTF-8 as the default character set, as step 7
143 above adjusted the character sets on all existing tables to contain UTF-8
144 encoded data, rather than Latin1.