@@ -112,6 +112,128 @@ values or if a value must be changed manually.
112
112
113
113
This will insert the bad API login rate limiting settings.
114
114
115
+ Update MySQL character set/collations (required)
116
+ ------------------------------------------------
117
+
118
+ issue2551282_ and issue2551115_ discuss issues with MySQL's utf8
119
+ support. MySQL has variations on utf8 character support. This
120
+ version of Roundup expects to use utf8mb4 which is a version of
121
+ utf8 that covers all characters, not just the ones in the basic
122
+ multilingual plane. Previous versions of Roundup used latin1 or
123
+ utf8mb3 (also known as just utf8). Newer versions of MySQL are
124
+ supposed to make utf8mb4 and not utf8mb3 the default.
125
+
126
+ To convert your database, you need to have MySQL 8.0.11 or newer
127
+ (April 2018) and a mysql client.
128
+
129
+ .. warning::
130
+
131
+ This conversion can damage your database. Back up your
132
+ database using mysqldump or other tools. Preferably on a quiet
133
+ database. Verify that your database can be restored (or at
134
+ least look up directions for restoring it). This is very
135
+ important.
136
+
137
+ We suggest shutting down Roundup's interfaces:
138
+
139
+ * web
140
+ * email
141
+ * cron jobs that use Python or roundup-admin
142
+
143
+ then make your backup.
144
+
145
+ Then connect to your mysql instance using ``mysql`` with the
146
+ information in ``config.ini``. If your tracker's ``config.ini``
147
+ includes::
148
+
149
+ name = roundupdb
150
+ host = localhost
151
+ user = roundupuser
152
+ password = rounduppw
153
+
154
+ you would run some version of::
155
+
156
+ mysql -u roundupuser --host localhost -p roundupdb
157
+
158
+ and supply ``rounduppw`` when prompted.
159
+
160
+ With the Roundup database quiet, convert the character set for the
161
+ database and then for all the tables. To convert the tables you
162
+ need a list of them. To get this run::
163
+
164
+ mysql -sN -u roundupuser --host localhost -p \
165
+ -e 'show tables;' roundupdb > /tmp/tracker.tables
166
+
167
+ The ``-sN`` removes line drawing characters and column headers
168
+ from the output. For each table ``<t>`` in the file, run::
169
+
170
+ ALTER TABLE `<t>` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
171
+
172
+ You can automate this conversion using sed::
173
+
174
+ sed -e 's/^/ALTER TABLE `/' \
175
+ -e 's/$/` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;/'\
176
+ /tmp/tracker.tables> /tmp/tracker.tables.sql
177
+
178
+ The backticks "`" are required as some of the table names became
179
+ MySQL reserved words during Roundup's lifetime.
180
+
181
+ Inspect ``tracker.tables.sql`` to see if all the lines look
182
+ correct. If so then we can start the conversion.
183
+
184
+ First convert the character set for the database by running::
185
+
186
+ mysql -u roundupuser --host localhost -p roundupdb
187
+
188
+ Then at the ``mysql>`` prompt run::
189
+
190
+ ALTER DATABASE roundupdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
191
+
192
+ you should see: ``Query OK, 1 row affected (0.01 sec)``.
193
+
194
+ Now to modify all the tables run:
195
+
196
+ \. /tmp/tracker.tables.sql
197
+
198
+ You will see output similar to::
199
+
200
+ Query OK, 5 rows affected (0.01 sec)
201
+ Records: 5 Duplicates: 0 Warnings: 0
202
+
203
+ for each table. The rows/records will depend on the number of
204
+ entries in the table. This can take a while.
205
+
206
+ Once you have successfully completed this, copy your tracker's
207
+ config.ini to a backup file. Edit ``config.ini`` to use the defaults:
208
+
209
+ * mysql_charset = utf8mb4
210
+ * mysql_collation = utf8mb4_unicode_ci
211
+ * mysql_binary_collation = utf8mb4_0900_bin
212
+
213
+ Also look for a ``~/.my.cnf`` for the roundup user and make sure
214
+ that the settings for character set (charset) are utf8mb4 compatible.
215
+
216
+ To test, run ``roundup-admin -i tracker_home`` and display an
217
+ issue designator: e.g. ``display issue10``. Check that the text
218
+ fields are properly displayed (e.g. title). Start the web
219
+ interface and browse some issues. Again, check that the text
220
+ fields display correctly, that the history at the bottom of the
221
+ issues displays correctly and if you are using the default full
222
+ text search, make sure that that works.
223
+
224
+ If this works, bring email cron jobs etc. back online.
225
+
226
+ If this fails, take down the web interface, restore the database
227
+ from backup, restore the old config.ini. Then test again and
228
+ reach out to the mailing list for help.
229
+
230
+ We can use assistance in getting these directions corrected or
231
+ enhanced. The core Roundup developers don't use MySQL for their
232
+ production workloads so we count on users to help us with this.
233
+
234
+ .. _issue2551282: https://issues.roundup-tracker.org/issue2551282
235
+ .. _issue2551115: https://issues.roundup-tracker.org/issue2551115
236
+
115
237
Disable performance improvement for wsgi mode (optional)
116
238
--------------------------------------------------------
117
239
0 commit comments