doc/en/mysql-upgrading.xml

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/mysql-upgrading.xml,v 1.2 2005/09/21 19:15:49 rane Exp $ -->

<guide link="/doc/en/mysql-upgrading.xml">
<title>Upgrade guide to MySQL 4.1.x</title>

<author title="Author">
  <mail link="citizen428@gentoo.org">Michael Kohl</mail>
</author>
<author title="Author">
  <mail link="vivo@gentoo.org">Francesco Riosa</mail>
</author>

<abstract>
The MySQL herd is proud to announce that MySQL 4.1 can now be found in Gentoo's
unstable tree (~arch). As the team hopes that it soon will be able to stabilize
this ebuild, here's an upgrade path for all willing testers.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.2</version>
<date>2005-10-17</date>

<chapter>
<title>Upgrading from old versions of MySQL</title>
<section>
<body>

<p>
Users upgrading from an old version (&lt;4.0.24) of MySQL will first have to
install MySQL 4.0.25. If you are already running a current version, you can skip
this section and continue with the next one.
</p>

<pre caption="Simple upgrade">
# <i>emerge -av --buildpkg "&lt;mysql-4.1"</i>
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Creating a backup of your current data</title>
<section>
<body>

<p>
One of the most important tasks that every database administrator has to perfom
is backing up data. Here we go:
</p>

<pre caption="Dump of all databases">
# <i>mysqldump \</i>
  <i>-uroot \</i>
  <i>-p$PASSWORD \</i>
  <i>-hlocalhost \</i>
  <i>--all-databases \</i>
  <i>--all \</i>
  <i>--opt \</i>
  <i>--allow-keywords \</i>
  <i>--flush-logs \</i>
  <i>--hex-blob \</i>
  <i>--master-data \</i>
  <i>--max_allowed_packet=16M \</i>
  <i>--quote-names \</i>
  <i>--result-file=BACKUP_MYSQL_4.0.SQL</i>
</pre>

<p>
Now a file named <path>BACKUP_MYSQL_4.0.SQL</path> should exist, which later can
be used to recreate your data. The data is described in the MySQL dialect of SQL,
the Structured Query Language.
</p>

<p>
Now would also be a good time to see if the backup you have created is working.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Upgrading from recent versions of MySQL</title>
<section>
<body>

<p>
If you have skipped step #1, you now have to create a backup package (of the
database server, not the data) of the currently installed version:
</p>

<pre caption="Binary package backup">
# <i>quickpkg dev-db/mysql</i>
</pre>

<p>
Now it's time to clean out the current version and all of its data:
</p>

<pre caption="Uninstall MySQL">
# <i>/etc/init.d/mysql stop</i>
# <i>emerge -C mysql</i>
# <i>tar -cjpvf ~/mysql.$(date +%F_%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i>
# <i>ls -l ~/mysql.*</i>
# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
</pre>

<note>
Now two different backups should exist: The SQL one, which is portable between
various versions of MySQL, and the other one that will allow you to quickly 
restore your database. This will be covered later in this doc in more detail.
</note>

<p>
After you got rid of your old MySQL installation, you can now install the new
version. Note that <c>revdep-rebuild</c> is necessary for rebuilding packages
linking against MySQL.
</p>

<pre caption="Upgrading the binaries">
# <i>emerge -av "&gt;mysql-4.1"</i>
# <i>dispatch-conf</i>
# <i>revdep-rebuild</i>
</pre>

<p>
Now configure the newly installed version of MySQL and restart the daemon:
</p>

<pre caption="Configure MySQL 4.1 base setup">
# <i>ebuild /var/db/pkg/dev-db/mysql-4.1.&lt;micro_version&gt;/mysql-4.1.&lt;micro_version&gt;.ebuild config</i>
# <i>/etc/init.d/mysql start</i>
</pre>

<p>
Finally you can import the backup you have created during step #2:
</p>

<pre caption="Importing the SQL backup">
# <i>cat BACKUP_MYSQL_4.0.SQL \</i>
     <i>| mysql \</i>
     <i>-uroot \</i>
     <i>-p$PASSWORD \</i>
     <i>-hlocalhost \</i>
     <i>--max_allowed_packet=16M</i>

# <i>mysql_fix_privilege_tables \</i>
     <i>--defaults-file=/etc/mysql/my.cnf \</i>
     <i>--user=root \</i>
     <i>--password=$PASSWORD</i>
</pre>

<p>
If you now restart your MySQL daemon and everything went as expected, you will
have a fully working version of 4.1.x! :-)
</p>

<pre caption="Restart the MySQL instance">
# <i>/etc/init.d/mysql restart</i>
</pre>

<p>
If you encountered any problems during the upgrade process, please report them
at our <uri link="https://bugs.gentoo.org">Bugzilla</uri>.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Recover the old installation of MySQL 4.0</title>
<section>
<body>

<p>
If you are not happy with MySQL 4.1, it's possible to go back to MySQL 4.0.
</p>

