MySQL, upgrade and switch to slotted guide

-This document cover how to upgrade to the latest version available. There are -currently three version of MySQL supported in portage: +This document covers how to upgrade to the latest avaliable MySQL version. +There are currently three versions of MySQL supported in portage:

@@ -38,20 +44,19 @@

-There are two additional version presently, but are currently unsupported -meaning that bug reports have very low priority any may lack functionalities. -The current document is not guaranteed to work with them. +There are two additional versions present, but are currently unsupported. +This means that bug reports have very low priority any may lack functionalities. +This document is not guaranteed to work with them.

3.23 ancient
3.23 deprecated
5.1 active development

-The present document will use mysql-4.0.26 as start point and -mysql-5.0.18-r30 as the target version. Replace any of these with your -own. +mysql-4.0.26 will be used as start point, and mysql-5.0.18-r30 as +the target version. Replace any of these versions with your own. @@ -60,18 +65,18 @@ -Install the new version +Installing The New Version

-This step require to (re)move some files from the running environment, so the -first thing to do is a backup of the running database server, still not the -data. Done that, it's possible to remove the conflicting files with the slotted -MySQL and install the new version side by side with the current one. +This step will require (re)moving some files from the running environment, so +the first thing to do is backup the running database server, not the data. Once +this is done, it's possible to remove the conflicting files with the slotted +MySQL, and install the new version side by side with the current one.

+ # quickpkg dev-db/mysql
 # rm -rf /usr/include/mysql /usr/bin/mysql_config
 # for tmpfile in  /usr/lib/*mysql* ; do
@@ -82,8 +87,8 @@
 
 
 
-Be sure to update the /etc/init.d/mysql startup script with
-etc-update or dispatch-conf.
+Be sure to run etc-update or dispatch-conf in order to update the
+/etc/init.d/mysql startup script.
 
 
 
@@ -91,23 +96,31 @@
 
 
 
-Copy the data to the newly installed server
+Copying The Data To The New Server
 
 
 
 
-Lets go to to dump the data, this will be imported in the new version of MySQL.
-We are going to use mysqldump from the slotted MySQL. Notice the
--500 suffix to the mysqldump program name, it's from the 5.0.x
-version.
+Now we'll go ahead and dump the data. This will be imported into the new
+version of MySQL. mysqldump will be used from the slotted
+MySQL. Notice the -500 suffix to the mysqldump program name. This
+indicates it's from the 5.0.x version.
 
 
+
+If you are upgrading between version revisions (ie. dev-db/mysql-5.0.18
+to dev-db/mysql-5.0.18-r30), you can simply stop the database, move from
+one datadir to the other, and restart the server. This allows you to skip this
+section entirely.
+
+
  # mysqldump-500 \
-  --defaults-file=/etc/mysql/my.cnf
-  -uroot \
-  --password='your_password' \
-  -hlocalhost \
+  --defaults-file=/etc/mysql/my.cnf \
+  --user=root \
+  (Replace 'your_password' with your MySQL root password)
+  --password='your_password' \
+  --host=localhost \
   --all-databases \
   --opt \
   --allow-keywords \
@@ -120,7 +133,7 @@
 
 
 
-Now a file named BACKUP_MYSQL_4.0.SQL exist which can be used to
+A file named BACKUP_MYSQL_4.0.SQL is created, which can be used to
 recreate your data. The data is described in the MySQL dialect of SQL, the
 Structured Query Language.
 
@@ -129,35 +142,35 @@
 Start the server without networking and user management and run the SQL script:
 
 
-+ # mv /etc/conf.d/mysql /etc/conf.d/mysql.orig
-# echo '
+# cat <<- EOF > /etc/conf.d/mysql
   NOCHECK=1
   DEBUG=3
   mysql_slot_500=(
     "skip-networking"
     "skip-grant-tables"
   )
-  ' > /etc/conf.d/mysql
+  EOF
 # /etc/init.d/mysql-500 start
 # mysql-500 --defaults-file=/etc/mysql-500/my.cnf < BACKUP_MYSQL_4.0.SQL
-# mv /etc/conf.d/mysql.orig /etc/conf.d/mysql
 # /etc/init.d/mysql-500 stop
+# mv /etc/conf.d/mysql.orig /etc/conf.d/mysql
 
 
 
-To convert the data to UTF-8 during this step you must remove
+To convert the data to UTF-8 during this step, you must remove
 --hex-blob from the mysqldump option, then filter the data through
-a converter like iconv. In most case this is done simply "piping" it like
-iconv -f ISO_8859-1 -t UTF8 BACKUP_MYSQL_4.0.SQL | mysql-500
---defaults-file=/etc/mysql-500/my.cnf. Also manual tweaking of the SQL file
-could be needed, depending on the structure and the data contained in it.
+a converter like iconv. In most cases this is done by simply "piping" it
+like so: iconv -f ISO_8859-1 -t UTF8 BACKUP_MYSQL_4.0.SQL | mysql-500
+--defaults-file=/etc/mysql-500/my.cnf. Manual adjustments of the SQL file
+could be required, depending on the structure and the data contained within.
 
 
 
 If there are applications still writing to the previous database, it's
