| 1 |
jkt 06/01/30 15:56:12 |
| 2 |
|
| 3 |
Added: xml/htdocs/doc/en mysql-upgrade-slotted.xml |
| 4 |
Log: |
| 5 |
#120210, new howto about upgrading to the slotted MySQL |
| 6 |
|
| 7 |
Revision Changes Path |
| 8 |
1.1 xml/htdocs/doc/en/mysql-upgrade-slotted.xml |
| 9 |
|
| 10 |
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/mysql-upgrade-slotted.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo |
| 11 |
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/mysql-upgrade-slotted.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo |
| 12 |
|
| 13 |
Index: mysql-upgrade-slotted.xml |
| 14 |
=================================================================== |
| 15 |
<?xml version='1.0' encoding="UTF-8"?> |
| 16 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 17 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/mysql-upgrade-slotted.xml,v 1.1 2006/01/30 15:56:12 jkt Exp $ --> |
| 18 |
|
| 19 |
<guide link="/doc/en/mysql-upgrade-slotted.xml"> |
| 20 |
<title>Slotted MySQL Upgrade and Migration Guide</title> |
| 21 |
|
| 22 |
<author title="Author"> |
| 23 |
<mail link="vivo@g.o">Francesco Riosa</mail> |
| 24 |
</author> |
| 25 |
<author title="Editor"> |
| 26 |
<mail link="chriswhite@g.o">Chris White</mail> |
| 27 |
</author> |
| 28 |
<author title="Editor"> |
| 29 |
<mail link="jkt@g.o">Jan Kundrát</mail> |
| 30 |
</author> |
| 31 |
<author title="Editor"> |
| 32 |
<mail link="jackdark@×××××.com">Joshua Saddler</mail> |
| 33 |
</author> |
| 34 |
|
| 35 |
<abstract> |
| 36 |
This document describes the upgrade path to the new slotted MySQL. It strives to |
| 37 |
make the upgrade as painless and friendly as possible. |
| 38 |
</abstract> |
| 39 |
|
| 40 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
| 41 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
| 42 |
<license/> |
| 43 |
|
| 44 |
<version>1.0</version> |
| 45 |
<date>2006-01-29</date> |
| 46 |
|
| 47 |
<chapter> |
| 48 |
<title>Upgrading Older MySQL Versions</title> |
| 49 |
<section> |
| 50 |
<body> |
| 51 |
|
| 52 |
<p> |
| 53 |
This document covers how to upgrade to the latest available MySQL version. There |
| 54 |
are currently three versions of MySQL supported in Portage: |
| 55 |
</p> |
| 56 |
|
| 57 |
<ul> |
| 58 |
<li> |
| 59 |
5.0 follows upstream releases in the stable tree and actively maintained |
| 60 |
</li> |
| 61 |
<li> |
| 62 |
4.1 follows upstream releases by implementing major bugfixes and security |
| 63 |
fixes, but no new features are added |
| 64 |
</li> |
| 65 |
<li>4.0 contains security fixes only</li> |
| 66 |
</ul> |
| 67 |
|
| 68 |
<p> |
| 69 |
There are two additional versions present, but are currently unsupported. This |
| 70 |
means that they may lack certain functionalities, and bug reports have very low |
| 71 |
priority. This document is not guaranteed to work with the following versions: |
| 72 |
</p> |
| 73 |
|
| 74 |
<ul> |
| 75 |
<li>3.23 has been deprecated</li> |
| 76 |
<li>5.1 is currently under heavy development</li> |
| 77 |
</ul> |
| 78 |
|
| 79 |
<note> |
| 80 |
<c>mysql-4.0.26</c> will be used as the starting point, and |
| 81 |
<c>mysql-5.0.18-r30</c> as the target version. Replace any of these versions |
| 82 |
with your own. |
| 83 |
</note> |
| 84 |
|
| 85 |
</body> |
| 86 |
</section> |
| 87 |
</chapter> |
| 88 |
|
| 89 |
|
| 90 |
<chapter id="install_the_new_version"> |
| 91 |
<title>Installing the New Version</title> |
| 92 |
<section> |
| 93 |
<body> |
| 94 |
|
| 95 |
<p> |
| 96 |
This step will require (re)moving some files from the running environment, so |
| 97 |
the first thing to do is backup the running database <e>server</e>, not the |
| 98 |
data. Once this is done, it's possible to remove the conflicting files with the |
| 99 |
slotted MySQL, and install the new version side by side with the current one. |
| 100 |
</p> |
| 101 |
|
| 102 |
<pre caption="Backing up the older version and preparing the installation"> |
| 103 |
# <i>quickpkg dev-db/mysql</i> |
| 104 |
# <i>rm -rf /usr/include/mysql /usr/bin/mysql_config</i> |
| 105 |
# <i>for tmpfile in /usr/lib/*mysql* |
| 106 |
do |
| 107 |
mv "${tmpfile}" "${tmpfile}.TMP" |
| 108 |
ln -s "${tmpfile}.TMP" "${tmpfile}" |
| 109 |
done</i> |
| 110 |
# <i>emerge -av =dev-db/mysql-5.0.18-r30</i> |
| 111 |
</pre> |
| 112 |
|
| 113 |
<p> |
| 114 |
Be sure to run <c>etc-update</c> or <c>dispatch-conf</c> in order to update the |
| 115 |
<path>/etc/init.d/mysql</path> startup script. |
| 116 |
</p> |
| 117 |
|
| 118 |
</body> |
| 119 |
</section> |
| 120 |
</chapter> |
| 121 |
|
| 122 |
<chapter> |
| 123 |
<title>Copying Data to the New Server</title> |
| 124 |
<section> |
| 125 |
<body> |
| 126 |
|
| 127 |
<p> |
| 128 |
Now we'll go ahead and dump the data. This will be imported into the new version |
| 129 |
of MySQL. <c>mysqldump</c> will be used from the <b>slotted</b> MySQL. Notice |
| 130 |
the <c>-500</c> suffix to the <c>mysqldump</c> program name. This indicates it's |
| 131 |
from the <b>5.0</b>.x version. |
| 132 |
</p> |
| 133 |
|
| 134 |
<impo> |
| 135 |
If you are upgrading between version revisions (ie. <c>dev-db/mysql-5.0.18</c> |
| 136 |
to <c>dev-db/mysql-5.0.18-r30</c>), you can simply stop the database, move from |
| 137 |
one data directry to the other, and restart the server. This allows you to skip |
| 138 |
this section entirely. |
| 139 |
</impo> |
| 140 |
|
| 141 |
<pre caption="Dump of all databases"> |
| 142 |
# <i>mysqldump-500 \ |
| 143 |
--defaults-file=/etc/mysql/my.cnf \ |
| 144 |
--user=root \</i> |
| 145 |
<comment>(Replace 'your_password' with your MySQL root password)</comment> |
| 146 |
<i>--password='your_password' \ |
| 147 |
--host=localhost \ |
| 148 |
--all-databases \ |
| 149 |
--opt \ |
| 150 |
--allow-keywords \ |
| 151 |
--flush-logs \ |
| 152 |
--hex-blob \ |
| 153 |
--master-data \ |
| 154 |
--max_allowed_packet=16M \ |
| 155 |
--quote-names \ |
| 156 |
--result-file=BACKUP_MYSQL_4.0.SQL</i> |
| 157 |
</pre> |
| 158 |
|
| 159 |
<p> |
| 160 |
A file named <path>BACKUP_MYSQL_4.0.SQL</path> is created, which can be used to |
| 161 |
recreate your data. The data is described in the MySQL dialect of SQL, the |
| 162 |
Structured Query Language. |
| 163 |
</p> |
| 164 |
|
| 165 |
<p> |
| 166 |
Start the server without networking and user management and run the SQL script: |
| 167 |
</p> |
| 168 |
|
| 169 |
<pre caption="Loading the data"> |
| 170 |
# <i>mv /etc/conf.d/mysql /etc/conf.d/mysql.orig</i> |
| 171 |
# <i>cat <<- EOF > /etc/conf.d/mysql |
| 172 |
NOCHECK=1 |
| 173 |
DEBUG=3 |
| 174 |
mysql_slot_500=( |
| 175 |
"skip-networking" |
| 176 |
"skip-grant-tables" |
| 177 |
) |
| 178 |
EOF</i> |
| 179 |
# <i>/etc/init.d/mysql-500 start</i> |
| 180 |
# <i>mysql-500 --defaults-file=/etc/mysql-500/my.cnf < BACKUP_MYSQL_4.0.SQL</i> |
| 181 |
# <i>/etc/init.d/mysql-500 stop</i> |
| 182 |
# <i>mv /etc/conf.d/mysql.orig /etc/conf.d/mysql</i> |
| 183 |
</pre> |
| 184 |
|
| 185 |
<note> |
| 186 |
To convert the data to UTF-8 during this step, you <e>must</e> remove |
| 187 |
<c>--hex-blob</c> from the <c>mysqldump</c> option, then filter the data through |
| 188 |
a converter like <c>iconv</c>. In most cases this is done by simply "piping" it |
| 189 |
like so: <c>iconv -f ISO_8859-1 -t UTF8 BACKUP_MYSQL_4.0.SQL | mysql-500 |
| 190 |
--defaults-file=/etc/mysql-500/my.cnf</c>. Manual adjustments of the SQL file |
| 191 |
could be required, depending on the structure and the data contained within. |
| 192 |
</note> |
| 193 |
|
| 194 |
<p> |
| 195 |
If there are applications still <e>writing</e> to the previous database, it's |
| 196 |
possible to setup a "Replication" relationship between the two databases. |
| 197 |
However, this document does not cover that procedure. |
| 198 |
</p> |
| 199 |
|
| 200 |
</body> |
| 201 |
</section> |
| 202 |
</chapter> |
| 203 |
|
| 204 |
<chapter> |
| 205 |
<title>Migrating to the New Server</title> |
| 206 |
<section> |
| 207 |
<body> |
| 208 |
|
| 209 |
<p> |
| 210 |
Please test applications against the newly installed server to make sure they |
| 211 |
work with it. Quite often every application has configuration settings to choose |
| 212 |
which port or socket to use for connecting to the database server. Simply start |
| 213 |
the server on an alternate port (for example 3307) and tell your application (or |
| 214 |
a test copy of it) to connect with those parameters. Please note that most |
| 215 |
applications will try to use the parameters found in the <c>[client]</c> section |
| 216 |
of <path>/etc/mysql/my.cnf</path> config file. |
| 217 |
</p> |
| 218 |
|
| 219 |
<p> |
| 220 |
When you're satisfied with the results, remove every test setting, stop the old |
| 221 |
server and start the new one. Also, be sure to add |
| 222 |
<path>/etc/init.d/mysql</path> to the default runlevel, ensuring it starts at |
| 223 |
the next reboot. |
| 224 |
</p> |
| 225 |
|
| 226 |
<pre caption="Using the new server"> |
| 227 |
# <i>rc-update del mysql default</i> |
| 228 |
# <i>rc-update add mysql-500 default</i> |
| 229 |
# <i>/etc/init.d/mysql stop</i> |
| 230 |
# <i>/etc/init.d/mysql-500 start</i> |
| 231 |
</pre> |
| 232 |
|
| 233 |
<p> |
| 234 |
Next, unmerge the old version and make the new one the default. The unmerge |
| 235 |
command will be unable to remove some files, such as the ones moved in <uri |
| 236 |
link="#install_the_new_version">Code Listing 2.1</uri>. This is an intended |
| 237 |
behavior, and is meant to avoid breaking applications linked to the old MySQL |
| 238 |
version. |
| 239 |
</p> |
| 240 |
|
| 241 |
<pre caption="Cleanup the old version"> |
| 242 |
# <i>emerge --unmerge --pretend mysql</i> |
| 243 |
# <i>emerge --unmerge =dev-db/mysql-4.0.26</i> |
| 244 |
# <i>cd /etc</i> |
| 245 |
# <i>mv mysql mysql.$(date +%F_%H-%M)</i> |
| 246 |
# <i>rm -rf /usr/lib/*.TMP</i> |
| 247 |
# <i>for i in /usr/lib/*mysql* |
| 248 |
do |
| 249 |
[[ -z "$( readlink -f $i )" ]] && [[ -L $i ]] && rm $i |
| 250 |
done</i> |
| 251 |
|
| 252 |
<comment>(emerge app-admin/eselect-mysql if you haven't already)</comment> |
| 253 |
# <i>eselect mysql list</i> |
| 254 |
# <i>eselect mysql set 1</i> |
| 255 |
# <i>eselect mysql show</i> |
| 256 |
</pre> |
| 257 |
|
| 258 |
</body> |
| 259 |
</section> |
| 260 |
</chapter> |
| 261 |
|
| 262 |
<chapter> |
| 263 |
<title>Rebuilding Applications</title> |
| 264 |
<section> |
| 265 |
<body> |
| 266 |
|
| 267 |
<p> |
| 268 |
After you remove your old MySQL installation, you can install the new version. |
| 269 |
Note that <c>revdep-rebuild</c> from <c>app-portage/gentoolkit</c> is necessary |
| 270 |
for rebuilding packages linked against MySQL. |
| 271 |
</p> |
| 272 |
|
| 273 |
<pre caption="Rebuilding reverse dependancies"> |
| 274 |
# <i>revdep-rebuild --soname libmysqlclient.so.12 -- -p -v</i> |
| 275 |
# <i>revdep-rebuild --soname libmysqlclient.so.12</i> |
| 276 |
</pre> |
| 277 |
|
| 278 |
<note> |
| 279 |
Depending on the older MySQL version, the <path>libmysqlclient.so</path> version |
| 280 |
may be <c>10</c>, <c>12</c>, <c>14</c> or <c>15</c>. Please choose the correct |
| 281 |
version of the <e>old</e> package. |
| 282 |
</note> |
| 283 |
|
| 284 |
</body> |
| 285 |
</section> |
| 286 |
</chapter> |
| 287 |
|
| 288 |
<chapter> |
| 289 |
<title>Final Touches</title> |
| 290 |
<section> |
| 291 |
<body> |
| 292 |
|
| 293 |
<pre caption="Upgrading the user database"> |
| 294 |
<comment>(Replace all instances of 'your_password' with your MySQL root password)</comment> |
| 295 |
# <i>mysql_fix_privilege_tables-500 \ |
| 296 |
--defaults-file=/etc/mysql-500/my.cnf \ |
| 297 |
--user=root \ |
| 298 |
--password='your_password'</i> |
| 299 |
# <i>mysql -uroot -p'your_password' mysql -e "FLUSH PRIVILEGES;"</i> |
| 300 |
# <i>for tbl in $( mysql --silent -uroot -p'your_password' -e 'USE mysql ; SHOW TABLES LIKE "help%";' ) |
| 301 |
do |
| 302 |
mysql -uroot -p'your_password' -e "use mysql ; TRUNCATE TABLE ${tbl};" |
| 303 |
done</i> |
| 304 |
# <i>mysql -uroot -p'your_password' mysql < /usr/share/mysql/fill_help_tables.sql</i> |
| 305 |
</pre> |
| 306 |
|
| 307 |
<p> |
| 308 |
If you encounter any problems during the upgrade process, please file a <uri |
| 309 |
link="https://bugs.gentoo.org">bug report</uri>. |
| 310 |
</p> |
| 311 |
|
| 312 |
</body> |
| 313 |
</section> |
| 314 |
</chapter> |
| 315 |
|
| 316 |
</guide> |
| 317 |
|
| 318 |
|
| 319 |
|
| 320 |
-- |
| 321 |
gentoo-doc-cvs@g.o mailing list |
Archives