Chapter 5. Migration

This chapter provides information on migration from one version to another for specific components of Red Hat Software Collections 1.2.

5.1. Migrating from MySQL 5.1 to MySQL 5.5

5.1.1. Notable Differences Between MySQL 5.1 and MySQL 5.5

The following is a list of the most important changes between MySQL 5.1 and MySQL 5.5
  • Starting with MySQL 5.5, the InnoDB storage engine (formerly known as InnoDB Plugin) is the default storage engine.
  • InnoDB and some other plug-ins (for example, archive, blackhole and federated) were installable plug-ins in MySQL 5.1. Starting with MySQL 5.5, these plug-ins became compiled-in storage engines, that is, they cannot be installed or uninstalled by default.
  • If you used InnoDB Plugin and it was loaded using the plugin-load=innodb=ha_innodb_plugin.so configuration option, you need to remove this configuration option as it does not work in MySQL 5.5.
  • In MySQL 5.1, InnoDB Plugin included a configuration variable innodb_file_io_threads. However, this variable does not exist in MySQL 5.5; new variables, innodb_read_io_threads and innodb_write_io_threads, are used instead. To ensure proper functionality, either remove the former variable from the configuration file or replace it with the current variables.
  • When upgrading from MySQL 5.1 to MySQL 5.5 using the in-place upgrading method, the mysql.proxies_priv table will not exist. To create the missing table, the mysql_upgrade utility has to be run as soon as the new daemon is started.
  • MySQL 5.5 uses latin1 for the stopword file if the character_set_server variable is ucs2, utf16 or utf32. Thus, if the table uses FULLTEXT indexes in these cases, users should repair the table using the REPAIR TABLE table_name QUICK.
  • MySQL 5.1 used the language variable for specifying the directory which included the error message file. This option is now deprecated and has been replaced by the lc_messages_dir and lc_messages options. This also applies for configuration options. Also, error messages no longer contain mixed set of character sets and error messages are returned in the set following the character_set_results system variable instead. That is, some error messages can be different in MySQL 5.5.
Please note that the EXAMPLE plug-in is no longer distributed in Red Hat Software Collections packages.
For more information about MySQL 5.1 and MySQL 5.5, refer to the release notes available at http://dev.mysql.com/doc/relnotes/mysql/5.1/en/ and http://dev.mysql.com/doc/relnotes/mysql/5.5/en/.

Important

MariaDB is a community-developed drop-in replacement for MySQL. The differences between MySQL 5.1 and MySQL 5.5 are valid also for MySQL 5.1 and MariaDB 5.5.

5.1.2. Upgrading from MySQL 5.1 to MySQL 5.5

Before migrating from MySQL 5.1 to MySQL 5.5, back up all your data, including any MySQL databases. Because the mysql55 Software Collection does not conflict with the mysql packages from the core systems, it is possible to install the mysql55 Software Collection together with the mysql packages. It is also possible to run both versions at the same time, however, the port number and the socket in the my.cnf files need to be changed to prevent these specific resources from conflicting.
Upgrading can be performed either by using the mysqldump and mysqlimport utilities or using in-place upgrade:
  • In the first scenario, the whole dump of all databases from one database is generated, mysql is run with the dump file as an input, using mysqlimport or the LOAD DATA INFILE SQL command within the other database. At the same time, the appropriate daemons have to be running during both dumping and restoring. You can use the --all-databases option in the mysqldump call to include all databases in the dump. The --routines, --triggers and --events options can also be used if needed.
  • During the in-place upgrade, the data files are copied from one database directory to another database directory. The daemons should not be running at the time of copying. Set the appropriate permissions and SELinux context for copied files.
After upgrading, start the server and run the mysql_upgrade command. Running mysql_upgrade is necessary to check and repair internal tables.

Important

All scripts that work with a server form Software Collection, especially the mysql_upgrade script, should be run inside the scl enable environment.
In case the root user has a non-empty password defined (it should have it defined), it is necessary to call the mysql_upgrade utility with the -p option and specify the password.
The dump and restore upgrade method is recommended. The in-place upgrade method is usually faster, however, there are certain risks and known problems. For more information, refer to the MySQL 5.5 Release Notes.
In addition, once the upgrade is complete, consider changing the appropriate settings in the my.cnf file to reflect the environment.