<pre caption="Back to the past">
# <i>/etc/init.d/mysql stop</i>
# <i>emerge -C mysql</i>
# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
# <i>emerge --usepkgonly "&lt;mysql-4.1"</i>
# <i>tar -xjpvf mysql.[tag] -C /</i>
# <i>/etc/init.d/mysql start</i>
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Straight upgrade, not supported, dangerous</title>
<section>
<body>

<p>
Under certain conditions it's possible to directly upgrade to the next major 
version of MySQL. If you know what you're doing and think that applies to your
case, here's a little trick that makes it possible to directly upgrade to 
MySQl 4.1.
</p>

<pre caption="Straight upgrade">
# <i>quickpkg dev-db/mysql</i>
# <i>/etc/init.d/mysql stop</i>
# <i>tar -cjpvf ~/mysql.$(date +%F_%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i>
# <i>ls -l ~/mysql.*</i>
# <i>export MYSQL_STRAIGHT_UPGRADE=1</i>
# <i>emerge -av "&gt;mysql-4.1"</i>
# <i>unset MYSQL_STRAIGHT_UPGRADE</i>
# <i>dispatch-conf</i>
# <i>revdep-rebuild</i>
# <i>/etc/init.d/mysql start</i>
# <i>mysql_fix_privilege_tables --defaults-file=/etc/mysql/my.cnf \</i>
     <i>-uroot --password=$PASSWORD</i>
# <i>mysql --database=mysql -uroot -p$PASSWORD &lt; /tmp/new_pieces.sql</i>
# <i>/etc/init.d/mysql restart</i> # just to be sure
</pre>

<p>
Good luck and if something fails, don't say we didn't warn you! ;-)
</p>

</body>
</section>
</chapter>

