/[gentoo]/xml/htdocs/doc/en/mysql-upgrading.xml
Gentoo

Contents of /xml/htdocs/doc/en/mysql-upgrading.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.24 - (show annotations) (download) (as text)
Wed Jul 24 20:40:40 2013 UTC (5 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.23: +2 -2 lines
File MIME type: application/xml
UTF-8 guide is now at https://wiki.gentoo.org/wiki/UTF-8

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/mysql-upgrading.xml,v 1.23 2013/07/22 13:59:36 swift Exp $ -->
4
5 <guide>
6 <title>Upgrade guide to MySQL 4.* or 5.0.*</title>
7
8 <author title="Author">
9 <mail link="citizen428@gentoo.org">Michael Kohl</mail>
10 </author>
11 <author title="Author">
12 <mail link="vivo@gentoo.org">Francesco Riosa</mail>
13 </author>
14
15 <abstract>
16 The MySQL herd is proud to announce that MySQL 5.0 will soon be found in
17 Gentoo's stable tree. This document describes how to upgrade to MySQL 4.* and
18 to 5.0.*.
19 </abstract>
20
21 <!-- The content of this document is licensed under the CC-BY-SA license -->
22 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
23 <license/>
24
25 <version>2</version>
26 <!-- Content date is 2007-06-04 -->
27 <date>2013-07-22</date>
28
29 <chapter>
30 <title>Straight upgrade, suggested for 4.1 =&gt; 5.0 migration</title>
31 <section>
32 <body>
33
34 <p>
35 The myisam storage engine in version 4.1 was already mature enough to allow a
36 direct upgrade to the next major version of MySQL.
37 </p>
38
39 <note>
40 This is not true for MERGE tables. You will likely run into trouble if you
41 attempt a direct upgrade for this (rarely used) type of table. You should dump
42 and recreate those tables and restore their contents in the process of
43 upgrading. If unsure, you should begin with <uri link="#doc_chap2">Upgrading
44 from old versions of MySQL</uri>.
45 </note>
46
47 <p>
48 For this step two shells are required because locks belong to the mysql
49 session.
50 </p>
51
52 <pre caption="Straight upgrade from 4.1 to 5.0.*">
53 # <i>quickpkg dev-db/mysql</i>
54 # <i>alias MYSQL="mysql --user=root --password=</i><comment>'your_password'</comment><i>"</i>
55 # <i>DATADIR=$(MYSQL --batch --raw --silent --skip-column-names \</i>
56 <i>--execute='SHOW variables LIKE "datadir";' \</i>
57 <i>| sed -e 's|datadir[ \t]||')</i>
58
59 <comment>(This next step should be done in the second shell)</comment>
60 # <i>mysql --user=root --password=</i><comment>'your_password'</comment>
61 mysql&gt; <i>FLUSH TABLES WITH READ LOCK;</i>
62
63 <comment>(Return to the first shell to run this command)</comment>
64 # <i>tar -cjpvf ~/mysql.$(date +%F"T"%H-%M).tar.bz2 \</i>
65 <i>/etc/conf.d/mysql /etc/mysql/my.cnf "${DATADIR}"</i>
66
67 <comment>(The following commands should be done in the second shell)</comment>
68 mysql&gt; <i>UNLOCK TABLES;</i>
69 mysql&gt; <i>quit</i>
70
71 <comment>(Return to the first shell for the rest of the upgrade)</comment>
72 # <i>tar -tjvf ~/mysql.*.tar.bz2</i>
73 # <i>emerge -av "&gt;dev-db/mysql-5.0"</i>
74 # <i>dispatch-conf</i>
75 # <i>revdep-rebuild</i>
76 # <i>/etc/init.d/mysql restart</i>
77 # <i>mysql_upgrade_shell --user=root --password=</i><comment>'your_password'</comment><i> \</i>
78 <i>--protocol=tcp --datadir="${DATADIR}"</i>
79 # <i>/etc/init.d/mysql restart</i>
80 # <i>unset DATADIR</i>
81 # <i>unalias MYSQL</i>
82 </pre>
83
84 </body>
85 </section>
86 </chapter>
87
88 <chapter>
89 <title>Upgrading from old versions of MySQL</title>
90 <section>
91 <body>
92
93 <p>
94 Users upgrading from an old version (&lt;4.0.24) of MySQL will first have to
95 install MySQL 4.0.25. If you are already running a more recent version, you can
96 skip this section and continue with the <uri link="#backup">next one</uri>.
97 </p>
98
99 <pre caption="Simple upgrade">
100 # <i>emerge -av --buildpkg "&lt;mysql-4.1"</i>
101 </pre>
102
103 </body>
104 </section>
105 </chapter>
106
107 <chapter id="backup">
108 <title>Creating a backup of your current data</title>
109 <section>
110 <body>
111
112 <impo>
113 Values inside primary keys are handled differently in various MySQL versions,
114 see <uri link="http://bugs.gentoo.org/108502">bug #108502</uri> for more
115 details, it is higly recommended to scan your tables for values of "0" (zero)
116 or less and update them to a value greater than or equal to "1".
117 </impo>
118
119 <p>
120 One of the most important tasks that every database administrator has to
121 perform is backing up data. Here we go:
122 </p>
123
124 <pre caption="Dump of all databases">
125 # <i>mysqldump \</i>
126 <i>-uroot \</i>
127 <i>--password=</i><comment>'your_password'</comment><i> \</i>
128 <i>-hlocalhost \</i>
129 <i>--all-databases \</i>
130 <i>--opt \</i>
131 <i>--allow-keywords \</i>
132 <i>--flush-logs \</i>
133 <i>--hex-blob \</i>
134 <i>--master-data \</i>
135 <i>--max_allowed_packet=16M \</i>
136 <i>--quote-names \</i>
137 <i>--result-file=BACKUP_MYSQL_4.0.SQL</i>
138 </pre>
139
140 <p>
141 Now a file named <path>BACKUP_MYSQL_4.0.SQL</path> should exist, which can be
142 used later to recreate your data. The data is described in the MySQL dialect of
143 SQL, the Structured Query Language.
144 </p>
145
146 <p>
147 Now would also be a good time to see if the backup you have created is working.
148 </p>
149
150 </body>
151 </section>
152 </chapter>
153
154 <chapter>
155 <title>Upgrading from recent versions of MySQL</title>
156 <section>
157 <body>
158
159 <p>
160 If you have skipped step #1, you now have to create a backup package (of the
161 database server, not the data) of the currently installed version:
162 </p>
163
164 <pre caption="Binary package backup">
165 # <i>quickpkg dev-db/mysql</i>
166 </pre>
167
168 <p>
169 Now it's time to clean out the current version and all of its data:
170 </p>
171
172 <pre caption="Uninstall MySQL">
173 # <i>/etc/init.d/mysql stop</i>
174 # <i>emerge -C mysql</i>
175 # <i>tar cjpvf ~/mysql.$(date +%F"T"%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i>
176 # <i>ls -l ~/mysql.*</i>
177 # <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
178 </pre>
179
180 <note>
181 Now two different backups should exist: the SQL one, which is portable between
182 various versions of MySQL, and the other one that will allow you to quickly
183 restore your database. This is covered later in this document in more detail.
184 </note>
185
186 <p>
187 After you get rid of your old MySQL installation, you can now install the new
188 version. Note that <c>revdep-rebuild</c> is necessary for rebuilding packages
189 linking against MySQL.
190 </p>
191
192 <pre caption="Upgrading the binaries">
193 # <i>emerge -av "&gt;mysql-4.1"</i>
194 <comment>(Update your config files, you may also use dispatch-conf)</comment>
195 # <i>etc-update</i>
196 # <i>revdep-rebuild</i>
197 </pre>
198
199 <p>
200 Now configure the newly installed version of MySQL and restart the daemon:
201 </p>
202
203 <pre caption="Configure MySQL 4.1 base setup">
204 # <i>emerge --config =mysql-4.1.<comment>&lt;micro_version&gt;</comment></i>
205 # <i>/etc/init.d/mysql start</i>
206 </pre>
207
208 <p>
209 Finally you can import the backup you have created during step #2.
210 </p>
211
212 <impo>
213 The default <path>/etc/mysql/my.cnf</path> file sets binary logging on
214 (<c>log-bin</c>) by default. This will log every single transaction that
215 modifies data. If run on a very large database (1GB or more), this could create
216 extremely large files that take up disk space rather quickly. If you are low on
217 space, disabling binary logging might be a good idea.
218 </impo>
219
220 <impo>
221 The default character set in MySQL 4.1 and above is <c>utf8</c>. If the data
222 contain <e>non</e>-ASCII characters, you may want to preserve the default
223 character set of the database replacing all occurrences of <c>utf8</c> with
224 <c>latin1</c> in the <path>/etc/mysql/my.cnf</path> config file. More
225 information can be found <uri link="#On_charset_conversion">Charset
226 conversion</uri> chapter.
227 </impo>
228
229 <impo>
230 The administrative <c>mysql</c> database that contains user names, passwords
231 amongst other things is and <b>must</b> be encoded in utf8.
232 </impo>
233
234 <p>
235 Older mysqldump utilities may export tables in the wrong order when foreign keys
236 are involved. To work around this problem, surround the SQL with the following
237 statements:
238 </p>
239
240 <pre caption="Fixing foreign key checks">
241 SET FOREIGN_KEY_CHECKS=0
242 SET FOREIGN_KEY_CHECKS=1
243 </pre>
244
245 <p>
246 Next, import the backup.
247 </p>
248
249 <pre caption="Importing the SQL backup">
250 # <i>cat BACKUP_MYSQL_4.0.SQL \</i>
251 <i>| mysql \</i>
252 <i>-uroot \</i>
253 <i>--password=</i><comment>'your_password'</comment><i> \</i>
254 <i>-hlocalhost \</i>
255 <i>--max_allowed_packet=16M</i>
256
257 # <i>mysql_fix_privilege_tables \</i>
258 <i>--defaults-file=/etc/mysql/my.cnf \</i>
259 <i>--user=root \</i>
260 <i>--password=</i><comment>'your_password'</comment><i></i>
261 </pre>
262
263 <p>
264 If you restart your MySQL daemon now and everything goes as expected, you have
265 a fully working version of 4.1.x.
266 </p>
267
268 <pre caption="Restart the MySQL instance">
269 # <i>/etc/init.d/mysql restart</i>
270 </pre>
271
272 <p>
273 If you encountered any problems during the upgrade process, please report them
274 on <uri link="http://bugs.gentoo.org">Bugzilla</uri>.
275 </p>
276
277 </body>
278 </section>
279 </chapter>
280
281 <chapter>
282 <title>Recover the old installation of MySQL 4.0</title>
283 <section>
284 <body>
285
286 <p>
287 If you are not happy with MySQL 4.1, it's possible to go back to MySQL 4.0.
288 </p>
289
290 <pre caption="Reverting to the previous version">
291 # <i>/etc/init.d/mysql stop</i>
292 # <i>emerge -C mysql</i>
293 # <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
294 # <i>emerge --usepkgonly "&lt;mysql-4.1"</i>
295 <comment>(Replace &lt;timestamp&gt; with the one used when creating the backup.)</comment>
296 # <i>tar -xjpvf mysql.&lt;timestamp&gt;.tar.bz2 -C /</i>
297 # <i>/etc/init.d/mysql start</i>
298 </pre>
299
300 <impo>
301 If packages other than <c>dev-db/mysql</c> have been emerged following this
302 guide, you need to run <c>revdep-rebuild</c> to ensure that every client is
303 using the correct mysqlclient shared object.
304 </impo>
305
306 </body>
307 </section>
308 </chapter>
309
310 <chapter id="On_charset_conversion">
311 <title>On charset conversion:</title>
312 <section>
313 <title>Introduction</title>
314 <body>
315
316 <p>
317 This chapter is not intended to be an exhaustive guide on how to do such
318 conversions, rather a short list of hints on which the reader can elaborate.
319 </p>
320
321 <p>
322 Converting a database may be a complex task and difficulty increases with data
323 variancy. Things like serialized object and blobs are one example where it's
324 difficult to keeps pieces together.
325 </p>
326
327 </body>
328 </section>
329 <section>
330 <title>Indexes</title>
331 <body>
332
333 <p>
334 Every utf-8 character is considered 3 bytes long within an index. Indexes in
335 MySQL can be up to 1000 bytes long (767 bytes for InnoDB tables). Note that the
336 limits are measured in bytes, whereas the length of a column is interpreted as
337 number of characters.
338 </p>
339
340 <p>
341 MySQL can also create indexes on parts of a column, this can be of some help.
342 Below are some examples:
343 </p>
344
345 <pre caption="Indexing using prefixes">
346 $ <i>mysql -uroot -p'<comment>your_password</comment>' test</i>
347
348 mysql> <i>SHOW variables LIKE "version" \G</i>
349 *************************** 1. row ***************************
350 Variable_name: version
351 Value: <comment>5.0.24-log</comment>
352 1 row in set (0.00 sec)
353
354 mysql> <i>CREATE TABLE t1 (</i>
355 -> <i>c1 varchar(255) NOT NULL default '',</i>
356 -> <i>c2 varchar(255) NOT NULL default ''</i>
357 -> <i>) ENGINE=MyISAM DEFAULT CHARSET=utf8;</i>
358 Query OK, 0 rows affected (0.01 sec)
359
360 mysql> <i>ALTER TABLE t1</i>
361 -> <i>ADD INDEX idx1 ( c1 , c2 );</i>
362 <comment>ERROR 1071 (42000): Specified key was too long; max key length is 1000 bytes</comment>
363
364 mysql> <i>ALTER TABLE t1</i>
365 -> <i>ADD INDEX idx1 ( c1(165) , c2(165) );</i>
366 Query OK, 0 rows affected (0.01 sec)
367 Records: 0 Duplicates: 0 Warnings: 0
368
369 mysql> <i>CREATE TABLE t2 (</i>
370 -> <i>c1 varchar(255) NOT NULL default '',</i>
371 -> <i>c2 varchar(255) NOT NULL default ''</i>
372 -> <i>) ENGINE=MyISAM DEFAULT CHARSET=sjis;</i>
373 Query OK, 0 rows affected (0.00 sec)
374
375 mysql> <i>ALTER TABLE t2</i>
376 -> <i>ADD INDEX idx1 ( c1(250) , c2(250) );</i>
377 Query OK, 0 rows affected (0.03 sec)
378 Records: 0 Duplicates: 0 Warnings: 0
379
380 mysql> <i>CREATE TABLE t3 (</i>
381 -> <i>c1 varchar(255) NOT NULL default '',</i>
382 -> <i>c2 varchar(255) NOT NULL default ''</i>
383 -> <i>) ENGINE=MyISAM DEFAULT CHARSET=latin1;</i>
384 Query OK, 0 rows affected (0.00 sec)
385
386 mysql> <i>ALTER TABLE t3</i>
387 -> <i>ADD INDEX idx1 ( c1 , c2 );</i>
388 Query OK, 0 rows affected (0.03 sec)
389 Records: 0 Duplicates: 0 Warnings: 0
390 </pre>
391
392 </body>
393 </section>
394 <section>
395 <title>Environment</title>
396 <body>
397
398 <p>
399 The system must be configured to support the UTF-8 locale. You will find more
400 information in the <uri link="https://wiki.gentoo.org/wiki/UTF-8">UTF-8 article</uri>
401 and <uri link="https://wiki.gentoo.org/wiki/Localization/HOWTO">Localization Guide</uri>
402 documents.
403 </p>
404
405 <p>
406 In this example, we set some shell environment variables to make use of the
407 English UTF-8 locale in <path>/etc/env.d/02locale</path>:
408 </p>
409
410 <pre caption="/etc/env.d/02locale">
411 LC_ALL=en_US.UTF-8
412 LANG=en_US.UTF-8
413 </pre>
414
415 <p>
416 Be sure to run <c>env-update &amp;&amp; source /etc/profile</c> afterward.
417 </p>
418
419 </body>
420 </section>
421 <section>
422 <title>iconv</title>
423 <body>
424
425 <p>
426 <c>iconv</c>, provided by <c>sys-libs/glibc</c>, is used to convert text files
427 from one charset to another. The <c>app-text/recode</c> package can be used as
428 well.
429 </p>
430
431 <pre caption="Using iconv">
432 <comment>(From latin1 to utf8)</comment>
433 $ <i>iconv -f ISO-8859-15 -t UTF-8 file1.sql &gt; file2.sql</i>
434
435 <comment>(From Japanese to utf8)</comment>
436 $ <i>iconv -f ISO2022JP -t UTF-8 file1.sql &gt; file2.sql</i>
437 </pre>
438
439 <p>
440 <c>iconv</c> can be used to recode a sql dump even if the environment is not
441 set to utf8.
442 </p>
443
444 </body>
445 </section>
446 <section>
447 <title>SQL Mangling</title>
448 <body>
449
450 <p>
451 It's possible to use the <c>CONVERT()</c> and <c>CAST()</c> MySQL functions to
452 convert data in your SQL scripts.
453 </p>
454
455 </body>
456 </section>
457 <section>
458 <title>Apache (webserver)</title>
459 <body>
460
461 <p>
462 To use utf-8 with apache, you need to adjust the following variables in
463 <path>httpd.conf</path>: AddDefaultCharset, CharsetDefault, CharsetSourceEnc.
464 If your source html files aren't encoded in utf-8, they <b>must</b> be
465 converted with <c>iconv</c> or <c>recode</c>.
466 </p>
467
468 </body>
469 </section>
470 </chapter>
471
472 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20