Example 5.1. Dump and Restore Upgrade

~]# service mysqld start
Starting mysqld:                                           [  OK  ]
~]# mysqldump --all-databases --routines --events > dump.sql
~]# service mysqld stop
Stopping mysqld:                                           [  OK  ]
~]# service mysql55-mysqld start
Starting mysql55-mysqld:                                   [  OK  ]
~]# scl enable mysql55 'mysql' < dump.sql
~]# scl enable mysql55 'mysql_upgrade -u root -p'
Enter password:
Looking for 'mysql' as: mysql
Looking for 'mysqlcheck' as: mysqlcheck
Running 'mysqlcheck with default connection arguments
Running 'mysqlcheck with default connection arguments
a.t1                                               OK
mysql.columns_priv                                 OK
<skipped tables list>
mysql.user                                         OK
Running 'mysql_fix_privilege_tables'...
OK

Example 5.2. In-place Upgrade

~]# service mysqld stop
Stopping mysqld:                                           [  OK  ]
~]# service mysql55-mysqld stop
Stopping mysql55-mysqld:                                   [  OK  ]
~]# rm -rf /opt/rh/mysql55/root/var/lib/mysql/
~]# cp -r /var/lib/mysql/ /opt/rh/mysql55/root/var/lib/
~]# chown -R mysql:mysql /opt/rh/mysql55/root/var/lib/mysql/
~]# restorecon -R /opt/rh/mysql55/root/var/lib/mysql/
~]# service mysql55-mysqld start
Starting mysql55-mysqld:                                   [  OK  ]
~]# scl enable mysql55 'mysql_upgrade -u root -p'
Enter password:
Looking for 'mysql' as: mysql
Looking for 'mysqlcheck' as: mysqlcheck
Running 'mysqlcheck with default connection arguments
Running 'mysqlcheck with default connection arguments
a.t1                                               OK
mysql.columns_priv                                 OK
<skipped tables list>
mysql.user                                         OK
Running 'mysql_fix_privilege_tables'...
OK
For more information about the upgrading process, refer to MySQL 5.5 Reference Manual.

Important

MariaDB is a community-developed drop-in replacement for MySQL. The steps for upgrading from MySQL 5.1 to MySQL 5.5 are valid also for upgrading from MySQL 5.1 to MariaDB 5.5, with the exception of the following differences:
  • The mariadb55 component name should be used instead of the mysql55, so replace all occurrences of mysql55 with mariadb55.
  • The systemd unit name for MariaDB 5.5. is mariadb55-mariadb in Red Hat Enterprise Linux 7, while the SysV unit script for MariaDB 5.5 is called mariadb55-mysqld in Red Hat Enterprise Linux 6.

5.1.3. Using the mysql55-mysql-devel Package

Red Hat Software Collections contains the server part of MySQL 5.5 database. Red Hat Enterprise Linux 6 provides version 5.1 of this database (client library and server daemon). A protocol which is used between the client library and the daemon is stable across database versions, so using, for example, the MySQL 5.1 client library with the MySQL 5.5 daemon works as expected.

5.1.3.1. Using Database Connectors for Dynamic Languages

Important

When a MariaDB or MySQL database contains old users created using old authentication schema, PHP using the mysqlnd driver will not be able to connect to the database. This is because the old_password setting in the /etc/my.cnf file is turned off by default on Red Hat Enterprise Linux 6 while it is enabled on Red Hat Enterprise Linux 5. To work around this problem, set old_password to 0, restart the MariaDB or MySQL service and set a new password for each user.

5.1.3.2. Building Applications for MySQL 5.5 from Red Hat Software Collections

