]>
Commit | Line | Data |
---|---|---|
dab09ea8 MKG |
1 | If you did not start by reading the README file, please start there; these |
2 | steps do not list the full upgrading process, merely a part which is sometimes | |
3 | necessary. | |
84fb5b46 MKG |
4 | |
5 | This file applies if either: | |
6 | ||
dab09ea8 MKG |
7 | =over |
8 | ||
9 | =item 1. | |
10 | ||
11 | You are upgrading RT from a version prior to 3.8.0, on any version | |
12 | of MySQL | |
13 | ||
14 | =item 2. | |
15 | ||
16 | You are migrating from MySQL 4.0 to MySQL 4.1 or above | |
17 | ||
18 | =back | |
84fb5b46 MKG |
19 | |
20 | If neither of the above cases apply, your should upgrade as per the | |
21 | instructions in the README. | |
22 | ||
dab09ea8 MKG |
23 | These changes are necessary because MySQL 4.1 and greater changed some aspects |
24 | of character set handling that may result in RT failures; this will manifest | |
25 | as multiple login requests, corrupted binary attachments, and corrupted image | |
26 | custom fields, among others. In order to resolve this issue, the upgrade | |
27 | process will need to modify the schema. | |
28 | ||
29 | =over | |
30 | ||
31 | =item 1. | |
32 | ||
33 | If you are moving the database and/or upgrading MySQL | |
34 | ||
35 | =over | |
36 | ||
37 | =item 1a. | |
38 | ||
39 | Dump the database; with MySQL 4.1 and greater be sure to pass the mysqldump | |
40 | command the --default-character-set=binary option. This is necessary because | |
41 | the data was originally encoded in Latin1. | |
42 | ||
43 | =item 1b. | |
44 | ||
45 | Configure the new MySQL to use Latin1 as the default character set everywhere, | |
46 | not UTF-8. This is necessary so the import in the next step assumes the data | |
47 | is Latin1. | |
48 | ||
49 | =item 1c. | |
50 | ||
51 | Import the dump made in step 1a into the new MySQL server, using the | |
52 | --default-character-set=binary option on restore. This will ensure that the | |
53 | data is imported as bytes, which will be interpreted as Latin1 thanks to step | |
54 | 1b above. | |
55 | ||
56 | =item 1d. | |
57 | ||
58 | Test that your RT works as expected on this new database. | |
59 | ||
60 | =back | |
61 | ||
62 | =item 2. | |
63 | ||
64 | Backup RT's database using --default-character-set=binary Furthermore, test | |
65 | that you can restore from this backup. | |
66 | ||
67 | =item 3. | |
68 | ||
69 | Follow instructions in the README file to step 6b. | |
70 | ||
71 | =item 4. | |
72 | ||
73 | Apply changes described in the README's step 6b, but only up to version | |
74 | 3.7.87. | |
75 | ||
76 | =item 5. | |
77 | ||
78 | Apply the RT 3.8 schema upgrades. Included in RT is the script | |
79 | etc/upgrade/upgrade-mysql-schema.pl that will generate the appropriate SQL | |
80 | queries: | |
81 | ||
82 | perl etc/upgrade/upgrade-mysql-schema.pl db user pass > queries.sql | |
83 | ||
84 | If your mysql database is on a remote host, you can run the script like this | |
85 | instead: | |
86 | ||
87 | perl etc/upgrade/upgrade-mysql-schema.pl db:host user pass > queries.sql | |
88 | ||
89 | =item 6. | |
90 | ||
91 | Check the sanity of the SQL queries in the queries.sql file yourself, or | |
92 | consult with your DBA. | |
93 | ||
94 | =item 7. | |
95 | ||
96 | Apply the queries. Note that this step can take a while; it may also require | |
97 | additional space on your hard drive comparable with size of your tables. | |
84fb5b46 | 98 | |
dab09ea8 | 99 | mysql -u root -p rt3 < queries.sql |
84fb5b46 | 100 | |
dab09ea8 MKG |
101 | NOTE that 'rt3' is the default name of the RT database, change it in the |
102 | command above if your database is named differently. | |
84fb5b46 | 103 | |
dab09ea8 MKG |
104 | This step should not produce any errors or warnings. If you see any, restore |
105 | your database from the backup you made at step 1, and send a report to the | |
106 | rt-users@lists.bestpractical.com mailing list. | |
84fb5b46 | 107 | |
dab09ea8 | 108 | =item 8. |
84fb5b46 | 109 | |
dab09ea8 MKG |
110 | Re-run the `make upgrade-database` command from step 6b of the README, |
111 | applying the rest of the upgrades, starting with 3.7.87, and follow the | |
112 | README's remaining steps. | |
84fb5b46 | 113 | |
dab09ea8 | 114 | =item 9. |
84fb5b46 | 115 | |
dab09ea8 | 116 | Test everything. The most important parts you have to test: |
84fb5b46 | 117 | |
dab09ea8 | 118 | =over |
84fb5b46 | 119 | |
dab09ea8 | 120 | =item * |
84fb5b46 | 121 | |
dab09ea8 | 122 | binary attachments, like docs, PDFs, and images |
84fb5b46 | 123 | |
dab09ea8 | 124 | =item * |
84fb5b46 | 125 | |
dab09ea8 | 126 | binary custom fields |
84fb5b46 | 127 | |
dab09ea8 | 128 | =item * |
84fb5b46 | 129 | |
dab09ea8 | 130 | everything that may contain characters other than ASCII |
84fb5b46 | 131 | |
dab09ea8 | 132 | =back |
84fb5b46 | 133 | |
84fb5b46 | 134 | |
dab09ea8 | 135 | =item 10. |
84fb5b46 | 136 | |
dab09ea8 MKG |
137 | If you were upgrading from MySQL 4.0, you may now, if you wish, reconfigure |
138 | your newer MySQL instance to use UTF-8 as the default character set, as step 7 | |
139 | above adjusted the character sets on all existing tables to contain UTF-8 | |
140 | encoded data, rather than Latin1. | |
84fb5b46 | 141 | |
dab09ea8 | 142 | =back |