/[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.18 - (show annotations) (download) (as text)
Fri Dec 29 05:49:47 2006 UTC (11 years, 5 months ago) by nightmorph
Branch: MAIN
Changes since 1.17: +11 -3 lines
File MIME type: application/xml
added MERGE tables note for bug 159340

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

  ViewVC Help
Powered by ViewVC 1.1.20