docs/UPGRADING.mysql

   1 If you did not start by reading the README file, please start there;
   2 these steps do not list the full upgrading process, merely a part which
   3 is sometimes necessary.
   4
   5 This file applies if either:
   6
   7  1) You are upgrading RT from a version prior to 3.8.0, on any version
   8     of MySQL
   9 ............. OR .............
  10  2) You are migrating from MySQL 4.0 to MySQL 4.1 or above
  11
  12 If neither of the above cases apply, your should upgrade as per the
  13 instructions in the README.
  14
  15 These changes are necessary because MySQL 4.1 and greater changed some
  16 aspects of character set handling that may result in RT failures; this
  17 will manifest as multiple login requests, corrupted binary attachments,
  18 and corrupted image custom fields, among others.  In order to resolve
  19 this issue, the upgrade process will need to modify the schema.
  20
  21  1) If you are moving the database and/or upgrading MySQL
  22    1a) Dump the database; with MySQL 4.1 and greater be sure to pass
  23        the mysqldump command the --default-character-set=binary option.
  24        This is necessary because the data was originally encoded in
  25        Latin1.
  26
  27    1b) Configure the new MySQL to use Latin1 as the default character
  28        set everywhere, not UTF-8.  This is necessary so the import in
  29        the next step assumes the data is Latin1.
  30
  31    1c) Import the dump made in step 1a into the new MySQL server, using
  32        the --default-character-set=binary option on restore.  This will
  33        ensure that the data is imported as bytes, which will be
  34        interpreted as Latin1 thanks to step 1b above.
  35
  36    1d) Test that your RT works as expected on this new database.
  37
  38  2) Backup RT's database using --default-character-set=binary
  39     Furthermore, test that you can restore from this backup.
  40
  41  3) Follow instructions in the README file to step 6b.
  42
  43  4) Apply changes described in the README's step 6b, but only up to
  44     version 3.7.87.
  45
  46  5) Apply the RT 3.8 schema upgrades. Included in RT is the script
  47     etc/upgrade/upgrade-mysql-schema.pl that will generate the
  48     appropriate SQL queries:
  49
  50         perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql
  51
  52     If your mysql database is on a remote host, you can run the script
  53     like this instead:
  54
  55         perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
  56
  57  6) Check the sanity of the SQL queries in the queries.sql file
  58     yourself, or consult with your DBA.
  59
  60  7) Apply the queries. Note that this step can take a while; it may also
  61     require additional space on your hard drive comparable with size of
  62     your tables.
  63
  64         mysql -u root -p rt3 < queries.sql
  65
  66     NOTE that 'rt3' is the default name of the RT database, change it in
  67     the command above if your database is named differently.
  68
  69     This step should not produce any errors or warnings. If you see any,
  70     restore your database from the backup you made at step 1, and send a
  71     report to the rt-users@lists.bestpractical.com mailing list.
  72
  73  8) Re-run the `make upgrade-database` command from step 6b of the
  74     README, applying the rest of the upgrades, starting with 3.7.87, and
  75     follow the README's remaining steps.
  76
  77  9) Test everything. The most important parts you have to test:
  78      * binary attachments, like docs, PDFs, and images
  79      * binary custom fields
  80      * everything that may contain characters other than ASCII
  81
  82 10) If you were upgrading from MySQL 4.0, you may now, if you wish,
  83     reconfigure your newer MySQL instance to use UTF-8 as the default
  84     character set, as step 7 above adjusted the character sets on all
  85     existing tables to contain UTF-8 encoded data, rather than Latin1.