rt/UPGRADING.mysql

   1 MySQL 4.1 and greater implemented changes in character set handling
   2 that may result in RT failures: multiple login requests, binary attachments
   3 breakage, image custom fields breakage and more.
   4
   5 In order to resolve this issue we've changed our schema for MySQL 4.1 and
   6 greater versions.
   7
   8 If you're installing a new RT then you can skip this file.
   9
  10 If you're migrating from MySQL 4.0 to MySQL 4.1 and newer then you MUST follow
  11 instructions at the bottom of this file.
  12
  13 If you're upgrading RT from versions prior to 3.8.0 then you MUST follow
  14 instructions below even if your old RT was installed on MySQL 4.1 or newer.
  15
  16 === Upgrading RT from versions prior to 3.8.0 ===
  17
  18 1) Backup RT's database. Test that you can restore from this backup.
  19
  20 2) Follow instructions in the README file to step 7.
  21
  22 3) Apply changes described in step 7, but only up to version 3.7.87.
  23
  24 4) Apply the RT 3.8 schema upgrades. Included in RT is the script
  25 etc/upgrade/upgrade-mysql-schema.pl that generates SQL queries to
  26 upgrade the database's schema. Run it:
  27
  28     perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql
  29
  30 If your mysql database is on a remote host, you can run the script
  31 like this instead
  32
  33     perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
  34
  35 5) Check sanity of the SQL queries yourself or consult with your DBA.
  36
  37 6) Apply the queries. Note that this step can take a while. It may require
  38 additional space on your hard drive comparable with size of your tables.
  39
  40     mysql -u root -p rt3 < queries.sql
  41
  42 NOTE that 'rt3' is the default name of the RT database, change it in the
  43 command above if you're using a different name.
  44
  45 This step should not produce any errors or warnings. If you see any, restore
  46 your database from the backup you made at step 1) and send a report to the
  47 rt-users@lists.bestpractical.com mailing list.
  48
  49 7) Continue from step 7 in the README and apply other upgrades and
  50 follow the remaining steps.
  51
  52 8) Test everything. The most important parts you have to test:
  53 * binary attachments, like docs, PDFs, and images
  54 * binary custom fields
  55 * everything that may contain characters other than ASCII
  56
  57 === Migrating from MySQL 4.0 to MySQL 4.1 and newer ===
  58
  59 Upgrading both MySQL and RT at the same time is a bad idea. The process becomes
  60 more complicated, more time consuming, greater chance to fail, and much harder
  61 to debug.
  62
  63 It's better to perform the upgrade in two steps. First upgrade MySQL from 4.0
  64 to 4.1 or newer. Remember the following:
  65
  66 * Don't use utf8 as MySQL's character set. This is the default in some
  67   Linux distributions.
  68 * import/export MySQL dumps using binary character set.
  69
  70 When you're sure that everything is fine, you may upgrade RT using the
  71 instructions above.
  72
  73 If you still want to upgrade MySQL and RT simultaneously, then you can
  74 do the following:
  75
  76 1) Install a new RT on MySQL 4.1 or newer.
  77 2) Test that this new clean RT works on this new database.
  78 3) Dump the database from MySQL 4.0.
  79 4) Configure MySQL 4.1 and newer to use Latin1 as default character set
  80    everywhere.
  81 5) Import the dump into the new MySQL server, replacing your empty database you
  82    created at step 1.
  83 6) At this point you have RT 3.8.x code base using an old database. You can
  84    upgrade RT using the instructions above.
  85