MySQL 5.5 from Red Hat Software Collections does not include database connectors; client libraries packaged in the MySQL 5.5 Red Hat Software Collections database packages are not supposed to be used as they are included only for purposes of server utilities and the daemon. Users are instead expected to use the system libraries and database connectors provided with the core system.
It means that users who would like to link their application against the MySQL client library should compile it and link it to the core Red Hat Enterprise Linux 6 environment, not to the MySQL 5.5 Red Hat Software Collections environment.
The only exception to this are server-side plug-ins, which are expected to be built under the MySQL 5.5 Red Hat Software Collections environment. This means the build process should be run inside the scl enable mysql55 '...' call.

5.2. Migrating from PostgreSQL 8.4 to PostgreSQL 9.2

Red Hat Software Collections 1.2 is distributed with PostgreSQL 9.2, which can be safely installed on the same machine in parallel with PostgreSQL 8.4 from Red Hat Enterprise Linux 6. It is also possible to run both versions of PostgreSQL on one machine at the same time, but you need to use different ports or IP addresses and adjust SELinux policy.

5.2.1. Notable Differences Between PostgreSQL 8.4 and PostgreSQL 9.2

The following is a list of the most important changes between PostgreSQL 8.4 and PostgreSQL 9.2:
  • The following server configuration parameters have been removed and are no longer supported: add_missing_from, regex_flavor, silent_mode, wal_sender_delay, and custom_variable_classes. Do not use any of these parameters in the new configuration file.
  • The unix_socket_directory parameter has been renamed to unix_socket_directories and can now be used to specify more than one UNIX socket to listen on. To do so, provide a list of comma-separated directories as the value of this option. The default value remains unchanged and is /tmp.
  • New configuration parameters ssl_ca_file, ssl_cert_file, ssl_crl_file, and ssl_key_file have been added. These configuration parameters can be used to specify the locations of server-side SSL files that were previously hard-coded as relative paths to the root.crt, server.crt, root.crl, and server.key files in the data directory.
    Note that the PostgreSQL server no longer reads the root.crt and root.crl files by default. To load these files, change the corresponding parameters to non-default values.
  • The => operator has been removed and users are now advised to use the hstore(text, text) function.
  • The default value of the standard_conforming_strings configuration parameter is now on. This configuration parameter controls if ordinary string literals (strings enclosed in single quotes) treat backslashes literally as specified in the SQL standard.
  • A new configuration parameter, backslash_quote, has been added. This configuration parameter can be used to control whether a single quotation mark can be represented by \' in string literals. The default value is safe_encoding, which permits the use of \' only when the client encoding does not allow ASCII backslashes in multi-byte characters. As a consequence, \' can now be interpreted differently only in specific cases and only in string literals that do not conform to standards, including escape string syntax, E'value'.
  • PostgreSQL 9.0 introduced access privileges for large objects. Consequently, a new configuration parameter, lo_compat_privileges, has been added to allow you to disable security checks related to the large objects affected by this change. To disable these security checks, change the value of this configuration parameter to on. The default value is off.
For a detailed list of known compatibility issues with earlier versions, see the official notes for PostgreSQL 9.0, PostgreSQL 9.1, and PostgreSQL 9.2. For an in-depth list of changes in behavior, see the upstream Release Notes.

5.2.2. Upgrading from PostgreSQL 8.4 to PostgreSQL 9.2

To migrate your data from PostgreSQL 8.4 that is distributed with Red Hat Enterprise Linux 6 to PostgreSQL 9.2 that is included in Red Hat Software Collections 1.2, you can either perform an in-place upgrade (recommended), or dump the database data into a text file with SQL commands and import it in the new database. Note that the second method is usually significantly slower and may require manual fixes; see the official documentation for more information about this upgrade method. If you need to migrate PosgreSQL databases to Red Hat Enterprise Linux 7, see https://access.redhat.com/articles/541873 and https://access.redhat.com/articles/694413.

Important

Before migrating your data from PostgreSQL 8.4 to PostgreSQL 9.2, make sure that you back up all your data, including the PostgreSQL database files that are by default located in the /var/lib/pgsql/data/ directory.

Procedure 5.1. Performing In-place Upgrade

