/[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.13 - (show annotations) (download) (as text)
Sun Sep 10 01:57:15 2006 UTC (11 years, 4 months ago) by rane
Branch: MAIN
Changes since 1.12: +4 -4 lines
File MIME type: application/xml
the title should mention 5.* and 4.*, not just 4.* to reflect the content

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

  ViewVC Help
Powered by ViewVC 1.1.20