rt/docs/UPGRADING.mysql

   1 =pod
   2
   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
   5 necessary.
   6
   7 This file applies if either:
   8
   9 =over
  10
  11 =item 1.
  12
  13 You are upgrading RT from a version prior to 3.8.0, on any version
  14 of MySQL
  15
  16 =item 2.
  17
  18 You are migrating from MySQL 4.0 to MySQL 4.1 or above
  19
  20 =back
  21
  22 If neither of the above cases apply, your should upgrade as per the
  23 instructions in the README.
  24
  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.
  30
  31 =over
  32
  33 =item 1.
  34
  35 If you are moving the database and/or upgrading MySQL
  36
  37 =over
  38
  39 =item 1a.
  40
  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.
  44
  45 =item 1b.
  46
  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
  49 is Latin1.
  50
  51 =item 1c.
  52
  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
  56 1b above.
  57
  58 =item 1d.
  59
  60 Test that your RT works as expected on this new database.
  61
  62 =back
  63
  64 =item 2.
  65
  66 Backup RT's database using --default-character-set=binary  Furthermore, test
  67 that you can restore from this backup.
  68
  69 =item 3.
  70
  71 Follow instructions in the README file to step 6b.
  72
  73 =item 4.
  74
  75 Apply changes described in the README's step 6b, but only up to version
  76 3.7.87.
  77
  78 =item 5.
  79
  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
  82 queries:
  83
  84     perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql
  85
  86 If your mysql database is on a remote host, you can run the script like this
  87 instead:
  88
  89     perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
  90
  91 =item 6.
  92
  93 Check the sanity of the SQL queries in the queries.sql file yourself, or
  94 consult with your DBA.
  95
  96 =item 7.
  97
  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.
 100
 101     mysql -u root -p rt3 < queries.sql
 102
 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.
 105
 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 send a report to the
 108 rt-users@lists.bestpractical.com mailing list.
 109
 110 =item 8.
 111
 112 Re-run the `make upgrade-database` command from step 6b of the README,
 113 applying the rest of the upgrades, starting with 3.7.87, and follow the
 114 README's remaining steps.
 115
 116 =item 9.
 117
 118 Test everything. The most important parts you have to test:
 119
 120 =over
 121
 122 =item *
 123
 124 binary attachments, like docs, PDFs, and images
 125
 126 =item *
 127
 128 binary custom fields
 129
 130 =item *
 131
 132 everything that may contain characters other than ASCII
 133
 134 =back
 135
 136
 137 =item 10.
 138
 139 If you were upgrading from MySQL 4.0, you may now, if you wish, reconfigure
 140 your newer MySQL instance to use UTF-8 as the default character set, as step 7
 141 above adjusted the character sets on all existing tables to contain UTF-8
 142 encoded data, rather than Latin1.
 143
 144 =back