diff options
Diffstat (limited to 'rt/docs/UPGRADING.mysql')
-rw-r--r-- | rt/docs/UPGRADING.mysql | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/rt/docs/UPGRADING.mysql b/rt/docs/UPGRADING.mysql new file mode 100644 index 000000000..77a6b389f --- /dev/null +++ b/rt/docs/UPGRADING.mysql @@ -0,0 +1,85 @@ +If you did not start by reading the README file, please start there; +these steps do not list the full upgrading process, merely a part which +is sometimes necessary. + +This file applies if either: + + 1) You are upgrading RT from a version prior to 3.8.0, on any version + of MySQL +............. OR ............. + 2) You are migrating from MySQL 4.0 to MySQL 4.1 or above + +If neither of the above cases apply, your should upgrade as per the +instructions in the README. + +These changes are necessary because MySQL 4.1 and greater changed some +aspects of character set handling that may result in RT failures; this +will manifest as multiple login requests, corrupted binary attachments, +and corrupted image custom fields, among others. In order to resolve +this issue, the upgrade process will need to modify the schema. + + 1) If you are moving the database and/or upgrading MySQL + 1a) Dump the database; with MySQL 4.1 and greater be sure to pass + the mysqldump command the --default-character-set=binary option. + This is necessary because the data was originally encoded in + Latin1. + + 1b) Configure the new MySQL to use Latin1 as the default character + set everywhere, not UTF-8. This is necessary so the import in + the next step assumes the data is Latin1. + + 1c) Import the dump made in step 1a into the new MySQL server, using + the --default-character-set=binary option on restore. This will + ensure that the data is imported as bytes, which will be + interpreted as Latin1 thanks to step 1b above. + + 1d) Test that your RT works as expected on this new database. + + 2) Backup RT's database using --default-character-set=binary + Furthermore, test that you can restore from this backup. + + 3) Follow instructions in the README file to step 6b. + + 4) Apply changes described in the README's step 6b, but only up to + version 3.7.87. + + 5) Apply the RT 3.8 schema upgrades. Included in RT is the script + etc/upgrade/upgrade-mysql-schema.pl that will generate the + appropriate SQL queries: + + perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql + + If your mysql database is on a remote host, you can run the script + like this instead: + + perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql + + 6) Check the sanity of the SQL queries in the queries.sql file + yourself, or consult with your DBA. + + 7) Apply the queries. Note that this step can take a while; it may also + require additional space on your hard drive comparable with size of + your tables. + + mysql -u root -p rt3 < queries.sql + + NOTE that 'rt3' is the default name of the RT database, change it in + the command above if your database is named differently. + + This step should not produce any errors or warnings. If you see any, + restore your database from the backup you made at step 1, and send a + report to the rt-users@lists.bestpractical.com mailing list. + + 8) Re-run the `make upgrade-database` command from step 6b of the + README, applying the rest of the upgrades, starting with 3.7.87, and + follow the README's remaining steps. + + 9) Test everything. The most important parts you have to test: + * binary attachments, like docs, PDFs, and images + * binary custom fields + * everything that may contain characters other than ASCII + +10) If you were upgrading from MySQL 4.0, you may now, if you wish, + reconfigure your newer MySQL instance to use UTF-8 as the default + character set, as step 7 above adjusted the character sets on all + existing tables to contain UTF-8 encoded data, rather than Latin1. |