/[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.17 - (show annotations) (download) (as text)
Mon Dec 4 16:42:50 2006 UTC (11 years, 6 months ago) by nightmorph
Branch: MAIN
Changes since 1.16: +4 -4 lines
File MIME type: application/xml
specified full category/package name for mysql, bug 157089

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

  ViewVC Help
Powered by ViewVC 1.1.20