To perform an in-place upgrade of your PostgreSQL server, complete the following steps:
  1. Stop the old PostgreSQL server to ensure that the data is not in an inconsistent state. To do so, type the following at a shell prompt as root:
    service postgresql stop
    To verify that the server is not running, type:
    service postgresql status
  2. Verify that the new data directory located in /opt/rh/postgresql92/root/var/lib/pgsql/data/ does not exist:
    file /opt/rh/postgresql92/root/var/lib/pgsql/data/
    If you are running a fresh installation of PostgreSQL 9.2, this directory should not be present in your system. If it is, back it up by running the following command as root:
    mv /opt/rh/postgresql92/root/var/lib/pgsql/data{,-scl-backup}
  3. Copy the old database data to the new location by typing the following at a shell prompt as root:
    cp -ra /var/lib/pgsql/data/ /opt/rh/postgresql92/root/var/lib/pgsql/
  4. Open the /opt/rh/postgresql92/root/var/lib/pgsql/data/pg_hba.conf configuration file and verify that the postgres user is allowed to connect to the PostgreSQL server from localhost without a password. If not, you can edit this file and temporarily set the authentication method for the postgres user to trust or ident. For a detailed description of the pg_hba.conf file and a complete list of available configuration options, see the official documentation.
  5. Upgrade the database data for the new server by running the following command as root:
    service postgresql92-postgresql upgrade
    It is recommended that you read the resulting /opt/rh/postgresql92/root/var/lib/pgsql/pgupgrade.log log file to see if there were any problems with the upgrade.
  6. Start the new server as root:
    service postgresql92-postgresql start
    It is also advised that you run the analyze_new_cluster.sh script as follows:
    su - postgres -c 'scl enable postgresql92 ~/analyze_new_cluster.sh'
  7. Optionally, you can configure the PostgreSQL 9.2 server to start automatically at boot time. To disable the old PostgreSQL 8.4 server, type the following command as root:
    chkconfig postgresql off
    To enable the PostgreSQL 9.2 server, type as root:
    chkconfig postgresql92-postgresql on

Procedure 5.2. Performing a Dump and Restore Upgrade

To perform a dump and restore upgrade of your PostgreSQL server, complete the following steps:
  1. Ensure that the old PostgreSQL server is running by typing the following at a shell prompt as root:
    service postgresql start
  2. Dump all data in the PostgreSQL database into a script file. As root, type:
    su - postgres -c 'pg_dumpall > ~/pgdump_file.sql'
  3. Stop the old server by running the following command as root:
    service postgresql stop
  4. Initialize the data directory for the new server as root:
    service postgresql92-postgresql initdb
  5. Start the new server as root:
    service postgresql92-postgresql start
  6. Import data from the previously created SQL file:
    su - postgres -c 'scl enable postgresql92 "psql -f ~/pgdump_file.sql postgres"'
  7. Optionally, you can configure the PostgreSQL 9.2 server to start automatically at boot time. To disable the old PostgreSQL 8.4 server, type the following command as root:
    chkconfig postgresql off
    To enable the PostgreSQL 9.2 server, type as root:
    chkconfig postgresql92-postgresql on
  8. If your configuration differs from the default one, make sure to update configuration files, especially the /opt/rh/postgresql92/root/var/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

5.3. Migrating from nginx 1.4 to nginx 1.6

In Red Hat Software Collections 1.2, nginx has been upgraded from version 1.4.4 to 1.6.1. The Software Collection has been renamed to nginx16 and it is now supported.
The nginx16 Software Collection uses a new prefix in accordance with the name of the collection and a different path to the root directory, which is now located in /opt/rh/nginx16/root/. The error log is now stored in /var/log/nginx16/error.log by default, and the initscript is called nginx16-nginx.
Configuration files in nginx 1.6 have the same format as in the previous version and they are compatible between version 1.4 and 1.6.

Important

Before upgrading from nginx 1.4 to nginx 1.6, back up all your data, including web pages and configuration files located in the /opt/rh/nginx14/root/ tree.
If you have made any specific changes, such as changing configuration files or setting up web applications, in the /opt/rh/nginx14/root/ tree, replicate those changes in the new /opt/rh/nginx16/root/ directory, too.
For the official nginx documentation, please refer to http://nginx.org/en/docs/.