X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=rt%2Fdocs%2FUPGRADING.mysql;fp=rt%2Fdocs%2FUPGRADING.mysql;h=a62dee78b8f4d9c2bc1a3d4bc19cdea14263e023;hp=77a6b389f2a50c049c66545986a8f794cf76e44f;hb=84f2df8931fa02e63fb21f8f0bb87dd9577b8919;hpb=d7678b9b97068dcd352f0ea101c6c8d02ae330d6 diff --git a/rt/docs/UPGRADING.mysql b/rt/docs/UPGRADING.mysql index 77a6b389f..a62dee78b 100644 --- a/rt/docs/UPGRADING.mysql +++ b/rt/docs/UPGRADING.mysql @@ -1,85 +1,142 @@ -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. +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 +=over + +=item 1. + +You are upgrading RT from a version prior to 3.8.0, on any version +of MySQL + +=item 2. + +You are migrating from MySQL 4.0 to MySQL 4.1 or above + +=back 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. +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. + +=over + +=item 1. + +If you are moving the database and/or upgrading MySQL + +=over + +=item 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. + +=item 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. + +=item 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. + +=item 1d. + +Test that your RT works as expected on this new database. + +=back + +=item 2. + +Backup RT's database using --default-character-set=binary Furthermore, test +that you can restore from this backup. + +=item 3. + +Follow instructions in the README file to step 6b. + +=item 4. + +Apply changes described in the README's step 6b, but only up to version +3.7.87. + +=item 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 + +=item 6. + +Check the sanity of the SQL queries in the queries.sql file yourself, or +consult with your DBA. + +=item 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. - 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. + mysql -u root -p rt3 < queries.sql - 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. +NOTE that 'rt3' is the default name of the RT database, change it in the +command above if your database is named differently. - 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. +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. - 1d) Test that your RT works as expected on this new database. +=item 8. - 2) Backup RT's database using --default-character-set=binary - Furthermore, test that you can restore from this backup. +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. - 3) Follow instructions in the README file to step 6b. +=item 9. - 4) Apply changes described in the README's step 6b, but only up to - version 3.7.87. +Test everything. The most important parts you have to test: - 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: +=over - perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql +=item * - If your mysql database is on a remote host, you can run the script - like this instead: +binary attachments, like docs, PDFs, and images - perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql +=item * - 6) Check the sanity of the SQL queries in the queries.sql file - yourself, or consult with your DBA. +binary custom fields - 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. +=item * - mysql -u root -p rt3 < queries.sql +everything that may contain characters other than ASCII - NOTE that 'rt3' is the default name of the RT database, change it in - the command above if your database is named differently. +=back - 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. +=item 10. - 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 +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. -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. +=back