Upgrade to 4.0.8 with mod of ExternalAuth + absolute paths to ticket-menu.
[usit-rt.git] / docs / UPGRADING.mysql
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.
4
5 This file applies if either:
6
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
19
20 If neither of the above cases apply, your should upgrade as per the
21 instructions in the README.
22
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.
98
99     mysql -u root -p rt3 < queries.sql
100
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.
103
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.
107
108 =item 8.
109
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.
113
114 =item 9.
115
116 Test everything. The most important parts you have to test:
117
118 =over
119
120 =item *
121
122 binary attachments, like docs, PDFs, and images
123
124 =item *
125
126 binary custom fields
127
128 =item *
129
130 everything that may contain characters other than ASCII
131
132 =back
133
134
135 =item 10.
136
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.
141
142 =back