import rt 3.8.7

[freeside.git] / rt / UPGRADING.mysql

diff --git a/rt/UPGRADING.mysql b/rt/UPGRADING.mysql
new file mode 100644 (file)
index 0000000..accaa97
--- /dev/null
+++ b/rt/UPGRADING.mysql
@@ -0,0 +1,85 @@
+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. 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.
+6) At this point you have RT 3.8.x code base using an old database. You can
+   upgrade RT using the instructions above.
+