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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.9 Revision 1.10
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/mysql-upgrading.xml,v 1.9 2006/09/04 09:38:53 nightmorph Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/mysql-upgrading.xml,v 1.10 2006/09/08 10:39:04 neysx Exp $ -->
4 4
5<guide link="/doc/en/mysql-upgrading.xml"> 5<guide link="/doc/en/mysql-upgrading.xml">
6<title>Upgrade guide to MySQL 4.1.x</title> 6<title>Upgrade guide to MySQL 4.1.x</title>
7 7
8<author title="Author"> 8<author title="Author">
11<author title="Author"> 11<author title="Author">
12 <mail link="vivo@gentoo.org">Francesco Riosa</mail> 12 <mail link="vivo@gentoo.org">Francesco Riosa</mail>
13</author> 13</author>
14 14
15<abstract> 15<abstract>
16The MySQL herd is proud to announce that MySQL 4.1 can now be found in Gentoo's 16The MySQL herd is proud to announce that MySQL 5.0 will soon be found in
17unstable tree (~arch). As the team hopes that it soon will be able to stabilize 17Gentoo's stable tree. This document describes how to upgrade from MySQL 4.* to
18this ebuild, here's an upgrade path for all willing testers. 18r.0.*
19</abstract> 19</abstract>
20 20
21<!-- The content of this document is licensed under the CC-BY-SA license --> 21<!-- The content of this document is licensed under the CC-BY-SA license -->
22<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 22<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
23<license/> 23<license/>
24 24
25<version>1.8</version> 25<version>1.8</version>
26<date>2006-09-04</date> 26<date>2006-09-08</date>
27
28<chapter>
29<title>Straight upgrade, suggested for 4.1 =&gt; 5.0 migration</title>
30<section>
31<body>
32
33<p>
34The myisam storage engine in 4.1 version was already mature enough to allow a
35direct 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>
27 63
28<chapter> 64<chapter>
29<title>Upgrading from old versions of MySQL</title> 65<title>Upgrading from old versions of MySQL</title>
30<section> 66<section>
31<body> 67<body>
32 68
33<p> 69<p>
34Users upgrading from an old version (&lt;4.0.24) of MySQL will first have to 70Users upgrading from an old version (&lt;4.0.24) of MySQL will first have to
35install MySQL 4.0.25. If you are already running a current version, you can skip 71install MySQL 4.0.25. If you are already running a more recent version, you can
36this section and continue with the next one. 72skip this section and continue with the <uri link="#backup">next one</uri>.
37</p> 73</p>
38 74
39<pre caption="Simple upgrade"> 75<pre caption="Simple upgrade">
40# <i>emerge -av --buildpkg "&lt;mysql-4.1"</i> 76# <i>emerge -av --buildpkg "&lt;mysql-4.1"</i>
41</pre> 77</pre>
42 78
43</body> 79</body>
44</section> 80</section>
45</chapter> 81</chapter>
46 82
47<chapter> 83<chapter id="backup">
48<title>Creating a backup of your current data</title> 84<title>Creating a backup of your current data</title>
49<section> 85<section>
50<body> 86<body>
51 87
52<p> 88<p>
53One of the most important tasks that every database administrator has to perfom 89One of the most important tasks that every database administrator has to
54is backing up data. Here we go: 90perform is backing up data. Here we go:
55</p> 91</p>
56 92
57<pre caption="Dump of all databases"> 93<pre caption="Dump of all databases">
58# <i>mysqldump \</i> 94# <i>mysqldump \</i>
59 <i>-uroot \</i> 95 <i>-uroot \</i>
69 <i>--quote-names \</i> 105 <i>--quote-names \</i>
70 <i>--result-file=BACKUP_MYSQL_4.0.SQL</i> 106 <i>--result-file=BACKUP_MYSQL_4.0.SQL</i>
71</pre> 107</pre>
72 108
73<p> 109<p>
74Now a file named <path>BACKUP_MYSQL_4.0.SQL</path> should exist, which later can 110Now a file named <path>BACKUP_MYSQL_4.0.SQL</path> should exist, which can be
75be used to recreate your data. The data is described in the MySQL dialect of SQL, 111used later to recreate your data. The data is described in the MySQL dialect of
76the Structured Query Language. 112SQL, the Structured Query Language.
77</p> 113</p>
78 114
79<p> 115<p>
80Now would also be a good time to see if the backup you have created is working. 116Now would also be a good time to see if the backup you have created is working.
81</p> 117</p>
103</p> 139</p>
104 140
105<pre caption="Uninstall MySQL"> 141<pre caption="Uninstall MySQL">
106# <i>/etc/init.d/mysql stop</i> 142# <i>/etc/init.d/mysql stop</i>
107# <i>emerge -C mysql</i> 143# <i>emerge -C mysql</i>
108# <i>tar cjpvf ~/mysql.$(date +%F_%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i> 144# <i>tar cjpvf ~/mysql.$(date +%F"T"%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i>
109# <i>ls -l ~/mysql.*</i> 145# <i>ls -l ~/mysql.*</i>
110# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i> 146# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
111</pre> 147</pre>
112 148
113<note> 149<note>
114Now two different backups should exist: The SQL one, which is portable between 150Now two different backups should exist: the SQL one, which is portable between
115various versions of MySQL, and the other one that will allow you to quickly 151various versions of MySQL, and the other one that will allow you to quickly
116restore your database. This will be covered later in this doc in more detail. 152restore your database. This is covered later in this doc in more detail.
117</note> 153</note>
118 154
119<p> 155<p>
120After you got rid of your old MySQL installation, you can now install the new 156After you got rid of your old MySQL installation, you can now install the new
121version. Note that <c>revdep-rebuild</c> is necessary for rebuilding packages 157version. Note that <c>revdep-rebuild</c> is necessary for rebuilding packages
122linking against MySQL. 158linking against MySQL.
123</p> 159</p>
124 160
125<pre caption="Upgrading the binaries"> 161<pre caption="Upgrading the binaries">
126# <i>emerge -av "&gt;mysql-4.1"</i> 162# <i>emerge -av "&gt;mysql-4.1"</i>
127# <i>dispatch-conf</i> 163<comment>(Update your config files, you may also use dispatch-conf)</comment>
164# <i>etc-update</i>
128# <i>revdep-rebuild</i> 165# <i>revdep-rebuild</i>
129</pre> 166</pre>
130 167
131<p> 168<p>
132Now configure the newly installed version of MySQL and restart the daemon: 169Now configure the newly installed version of MySQL and restart the daemon:
133</p> 170</p>
134 171
135<pre caption="Configure MySQL 4.1 base setup"> 172<pre caption="Configure MySQL 4.1 base setup">
136# <i>emerge --config =mysql-4.1.&lt;micro_version&gt;</i> 173# <i>emerge --config =mysql-4.1.<comment>&lt;micro_version&gt;</comment></i>
137# <i>/etc/init.d/mysql start</i> 174# <i>/etc/init.d/mysql start</i>
138</pre> 175</pre>
139 176
140<p> 177<p>
141Finally you can import the backup you have created during step #2. 178Finally you can import the backup you have created during step #2.
142</p> 179</p>
143 180
144<impo> 181<impo>
145The default <path>/etc/mysql/my.cnf</path> file sets binary logging 182The default <path>/etc/mysql/my.cnf</path> file sets binary logging on
146(<c>log-bin</c>) by default. This will log every single transaction that 183(<c>log-bin</c>) by default. This will log every single transaction that
147modifies data. If run on a very large database (1GB for example), this could 184modifies data. If run on a very large database (1GB or more), this could create
148create extremely large files that take up disk space rather quickly. If you 185extremely large files that take up disk space rather quickly. If you are low on
149are low on space, disabling binary logging might be a good idea. 186space, disabling binary logging might be a good idea.
187</impo>
188
189<impo>
190The default character set in gentoo mysql 4.1 and above is <c>utf8</c>. If the
191data contain <e>non</e>-ASCII characters, you may want to preserve the default
192character 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
194information can be found <uri link="#On_charset_conversion">Charset
195conversion</uri> charapter.
196</impo>
197
198<impo>
199The administrative <c>mysql</c> database that containins user names, passwords
200amongst other things is and <b>must</b> be in encoded in utf8.
150</impo> 201</impo>
151 202
152<pre caption="Importing the SQL backup"> 203<pre caption="Importing the SQL backup">
153# <i>cat BACKUP_MYSQL_4.0.SQL \</i> 204# <i>cat BACKUP_MYSQL_4.0.SQL \</i>
154 <i>| mysql \</i> 205 <i>| mysql \</i>
162 <i>--user=root \</i> 213 <i>--user=root \</i>
163 <i>--password=</i><comment>'your_password'</comment><i></i> 214 <i>--password=</i><comment>'your_password'</comment><i></i>
164</pre> 215</pre>
165 216
166<p> 217<p>
167If you now restart your MySQL daemon and everything went as expected, you will 218If you restart your MySQL daemon now and everything goes as expected, you have
168have a fully working version of 4.1.x! :-) 219a fully working version of 4.1.x.
169</p> 220</p>
170 221
171<pre caption="Restart the MySQL instance"> 222<pre caption="Restart the MySQL instance">
172# <i>/etc/init.d/mysql restart</i> 223# <i>/etc/init.d/mysql restart</i>
173</pre> 224</pre>
174 225
175<p> 226<p>
176If you encountered any problems during the upgrade process, please report them 227If you encountered any problems during the upgrade process, please report them
177at our <uri link="https://bugs.gentoo.org">Bugzilla</uri>. 228on <uri link="http://bugs.gentoo.org">Bugzilla</uri>.
178</p> 229</p>
179 230
180</body> 231</body>
181</section> 232</section>
182</chapter> 233</chapter>
188 239
189<p> 240<p>
190If you are not happy with MySQL 4.1, it's possible to go back to MySQL 4.0. 241If you are not happy with MySQL 4.1, it's possible to go back to MySQL 4.0.
191</p> 242</p>
192 243
193<pre caption="Back to the past"> 244<pre caption="Reverting to the previous version">
194# <i>/etc/init.d/mysql stop</i> 245# <i>/etc/init.d/mysql stop</i>
195# <i>emerge -C mysql</i> 246# <i>emerge -C mysql</i>
196# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i> 247# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
197# <i>emerge --usepkgonly "&lt;mysql-4.1"</i> 248# <i>emerge --usepkgonly "&lt;mysql-4.1"</i>
198# <i>tar -xjpvf mysql.[tag] -C /</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>
199# <i>/etc/init.d/mysql start</i> 251# <i>/etc/init.d/mysql start</i>
200</pre> 252</pre>
201 253
202<note> 254<impo>
203After downgrading, you <e>may</e> need to run <c>revdep-rebuild</c>. 255If packages other than <c>dev-db/mysql</c> have been emerged following this
204</note> 256guide, you need to run <c>revdep-rebuild</c> to ensure that every client is
257using the correct mysqlclient shared object.
258</impo>
205 259
206</body> 260</body>
207</section>
208</chapter>
209
210<chapter>
211<title>Straight upgrade, not supported, dangerous</title>
212<section> 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>
271This charapter is not intended to be an exhaustive guide on how to do such
272conversions, rather a short list of hints on which the reader can elaborate.
273</p>
274
275<p>
276Converting a database may be a complex task and difficulty increases with data
277variancy. Things like serialized object and blobs are one example where it's
278difficult to keeps pieces together.
279</p>
280
213<body> 281</body>
282</section>
283<section>
284<title>Indexes</title>
285<body>
214 286
215<p>
216Under certain conditions it's possible to directly upgrade to the next major
217version of MySQL. If you know what you're doing and think that applies to your
218case, here's a little trick that makes it possible to directly upgrade to
219MySQl 4.1.
220</p> 287<p>
221 288Every utf-8 char is considered 3 bytes long within an index. Indexes in MySQL
222<pre caption="Straight upgrade"> 289can be up to 1000 bytes long (767 bytes for InnoDB tables). Note that the
223# <i>quickpkg dev-db/mysql</i> 290limits are measured in bytes, whereas the length of a column is interpreted as
224# <i>/etc/init.d/mysql stop</i> 291number of characters.
225# <i>tar -cjpvf ~/mysql.$(date +%F_%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i>
226# <i>ls -l ~/mysql.*</i>
227# <i>export MYSQL_STRAIGHT_UPGRADE=1</i>
228# <i>emerge -av "&gt;mysql-4.1"</i>
229# <i>unset MYSQL_STRAIGHT_UPGRADE</i>
230# <i>dispatch-conf</i>
231# <i>revdep-rebuild</i>
232# <i>/etc/init.d/mysql start</i>
233# <i>mysql_fix_privilege_tables --defaults-file=/etc/mysql/my.cnf \</i>
234 <i>-uroot --password=</i><comment>'your_password'</comment><i></i>
235# <i>mysql --database=mysql -uroot --password=</i><comment>'your_password'</comment><i> &lt; /tmp/new_pieces.sql</i>
236# <i>/etc/init.d/mysql restart</i> # just to be sure
237</pre>
238
239<p> 292</p>
240Good luck and if something fails, don't say we didn't warn you! ;-) 293
294<p>
295MySQL can also create indexes on parts of a column, this can be of some help.
296Below are some examples:
297</p>
298
299<pre caption="Indexing using prefixes">
300$ <i>mysql -uroot -p'<comment>your_password</comment>' test</i>
301
302mysql> <i>SHOW variables LIKE "version" \G</i>
303*************************** 1. row ***************************
304Variable_name: version
305 Value: <comment>5.0.24-log</comment>
3061 row in set (0.00 sec)
307
308mysql> <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>
312Query OK, 0 rows affected (0.01 sec)
313
314mysql> <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
318mysql> <i>ALTER TABLE t1</i>
319 -> <i>ADD INDEX idx1 ( c1(165) , c2(165) );</i>
320Query OK, 0 rows affected (0.01 sec)
321Records: 0 Duplicates: 0 Warnings: 0
322
323mysql> <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>
327Query OK, 0 rows affected (0.00 sec)
328
329mysql> <i>ALTER TABLE t2</i>
330 -> <i>ADD INDEX idx1 ( c1(250) , c2(250) );</i>
331Query OK, 0 rows affected (0.03 sec)
332Records: 0 Duplicates: 0 Warnings: 0
333
334mysql> <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>
338Query OK, 0 rows affected (0.00 sec)
339
340mysql> <i>ALTER TABLE t3</i>
341 -> <i>ADD INDEX idx1 ( c1 , c2 );</i>
342Query OK, 0 rows affected (0.03 sec)
343Records: 0 Duplicates: 0 Warnings: 0
344</pre>
345
346</body>
347</section>
348<section>
349<title>Environment</title>
350<body>
351
352<p>
353Working in a utf-8 environment, with utf-8 editors and tools help too:
354</p>
355
356<pre caption="Shell evironment variables">
357LC_ALL=en_US.UTF-8
358LANG=en_US.UTF-8
359export LC_ALL LANG
360</pre>
361
362<p>
363The system must be configured to support the chosen UTF-8 locale. You will find
364more information in our <uri link="/doc/en/utf-8.xml">Using UTF-8 with
365Gentoo</uri> and <uri link="/doc/en/guide-localization.xml">Localization
366Guide</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
377from one charset to another. The <c>app-text/recode</c> package can be used as
378well.
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
391set to utf8.
392</p>
393
394</body>
395</section>
396<section>
397<title>SQL Mangling</title>
398<body>
399
400<p>
401It's possible to use the <c>CONVERT()</c> and <c>CAST()</c> MySQL functions to
402convert data in your SQL scripts.
403</p>
404
405</body>
406</section>
407<section>
408<title>Apache (webserver)</title>
409<body>
410
411<p>
412To use utf-8 with apache, you need to adjust the folowing variables in
413<path>httpd.conf</path>: AddDefaultCharset, CharsetDefault, CharsetSourceEnc.
414If your source html files aren't encoded in utf-8, they <b>must</b> be
415converted with <c>iconv</c> or <c>recode</c>.
241</p> 416</p>
242 417
243</body> 418</body>
244</section> 419</section>
245</chapter> 420</chapter>

Legend:
Removed from v.1.9  
changed lines
  Added in v.1.10

  ViewVC Help
Powered by ViewVC 1.1.20