-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.
+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 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
+=over
+
+=item 1.
+
+You are upgrading RT from a version prior to 3.8.0, on any version
+of MySQL
+
+=item 2.
+
+You are migrating from MySQL 4.0 to MySQL 4.1 or above
+
+=back
If neither of the above cases apply, your should upgrade as per the
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
-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.
+These changes are necessary because MySQL 4.1 and greater changed some aspects
+of character set handling that may result in RT failures; this 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.
+
+=over
+
+=item 1.
+
+If you are moving the database and/or upgrading MySQL
+
+=over
+
+=item 1a.
+
+Dump the database; with MySQL 4.1 and greater be sure to pass the mysqldump
+command the --default-character-set=binary option. This is necessary because
+the data was originally encoded in Latin1.
+
+=item 1b.
+
+Configure the new MySQL to use Latin1 as the default character set everywhere,
+not UTF-8. This is necessary so the import in the next step assumes the data
+is Latin1.
+
+=item 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.
+
+=item 1d.
+
+Test that your RT works as expected on this new database.
+
+=back
+
+=item 2.
+
+Backup RT's database using --default-character-set=binary Furthermore, test
+that you can restore from this backup.
+
+=item 3.
+
+Follow instructions in the README file to step 6b.
+
+=item 4.
+
+Apply changes described in the README's step 6b, but only up to version
+3.7.87.
+
+=item 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:
+
+ 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
+
+=item 6.
+
+Check the sanity of the SQL queries in the queries.sql file yourself, or
+consult with your DBA.
+
+=item 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.
- 1) If you are moving the database and/or upgrading MySQL
- 1a) Dump the database; with MySQL 4.1 and greater be sure to pass
- the mysqldump command the --default-character-set=binary option.
- This is necessary because the data was originally encoded in
- Latin1.
+ mysql -u root -p rt3 < queries.sql
- 1b) Configure the new MySQL to use Latin1 as the default character
- set everywhere, not UTF-8. This is necessary so the import in
- the next step assumes the data is Latin1.
+NOTE that 'rt3' is the default name of the RT database, change it in the
+command above if your database is named differently.
- 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.
+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.
- 1d) Test that your RT works as expected on this new database.
+=item 8.
- 2) Backup RT's database using --default-character-set=binary
- Furthermore, test that you can restore from this backup.
+Re-run the `make upgrade-database` command from step 6b of the README,
+applying the rest of the upgrades, starting with 3.7.87, and follow the
+README's remaining steps.
- 3) Follow instructions in the README file to step 6b.
+=item 9.
- 4) Apply changes described in the README's step 6b, but only up to
- version 3.7.87.
+Test everything. The most important parts you have to test:
- 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:
+=over
- perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql
+=item *
- If your mysql database is on a remote host, you can run the script
- like this instead:
+binary attachments, like docs, PDFs, and images
- perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql
+=item *
- 6) Check the sanity of the SQL queries in the queries.sql file
- yourself, or consult with your DBA.
+binary custom fields
- 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.
+=item *
- mysql -u root -p rt3 < queries.sql
+everything that may contain characters other than ASCII
- NOTE that 'rt3' is the default name of the RT database, change it in
- the command above if your database is named differently.
+=back
- 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.
- 8) Re-run the `make upgrade-database` command from step 6b of the
- README, applying the rest of the upgrades, starting with 3.7.87, and
- follow the README's remaining steps.
+=item 10.
- 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
+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 character sets on all existing tables to contain UTF-8
+encoded data, rather than Latin1.
-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 character sets on all
- existing tables to contain UTF-8 encoded data, rather than Latin1.
+=back
projects / freeside.git / blobdiff