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