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