/[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.20 - (show annotations) (download) (as text)
Thu May 17 22:25:45 2007 UTC (11 years, 6 months ago) by rane
Branch: MAIN
Changes since 1.19: +2 -2 lines
File MIME type: application/xml
there was one 'in' too much, thanks to keytoaster on irc for reporting

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

  ViewVC Help
Powered by ViewVC 1.1.20