-possible to setup a "Replication" relationship between the two databases,
-however this will not be covered here.
+possible to setup a "Replication" relationship between the two databases.
+However, this document will not be cover that procedure.
 
 
 
@@ -166,27 +179,28 @@
 
 
 
-Switch to the new server
+Migrating To The New Server
 
 
 
 
 If you need to be sure that applications are working with the newly installed
-server, please test them against it, quite every application has configuration
-settings to chose which port or socket to use to connect to the database
-server. Simply start the server on an alternate port (for example 3307) and tell
-your application or a test copy of it to connect with those parameters. Pay
-attention that most of them will try to use the parameters found in the
-[client] section of /etc/mysql/my.cnf config file.
+server, please test them against it. Quite often every application has 
+configuration settings to chose which port or socket to use for connecting to
+the database server. Simply start the server on an alternate port (for example
+3307) and tell your application, or a test copy of it, to connect with those 
+parameters. Please note that most applications will try to use the parameters
+found in the [client] section of /etc/mysql/my.cnf config file.
 
 
 
-When you're satisfied with the results, remove every testing setting, stop the
-old server and start the new one. Also make it the server that will start at
-next reboot.
+When you're satisfied with the results, remove every test setting, stop the
+old server and start the new one. Also, be sure to add
+/etc/init.d/mysql to the default runlevel, ensuring it starts at
+the next reboot.
 
 
-+ # rc-update del mysql default
 # rc-update add mysql-500 default
 # /etc/init.d/mysql stop
@@ -195,10 +209,10 @@
 
 
 Unmerge the old version, and make the new one the default. The unmerge command
-will be unable to remove some files, the ones moved in Backup old package and prepare
-installation. This is an intended behavior, and avoid breaking application
-linked to the old MySQL version.
+will be unable to remove some files, such as the ones moved in Backing up the older version and preparing the
+installation. This is an intended behavior, and meant to avoid breaking
+applications linked to the old MySQL version.
 
 
 @@ -207,10 +221,10 @@
 # cd /etc
 # mv mysql mysql.$(date +%F_%H-%M)
 # rm -rf /usr/lib/*.TMP
-# rm -rf /usr/lib/*.TMP
 # for i in /usr/lib/*mysql* ; do
-    readlink -f $i || [[ -L $i ]] && rm $i
+    [[ -z "$( readlink -f $i )" ]] && [[ -L $i ]] && rm $i
   done
+  (emerge app-admin/eselect-mysql if you haven't already)
 # eselect mysql list
 # eselect mysql set 1
 # eselect mysql show
@@ -222,14 +236,14 @@
 
 
 
-Rebuild applications
+Rebuilding Applications
 
 
 
 
-After you got rid of your old MySQL installation, you can now install the new
+After you remove your old MySQL installation, you can now install the new
 version. Note that revdep-rebuild from the app-portage/gentoolkit
-is necessary for rebuilding packages linking against MySQL.
+is necessary for rebuilding packages linked against MySQL.
 
 
 @@ -238,8 +252,9 @@
 
 
 
-Depending on which really is the old version libmysqlclient.so
-number may be 10, 12, 14 or 15, chose the one of the old package.
+Depending on the older MySQL version, the libmysqlclient.so
+version may be 10, 12, 14 or 15. Please choose version of the old
+package.
 
 
 
@@ -248,26 +263,27 @@
 
 
 
-Final touches
+Final Touches
 
 
 
 +(Replace all instances of 'your_password' with your MySQL root password)
 # mysql_fix_privilege_tables-500 \
      --defaults-file=/etc/mysql-500/my.cnf \
      --user=root \
-     --password='your_password'
-# mysql -uroot -p'your_password' mysql -e "FLUSH PRIVILEGES;"
-# for tbl in $( mysql --silent -uroot -p'your_password' -e 'USE mysql ; SHOW TABLES LIKE "help%";' )
+     --password='your_password'
+# mysql -uroot -p'your_password' mysql -e "FLUSH PRIVILEGES;"
+# for tbl in $( mysql --silent -uroot -p'your_password' -e 'USE mysql ; SHOW TABLES LIKE "help%";' )
   do
-    mysql -uroot -p'your_password' -e "use mysql ; TRUNCATE TABLE ${tbl};"
+    mysql -uroot -p'your_password' -e "use mysql ; TRUNCATE TABLE ${tbl};"
   done
-# mysql -uroot -p'your_password' mysql < /usr/share/mysql/fill_help_tables.sql
+# mysql -uroot -p'your_password' mysql < /usr/share/mysql/fill_help_tables.sql
 
 
 
-If you encountered any problems during the upgrade process, please report them
-at our Bugzilla.
+If you encounter any problems during the upgrade process, please report them
+to our Bugzilla.