[Rt-commit] rt branch, 4.0/reword-upgrading-mysql, updated. rt-4.0.2rc1-10-g68d3e94
Alex Vandiver
alexmv at bestpractical.com
Wed Aug 10 15:20:07 EDT 2011
The branch, 4.0/reword-upgrading-mysql has been updated
via 68d3e94877c106a7123bea2b6debd958ea594bd1 (commit)
via ac0cd59aa131e5e4db0bb71b4a08a1b641d6ffa2 (commit)
from f78aac368cf5047e197220f5439150186cc79790 (commit)
Summary of changes:
docs/UPGRADING.mysql | 89 ++++++++++++++++++++-----------------------------
1 files changed, 36 insertions(+), 53 deletions(-)
- Log -----------------------------------------------------------------
commit ac0cd59aa131e5e4db0bb71b4a08a1b641d6ffa2
Author: Alex Vandiver <alexmv at bestpractical.com>
Date: Wed Aug 10 14:43:01 2011 -0400
Reorder into one longer set of steps with an if-statement
diff --git a/docs/UPGRADING.mysql b/docs/UPGRADING.mysql
index d670567..358575d 100644
--- a/docs/UPGRADING.mysql
+++ b/docs/UPGRADING.mysql
@@ -2,15 +2,15 @@ If you did not start by reading the README file, please start there;
these steps do not list the full upgrading process, merely a part which
is sometimes necessary.
-This file applies if:
- 1) You are migrating from MySQL 4.0 to MySQL 4.1 or above
- OR
- 2) You are upgrading RT from versions prior to 3.8.0, even if your old
- RT was installed on MySQL 4.1 or newer
+This file applies if either:
+
+ 1) You are upgrading RT from a version prior to 3.8.0, on any version
+ of MySQL
+............. OR .............
+ 2) You are migrating from MySQL 4.0 to MySQL 4.1 or above
If neither of the above cases apply, your should upgrade as per the
-instructions in the README. If both cases apply, you should first
-upgrade MySQL and then upgrade RT.
+instructions in the README.
These changes are necessary because MySQL 4.1 and greater changed some
aspects of character set handling that may result in RT failures; this
@@ -18,17 +18,27 @@ will manifest as multiple login requests, corrupted binary attachments,
and corrupted image custom fields, among others. In order to resolve
this issue, the upgrade process will need to modify the schema.
+ 1) If you are migrating from MySQL 4.0 to MySQL 4.1 or above:
+ 1a) Dump the database from your MySQL 4.0 instance using
+ --default-character-set=binary
+
+ 1b) Configure the new MySQL to use Latin1 as the default character
+ set everywhere.
+
+ 1c) Import the dump into the new MySQL server, using the
+ --default-character-set=binary option on restore.
-=== Upgrading RT from versions prior to 3.8.0 ===
+ 1d) Test that your RT works as expected on this new database
- 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) Backup RT's database using --default-character-set=binary
+ Furthermore, test that you can restore from this backup.
- 2) Follow instructions in the README file to step 6b.
+ 3) Follow instructions in the README file to step 6b.
- 3) Apply changes described in step 6b, but only up to version 3.7.87.
+ 4) Apply changes described in the README's step 6b, but only up to
+ version 3.7.87.
- 4) Apply the RT 3.8 schema upgrades. Included in RT is the script
+ 5) Apply the RT 3.8 schema upgrades. Included in RT is the script
etc/upgrade/upgrade-mysql-schema.pl that will generate the
appropriate SQL queries:
@@ -39,10 +49,10 @@ this issue, the upgrade process will need to modify the schema.
perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
- 5) Check the sanity of the SQL queries in the queries.sql file
+ 6) Check the sanity of the SQL queries in the queries.sql file
yourself, or consult with your DBA.
- 6) Apply the queries. Note that this step can take a while; it may also
+ 7) Apply the queries. Note that this step can take a while; it may also
require additional space on your hard drive comparable with size of
your tables.
@@ -55,48 +65,11 @@ this issue, the upgrade process will need to modify the schema.
restore your database from the backup you made at step 1, and send a
report to the rt-users at lists.bestpractical.com mailing list.
- 7) Re-run the rt-setup-database command from step 6b of the README,
+ 8) Re-run the rt-setup-database command from step 6b of the README,
applying the rest of the upgrades, and follow the README's remaining
steps.
- 8) Test everything. The most important parts you have to test:
+ 9) 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, has a greater chance to
-fail, and is much harder to debug.
-
-It is a much better idea to perform the upgrade in two steps. First
-upgrade MySQL from 4.0 to 4.1 or above, then complete the RT
-upgrade. 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.
commit 68d3e94877c106a7123bea2b6debd958ea594bd1
Author: Alex Vandiver <alexmv at bestpractical.com>
Date: Wed Aug 10 15:20:04 2011 -0400
Add more words describing the why of the Latin1 configuration
diff --git a/docs/UPGRADING.mysql b/docs/UPGRADING.mysql
index 358575d..efadead 100644
--- a/docs/UPGRADING.mysql
+++ b/docs/UPGRADING.mysql
@@ -19,16 +19,21 @@ and corrupted image custom fields, among others. In order to resolve
this issue, the upgrade process will need to modify the schema.
1) If you are migrating from MySQL 4.0 to MySQL 4.1 or above:
- 1a) Dump the database from your MySQL 4.0 instance using
- --default-character-set=binary
+ 1a) Dump the database from your MySQL 4.0; be sure to pass the
+ mysqldump command the --default-character-set=binary option.
+ This is necessary because the data was originally encoded in
+ Latin1.
1b) Configure the new MySQL to use Latin1 as the default character
- set everywhere.
+ set everywhere, not UTF-8. This is necessary so the import in
+ the next step assumes the data is Latin1.
- 1c) Import the dump into the new MySQL server, using the
- --default-character-set=binary option on restore.
+ 1c) Import the dump made in step 1a into the new MySQL server, using
+ the --default-character-set=binary option on restore. This will
+ ensure that the data is imported as bytes, which will be
+ interpreted as Latin1 thanks to step 1b above.
- 1d) Test that your RT works as expected on this new database
+ 1d) Test that your RT works as expected on this new database.
2) Backup RT's database using --default-character-set=binary
Furthermore, test that you can restore from this backup.
@@ -73,3 +78,8 @@ this issue, the upgrade process will need to modify the schema.
* binary attachments, like docs, PDFs, and images
* binary custom fields
* everything that may contain characters other than ASCII
+
+10) If you were upgrading from MySQL 4.0, you may now, if you wish,
+ reconfigure your newer MySQL instance to use UTF-8 as the default
+ character set, as step 7 above adjusted the cahracter sets on all
+ existing tables to contain UTF-8 encoded data, rather than Latin1.
-----------------------------------------------------------------------
More information about the Rt-commit
mailing list