</guide>
1	rane	1.1	<?xml version='1.0' encoding="UTF-8"?>
2			<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	rane	1.3	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/mysql-upgrading.xml,v 1.2 2005/09/21 19:15:49 rane Exp $ -->
4	rane	1.1
5			<guide link="/doc/en/mysql-upgrading.xml">
6			<title>Upgrade guide to MySQL 4.1.x</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 4.1 can now be found in Gentoo's
17			unstable tree (~arch). As the team hopes that it soon will be able to stabilize
18			this ebuild, here's an upgrade path for all willing testers.
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	rane	1.3	<version>1.2</version>
26			<date>2005-10-17</date>
27	rane	1.1
28			<chapter>
29			<title>Upgrading from old versions of MySQL</title>
30			<section>
31			<body>
32
33			<p>
34			Users upgrading from an old version (<4.0.24) of MySQL will first have to
35			install MySQL 4.0.25. If you are already running a current version, you can skip
36			this section and continue with the next one.
37			</p>
38
39			<pre caption="Simple upgrade">
40			# <i>emerge -av --buildpkg "<mysql-4.1"</i>
41			</pre>
42
43			</body>
44			</section>
45			</chapter>
46
47			<chapter>
48			<title>Creating a backup of your current data</title>
49			<section>
50			<body>
51
52			<p>
53	rane	1.2	One of the most important tasks that every database administrator has to perfom
54			is backing up data. Here we go:
55	rane	1.1	</p>
56
57			<pre caption="Dump of all databases">
58			# <i>mysqldump \</i>
59			<i>-uroot \</i>
60			<i>-p$PASSWORD \</i>
61			<i>-hlocalhost \</i>
62			<i>--all-databases \</i>
63			<i>--all \</i>
64			<i>--opt \</i>
65			<i>--allow-keywords \</i>
66			<i>--flush-logs \</i>
67			<i>--hex-blob \</i>
68			<i>--master-data \</i>
69			<i>--max_allowed_packet=16M \</i>
70	rane	1.3	<i>--quote-names \</i>
71	rane	1.1	<i>--result-file=BACKUP_MYSQL_4.0.SQL</i>
72			</pre>
73
74			<p>
75	rane	1.2	Now a file named <path>BACKUP_MYSQL_4.0.SQL</path> should exist, which later can
76			be used to recreate your data. The data is described in the MySQL dialect of SQL,
77	rane	1.1	the Structured Query Language.
78			</p>
79
80			<p>
81	rane	1.2	Now would also be a good time to see if the backup you have created is working.
82	rane	1.1	</p>
83
84			</body>
85			</section>
86			</chapter>
87
88			<chapter>
89			<title>Upgrading from recent versions of MySQL</title>
90			<section>
91			<body>
92
93			<p>
94	rane	1.2	If you have skipped step #1, you now have to create a backup package (of the
95	rane	1.1	database server, not the data) of the currently installed version:
96			</p>
97
98			<pre caption="Binary package backup">
99			# <i>quickpkg dev-db/mysql</i>
100			</pre>
101
102			<p>
103	rane	1.2	Now it's time to clean out the current version and all of its data:
104	rane	1.1	</p>
105
106			<pre caption="Uninstall MySQL">
107			# <i>/etc/init.d/mysql stop</i>
108			# <i>emerge -C mysql</i>
109			# <i>tar -cjpvf ~/mysql.$(date +%F_%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i>
110			# <i>ls -l ~/mysql.*</i>
111			# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
112			</pre>
113
114			<note>
115	rane	1.2	Now two different backups should exist: The SQL one, which is portable between
116			various versions of MySQL, and the other one that will allow you to quickly
117			restore your database. This will be covered later in this doc in more detail.
118	rane	1.1	</note>
119
120			<p>
121			After you got rid of your old MySQL installation, you can now install the new
122			version. Note that <c>revdep-rebuild</c> is necessary for rebuilding packages
123			linking against MySQL.
124			</p>
125
126			<pre caption="Upgrading the binaries">
127			# <i>emerge -av ">mysql-4.1"</i>
128			# <i>dispatch-conf</i>
129			# <i>revdep-rebuild</i>
130			</pre>
131
132			<p>
133			Now configure the newly installed version of MySQL and restart the daemon:
134			</p>
135
136			<pre caption="Configure MySQL 4.1 base setup">
137			# <i>ebuild /var/db/pkg/dev-db/mysql-4.1.<micro_version>/mysql-4.1.<micro_version>.ebuild config</i>
138			# <i>/etc/init.d/mysql start</i>
139			</pre>
140
141			<p>
142			Finally you can import the backup you have created during step #2:
143			</p>
144
145			<pre caption="Importing the SQL backup">
146			# <i>cat BACKUP_MYSQL_4.0.SQL \</i>
147			<i>\| mysql \</i>
148			<i>-uroot \</i>
149			<i>-p$PASSWORD \</i>
150			<i>-hlocalhost \</i>
151			<i>--max_allowed_packet=16M</i>
152
153			# <i>mysql_fix_privilege_tables \</i>
154			<i>--defaults-file=/etc/mysql/my.cnf \</i>
155			<i>--user=root \</i>
156			<i>--password=$PASSWORD</i>
157			</pre>
158
159			<p>
160			If you now restart your MySQL daemon and everything went as expected, you will
161			have a fully working version of 4.1.x! :-)
162			</p>
163
164			<pre caption="Restart the MySQL instance">
165			# <i>/etc/init.d/mysql restart</i>
166			</pre>
167
168			<p>
169			If you encountered any problems during the upgrade process, please report them
170			at our <uri link="https://bugs.gentoo.org">Bugzilla</uri>.
171			</p>
172
173			</body>
174			</section>
175			</chapter>
176
177			<chapter>
178			<title>Recover the old installation of MySQL 4.0</title>
179			<section>
180			<body>
181
182			<p>
183	rane	1.2	If you are not happy with MySQL 4.1, it's possible to go back to MySQL 4.0.
184	rane	1.1	</p>
185
186			<pre caption="Back to the past">
187			# <i>/etc/init.d/mysql stop</i>
188			# <i>emerge -C mysql</i>
189			# <i>rm -rf /var/lib/mysql/ /var/log/mysql</i>
190			# <i>emerge --usepkgonly "<mysql-4.1"</i>
191	rane	1.2	# <i>tar -xjpvf mysql.[tag] -C /</i>
192	rane	1.1	# <i>/etc/init.d/mysql start</i>
193			</pre>
194
195			</body>
196			</section>
197			</chapter>
198
199			<chapter>
200			<title>Straight upgrade, not supported, dangerous</title>
201			<section>
202			<body>
203
204			<p>
205	rane	1.2	Under certain conditions it's possible to directly upgrade to the next major
206			version of MySQL. If you know what you're doing and think that applies to your
207			case, here's a little trick that makes it possible to directly upgrade to
208			MySQl 4.1.
209	rane	1.1	</p>
210
211			<pre caption="Straight upgrade">
212			# <i>quickpkg dev-db/mysql</i>
213			# <i>/etc/init.d/mysql stop</i>
214			# <i>tar -cjpvf ~/mysql.$(date +%F_%H-%M).tar.bz2 /etc/mysql/my.cnf /var/lib/mysql/</i>
215			# <i>ls -l ~/mysql.*</i>
216			# <i>export MYSQL_STRAIGHT_UPGRADE=1</i>
217			# <i>emerge -av ">mysql-4.1"</i>
218			# <i>unset MYSQL_STRAIGHT_UPGRADE</i>
219			# <i>dispatch-conf</i>
220			# <i>revdep-rebuild</i>
221			# <i>/etc/init.d/mysql start</i>
222			# <i>mysql_fix_privilege_tables --defaults-file=/etc/mysql/my.cnf \</i>
223			<i>-uroot --password=$PASSWORD</i>
224			# <i>mysql --database=mysql -uroot -p$PASSWORD < /tmp/new_pieces.sql</i>
225			# <i>/etc/init.d/mysql restart</i> # just to be sure
226			</pre>
227
228			<p>
229	rane	1.2	Good luck and if something fails, don't say we didn't warn you! ;-)
230	rane	1.1	</p>
231
232			</body>
233			</section>
234			</chapter>
235
236			</guide>