MySQL 4.1 and greater implemented changes in character set handling
that may result in RT failures: multiple login requests, binary attachments
breakage, image custom fields breakage and more.

In order to resolve this issue we've changed our schema for MySQL 4.1 and
greater versions.

If you're installing a new RT then you can skip this file.

If you're migrating from MySQL 4.0 to MySQL 4.1 and newer then you MUST follow
instructions at the bottom of this file.

If you're upgrading RT from versions prior to 3.8.0 then you MUST follow
instructions below even if your old RT was installed on MySQL 4.1 or newer.

=== Upgrading RT from versions prior to 3.8.0 ===

1) Backup RT's database. Use --default-character-set=binary if mysql
server is 4.1 or newer. Test that you can restore from this backup.

2) Follow instructions in the README file to step 7.

3) Apply changes described in step 7, but only up to version 3.7.87.

4) Apply the RT 3.8 schema upgrades. Included in RT is the script
etc/upgrade/upgrade-mysql-schema.pl that generates SQL queries to 
upgrade the database's schema. Run it:

    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

5) Check sanity of the SQL queries yourself or consult with your DBA.

6) Apply the queries. Note that this step can take a while. It may require
additional space on your hard drive comparable with size of your tables.

    mysql -u root -p rt3 < queries.sql

NOTE that 'rt3' is the default name of the RT database, change it in the
command above if you're using a different name.

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.

7) Continue from step 7 in the README and apply other upgrades and 
follow the remaining steps.

8) 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

=== Migrating from MySQL 4.0 to MySQL 4.1 and newer ===

Upgrading both MySQL and RT at the same time is a bad idea. The process becomes
more complicated, more time consuming, greater chance to fail, and much harder
to debug.

It's better to perform the upgrade in two steps. First upgrade MySQL from 4.0
to 4.1 or newer. Remember the following:

* Don't use utf8 as MySQL's character set. This is the default in some
  Linux distributions.
* import/export MySQL dumps using binary character set.

When you're sure that everything is fine, you may upgrade RT using the
instructions above.

If you still want to upgrade MySQL and RT simultaneously, then you can
do the following:

1) Install a new RT on MySQL 4.1 or newer.
2) Test that this new clean RT works on this new database.
3) Dump the database from MySQL 4.0.
4) Configure MySQL 4.1 and newer to use Latin1 as default character set
   everywhere.
5) Import the dump into the new MySQL server, replacing your empty database you
   created at step 1, use --default-character-set=binary on restore.
6) At this point you have RT 3.8.x code base using an old database. You can
   upgrade RT using the instructions above.