Chapter 5. Migration

1. Stop the rh-mariadb102 database server if it is still running.
   Before stopping the server, set the innodb_fast_shutdown option to 0, so that InnoDB performs a slow shutdown, including a full purge and insert buffer merge. Read more about this option in the upstream documentation. This operation can take a longer time than in case of a normal shutdown.

   mysql -uroot -p -e "SET GLOBAL innodb_fast_shutdown = 0"

   Stop the rh-mariadb102 server.

   systemctl stop rh-mariadb102-mariadb.service

2. Install the rh-mariadb103 Software Collection, including the subpackage providing the mysql_upgrade utility.

   yum install rh-mariadb103-mariadb-server rh-mariadb103-mariadb-server-utils

   Note that it is possible to install the rh-mariadb103 Software Collection while the rh-mariadb102 Software Collection is still installed because these Collections do not conflict.
3. Inspect configuration of rh-mariadb103, which is stored in the /etc/opt/rh/rh-mariadb103/my.cnf file and the /etc/opt/rh/rh-mariadb103/my.cnf.d/ directory. Compare it with configuration of rh-mariadb102 stored in /etc/opt/rh/rh-mariadb102/my.cnf and /etc/opt/rh/rh-mariadb102/my.cnf.d/ and adjust it if necessary.
4. All data of the rh-mariadb102 Software Collection is stored in the /var/opt/rh/rh-mariadb102/lib/mysql/ directory unless configured differently. Copy the whole content of this directory to /var/opt/rh/rh-mariadb103/lib/mysql/. You can move the content but remember to back up your data before you continue to upgrade. Make sure the data are owned by the mysql user and SELinux context is correct.
5. Start the rh-mariadb103 database server.

   systemctl start rh-mariadb103-mariadb.service

6. Perform the data migration. Note that running the mysql_upgrade command is required due to upstream changes introduced in MDEV-14637.

   scl enable rh-mariadb103 mysql_upgrade

   If the root user has a non-empty password defined (it should have a password defined), it is necessary to call the mysql_upgrade utility with the -p option and specify the password.

   scl enable rh-mariadb103 -- mysql_upgrade -p

   Note that when the rh-mariadb103*-syspaths packages are installed, the scl enable command is not required. However, the *-syspaths packages conflict with the corresponding packages from the base Red Hat Enterprise Linux system and from the rh-mariadb102 and rh-mysql80 Software Collections.

1. Stop the rh-mariadb101 database server if it is still running.
   Before stopping the server, set the innodb_fast_shutdown option to 0, so that InnoDB performs a slow shutdown, including a full purge and insert buffer merge. Read more about this option in the upstream documentation. This operation can take a longer time than in case of a normal shutdown.

   mysql -uroot -p -e "SET GLOBAL innodb_fast_shutdown = 0"

   Stop the rh-mariadb101 server.

   service rh-mariadb101-mariadb stop

2. Install the rh-mariadb102 Software Collection.

   yum install rh-mariadb102-mariadb-server

   Note that it is possible to install the rh-mariadb102 Software Collection while the rh-mariadb101 Software Collection is still installed because these Collections do not conflict.
3. Inspect configuration of rh-mariadb102, which is stored in the /etc/opt/rh/rh-mariadb102/my.cnf file and the /etc/opt/rh/rh-mariadb102/my.cnf.d/ directory. Compare it with configuration of rh-mariadb101 stored in /etc/opt/rh/rh-mariadb101/my.cnf and /etc/opt/rh/rh-mariadb101/my.cnf.d/ and adjust it if necessary.
4. All data of the rh-mariadb101 Software Collection is stored in the /var/opt/rh/rh-mariadb101/lib/mysql/ directory unless configured differently. Copy the whole content of this directory to /var/opt/rh/rh-mariadb102/lib/mysql/. You can move the content but remember to back up your data before you continue to upgrade. Make sure the data are owned by the mysql user and SELinux context is correct.
5. Start the rh-mariadb102 database server.

   service rh-mariadb102-mariadb start

6. Perform the data migration.

   scl enable rh-mariadb102 mysql_upgrade

   If the root user has a non-empty password defined (it should have a password defined), it is necessary to call the mysql_upgrade utility with the -p option and specify the password.

   scl enable rh-mariadb102 -- mysql_upgrade -p

   Note that when the rh-mariadb102*-syspaths packages are installed, the scl enable command is not required. However, the *-syspaths packages conflict with the corresponding packages from the base Red Hat Enterprise Linux system and from the rh-mysql80 Software Collection.

1. Install the rh-mysql80 Software Collection.

   yum install rh-mysql80-mysql-server

2. Inspect the configuration of rh-mysql80, which is stored in the /etc/opt/rh/rh-mysql80/my.cnf file and the /etc/opt/rh/rh-mysql80/my.cnf.d/ directory. Compare it with the configuration of rh-mysql57 stored in /etc/opt/rh/rh-mysql57/my.cnf and /etc/opt/rh/rh-mysql57/my.cnf.d/ and adjust it if necessary.
3. Stop the rh-mysql57 database server, if it is still running.

   systemctl stop rh-mysql57-mysqld.service

4. All data of the rh-mysql57 Software Collection is stored in the /var/opt/rh/rh-mysql57/lib/mysql/ directory. Copy the whole content of this directory to /var/opt/rh/rh-mysql80/lib/mysql/. You can also move the content but remember to back up your data before you continue to upgrade.
5. Start the rh-mysql80 database server.

   systemctl start rh-mysql80-mysqld.service

6. Perform the data migration.

   scl enable rh-mysql80 mysql_upgrade

   If the root user has a non-empty password defined (it should have a password defined), it is necessary to call the mysql_upgrade utility with the -p option and specify the password.

   scl enable rh-mysql80 -- mysql_upgrade -p

   Note that when the rh-mysql80*-syspaths packages are installed, the scl enable command is not required. However, the *-syspaths packages conflict with the corresponding packages from the base Red Hat Enterprise Linux system and from the rh-mariadb102 and rh-mariadb103 Software Collections.

1. Install the rh-mysql57 Software Collection.

   yum install rh-mysql57-mysql-server

2. Inspect the configuration of rh-mysql57, which is stored in the /etc/opt/rh/rh-mysql57/my.cnf file and the /etc/opt/rh/rh-mysql57/my.cnf.d/ directory. Compare it with the configuration of rh-mysql56 stored in /etc/opt/rh/rh-mysql56/my.cnf and /etc/opt/rh/rh-mysql56/my.cnf.d/ and adjust it if necessary.
3. Stop the rh-mysql56 database server, if it is still running.

   service rh-mysql56-mysqld stop

4. All data of the rh-mysql56 Software Collection is stored in the /var/opt/rh/rh-mysql56/lib/mysql/ directory. Copy the whole content of this directory to /var/opt/rh/rh-mysql57/lib/mysql/. You can also move the content but remember to back up your data before you continue to upgrade.
5. Start the rh-mysql57 database server.

   service rh-mysql57-mysqld start

6. Perform the data migration.

   scl enable rh-mysql57 mysql_upgrade

   If the root user has a non-empty password defined (it should have a password defined), it is necessary to call the mysql_upgrade utility with the -p option and specify the password.

   scl enable rh-mysql57 -- mysql_upgrade -p

1. To be able to upgrade, the rh-mongodb34 instance must have featureCompatibilityVersion set to 3.4. Check featureCompatibilityVersion:

   ~]$ scl enable rh-mongodb34 'mongo --host localhost --port 27017 admin' --eval 'db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1})'

   If the mongod server is configured with enabled access control, add the --username and --password options to the mongo command.
2. Install the MongoDB servers and shells from the rh-mongodb36 Software Collections:

   ~]# yum install rh-mongodb36

3. Stop the MongoDB 3.4 server:

   ~]# systemctl stop rh-mongodb34-mongod.service

4. Copy your data to the new location:

   ~]# cp -a /var/opt/rh/rh-mongodb34/lib/mongodb/* /var/opt/rh/rh-mongodb36/lib/mongodb/

5. Configure the rh-mongodb36-mongod daemon in the /etc/opt/rh/rh-mongodb36/mongod.conf file.
6. Start the MongoDB 3.6 server:

   ~]# systemctl start rh-mongodb36-mongod.service

7. Enable backwards incompatible features:

   ~]$ scl enable rh-mongodb36 'mongo --host localhost --port 27017 admin' --eval 'db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } )'

   If the mongod server is configured with enabled access control, add the --username and --password options to the mongo command.

   Note

   After upgrading, it is recommended to run the deployment first without enabling the backwards incompatible features for a burn-in period of time, to minimize the likelihood of a downgrade.

1. Install the MongoDB servers and shells from the rh-mongodb34 Software Collections:

   ~]# yum install rh-mongodb34

2. Stop the MongoDB 3.2 server:

   ~]# systemctl stop rh-mongodb32-mongod.service

   Use the service rh-mongodb32-mongodb stop command on a Red Hat Enterprise Linux 6 system.
3. Copy your data to the new location:

   ~]# cp -a /var/opt/rh/rh-mongodb32/lib/mongodb/* /var/opt/rh/rh-mongodb34/lib/mongodb/

4. Configure the rh-mongodb34-mongod daemon in the /etc/opt/rh/rh-mongodb34/mongod.conf file.
5. Start the MongoDB 3.4 server:

   ~]# systemctl start rh-mongodb34-mongod.service

   On Red Hat Enterprise Linux 6, use the service rh-mongodb34-mongodb start command instead.
6. Enable backwards-incompatible features:

   ~]$ scl enable rh-mongodb34 'mongo --host localhost --port 27017 admin' --eval 'db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } )'

   If the mongod server is configured with enabled access control, add the --username and --password options to mongo command.
   Note that it is recommended to run the deployment after the upgrade without enabling these features first.

Procedure 5.1. Fast Upgrade Using the pg_upgrade Tool

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:

   systemctl stop postgresql.service

   To verify that the server is not running, type:

   systemctl status postgresql.service

2. Verify that the old directory /var/lib/pgsql/data/ exists:

   file /var/lib/pgsql/data/

   and back up your data.
3. Verify that the new data directory /var/opt/rh/rh-postgresql10/lib/pgsql/data/ does not exist:

   file /var/opt/rh/rh-postgresql10/lib/pgsql/data/

   If you are running a fresh installation of PostgreSQL 10, this directory should not be present in your system. If it is, back it up by running the following command as root:

   mv /var/opt/rh/rh-postgresql10/lib/pgsql/data{,-scl-backup}

4. Upgrade the database data for the new server by running the following command as root:

   scl enable rh-postgresql10 -- postgresql-setup --upgrade

   Alternatively, you can use the /opt/rh/rh-postgresql10/root/usr/bin/postgresql-setup --upgrade command.
   Note that you can use the --upgrade-from option for upgrade from different versions of PostgreSQL. The list of possible upgrade scenarios is available using the --upgrade-ids option.
   It is recommended that you read the resulting /var/lib/pgsql/upgrade_rh-postgresql10-postgresql.log log file to find out if any problems occurred during the upgrade.
5. Start the new server as root:

   systemctl start rh-postgresql10-postgresql.service

   It is also advised that you run the analyze_new_cluster.sh script as follows:

   su - postgres -c 'scl enable rh-postgresql10 ~/analyze_new_cluster.sh'

6. Optionally, you can configure the PostgreSQL 10 server to start automatically at boot time. To disable the old system PostgreSQL server, type the following command as root:

   chkconfig postgresql off

   To enable the PostgreSQL 10 server, type as root:

   chkconfig rh-postgresql10-postgresql on

7. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql10/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

Procedure 5.2. Performing a Dump and Restore Upgrade

1. Ensure that the old PostgreSQL server is running by typing the following at a shell prompt as root:

   systemctl start postgresql.service

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:

   systemctl stop postgresql.service

4. Initialize the data directory for the new server as root:

   scl enable rh-postgresql10-postgresql -- postgresql-setup --initdb

5. Start the new server as root:

   systemctl start rh-postgresql10-postgresql.service

6. Import data from the previously created SQL file:

   su - postgres -c 'scl enable rh-postgresql10 "psql -f ~/pgdump_file.sql postgres"'

7. Optionally, you can configure the PostgreSQL 10 server to start automatically at boot time. To disable the old system PostgreSQL server, type the following command as root:

   chkconfig postgresql off

   To enable the PostgreSQL 10 server, type as root:

   chkconfig rh-postgresql10-postgresql on

8. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql10/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

Procedure 5.3. Fast Upgrade Using the pg_upgrade Tool

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:

   systemctl stop rh-postgresql96-postgresql.service

   To verify that the server is not running, type:

   systemctl status rh-postgresql96-postgresql.service

2. Verify that the old directory /var/opt/rh/rh-postgresql96/lib/pgsql/data/ exists:

   file /var/opt/rh/rh-postgresql96/lib/pgsql/data/

   and back up your data.
3. Verify that the new data directory /var/opt/rh/rh-postgresql10/lib/pgsql/data/ does not exist:

   file /var/opt/rh/rh-postgresql10/lib/pgsql/data/

   If you are running a fresh installation of PostgreSQL 10, this directory should not be present in your system. If it is, back it up by running the following command as root:

   mv /var/opt/rh/rh-postgresql10/lib/pgsql/data{,-scl-backup}

4. Upgrade the database data for the new server by running the following command as root:

   scl enable rh-postgresql10 -- postgresql-setup --upgrade --upgrade-from=rh-postgresql96-postgresql

   Alternatively, you can use the /opt/rh/rh-postgresql10/root/usr/bin/postgresql-setup --upgrade --upgrade-from=rh-postgresql96-postgresql command.
   Note that you can use the --upgrade-from option for upgrading from different versions of PostgreSQL. The list of possible upgrade scenarios is available using the --upgrade-ids option.
   It is recommended that you read the resulting /var/lib/pgsql/upgrade_rh-postgresql10-postgresql.log log file to find out if any problems occurred during the upgrade.
5. Start the new server as root:

   systemctl start rh-postgresql10-postgresql.service

   It is also advised that you run the analyze_new_cluster.sh script as follows:

   su - postgres -c 'scl enable rh-postgresql10 ~/analyze_new_cluster.sh'

6. Optionally, you can configure the PostgreSQL 10 server to start automatically at boot time. To disable the old PostgreSQL 9.6 server, type the following command as root:

   chkconfig rh-postgresql96-postgreqsql off

   To enable the PostgreSQL 10 server, type as root:

   chkconfig rh-postgresql10-postgresql on

7. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql10/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

Procedure 5.4. Performing a Dump and Restore Upgrade

1. Ensure that the old PostgreSQL server is running by typing the following at a shell prompt as root:

   systemctl start rh-postgresql96-postgresql.service

2. Dump all data in the PostgreSQL database into a script file. As root, type:

   su - postgres -c 'scl enable rh-postgresql96 "pg_dumpall > ~/pgdump_file.sql"'

3. Stop the old server by running the following command as root:

   systemctl stop rh-postgresql96-postgresql.service

4. Initialize the data directory for the new server as root:

   scl enable rh-postgresql10-postgresql -- postgresql-setup --initdb

5. Start the new server as root:

   systemctl start rh-postgresql10-postgresql.service

6. Import data from the previously created SQL file:

   su - postgres -c 'scl enable rh-postgresql10 "psql -f ~/pgdump_file.sql postgres"'

7. Optionally, you can configure the PostgreSQL 10 server to start automatically at boot time. To disable the old PostgreSQL 9.6 server, type the following command as root:

   chkconfig rh-postgresql96-postgresql off

   To enable the PostgreSQL 10 server, type as root:

   chkconfig rh-postgresql10-postgresql on

8. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql10/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

Procedure 5.5. Fast Upgrade Using the pg_upgrade Tool

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 old directory /var/lib/pgsql/data/ exists:

   file /var/lib/pgsql/data/

   and back up your data.
3. Verify that the new data directory /var/opt/rh/rh-postgresql96/lib/pgsql/data/ does not exist:

   file /var/opt/rh/rh-postgresql96/lib/pgsql/data/

   If you are running a fresh installation of PostgreSQL 9.6, this directory should not be present in your system. If it is, back it up by running the following command as root:

   mv /var/opt/rh/rh-postgresql96/lib/pgsql/data{,-scl-backup}

4. Upgrade the database data for the new server by running the following command as root:

   scl enable rh-postgresql96 -- postgresql-setup --upgrade

   Alternatively, you can use the /opt/rh/rh-postgresql96/root/usr/bin/postgresql-setup --upgrade command.
   Note that you can use the --upgrade-from option for upgrade from different versions of PostgreSQL. The list of possible upgrade scenarios is available using the --upgrade-ids option.
   It is recommended that you read the resulting /var/lib/pgsql/upgrade_rh-postgresql96-postgresql.log log file to find out if any problems occurred during the upgrade.
5. Start the new server as root:

   service rh-postgresql96-postgresql start

   It is also advised that you run the analyze_new_cluster.sh script as follows:

   su - postgres -c 'scl enable rh-postgresql96 ~/analyze_new_cluster.sh'

6. Optionally, you can configure the PostgreSQL 9.6 server to start automatically at boot time. To disable the old system PostgreSQL server, type the following command as root:

   chkconfig postgresql off

   To enable the PostgreSQL 9.6 server, type as root:

   chkconfig rh-postgresql96-postgresql on

7. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql96/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

Procedure 5.6. Performing a Dump and Restore Upgrade

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:

   scl enable rh-postgresql96-postgresql -- postgresql-setup --initdb

5. Start the new server as root:

   service rh-postgresql96-postgresql start

6. Import data from the previously created SQL file:

   su - postgres -c 'scl enable rh-postgresql96 "psql -f ~/pgdump_file.sql postgres"'

7. Optionally, you can configure the PostgreSQL 9.6 server to start automatically at boot time. To disable the old system PostgreSQL server, type the following command as root:

   chkconfig postgresql off

   To enable the PostgreSQL 9.6 server, type as root:

   chkconfig rh-postgresql96-postgresql on

8. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql96/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

Procedure 5.7. Fast Upgrade Using the pg_upgrade Tool

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 rh-postgresql95-postgresql stop

   To verify that the server is not running, type:

   service rh-postgresql95-postgresql status

2. Verify that the old directory /var/opt/rh/rh-postgresql95/lib/pgsql/data/ exists:

   file /var/opt/rh/rh-postgresql95/lib/pgsql/data/

   and back up your data.
3. Verify that the new data directory /var/opt/rh/rh-postgresql96/lib/pgsql/data/ does not exist:

   file /var/opt/rh/rh-postgresql96/lib/pgsql/data/

   If you are running a fresh installation of PostgreSQL 9.6, this directory should not be present in your system. If it is, back it up by running the following command as root:

   mv /var/opt/rh/rh-postgresql96/lib/pgsql/data{,-scl-backup}

4. Upgrade the database data for the new server by running the following command as root:

   scl enable rh-postgresql96 -- postgresql-setup --upgrade --upgrade-from=rh-postgresql95-postgresql

   Alternatively, you can use the /opt/rh/rh-postgresql96/root/usr/bin/postgresql-setup --upgrade --upgrade-from=rh-postgresql95-postgresql command.
   Note that you can use the --upgrade-from option for upgrading from different versions of PostgreSQL. The list of possible upgrade scenarios is available using the --upgrade-ids option.
   It is recommended that you read the resulting /var/lib/pgsql/upgrade_rh-postgresql96-postgresql.log log file to find out if any problems occurred during the upgrade.
5. Start the new server as root:

   service rh-postgresql96-postgresql start

   It is also advised that you run the analyze_new_cluster.sh script as follows:

   su - postgres -c 'scl enable rh-postgresql96 ~/analyze_new_cluster.sh'

6. Optionally, you can configure the PostgreSQL 9.6 server to start automatically at boot time. To disable the old PostgreSQL 9.5 server, type the following command as root:

   chkconfig rh-postgresql95-postgreqsql off

   To enable the PostgreSQL 9.6 server, type as root:

   chkconfig rh-postgresql96-postgresql on

7. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql96/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.

Procedure 5.8. Performing a Dump and Restore Upgrade

1. Ensure that the old PostgreSQL server is running by typing the following at a shell prompt as root:

   service rh-postgresql95-postgresql start

2. Dump all data in the PostgreSQL database into a script file. As root, type:

   su - postgres -c 'scl enable rh-postgresql95 "pg_dumpall > ~/pgdump_file.sql"'

3. Stop the old server by running the following command as root:

   service rh-postgresql95-postgresql stop

4. Initialize the data directory for the new server as root:

   scl enable rh-postgresql96-postgresql -- postgresql-setup --initdb

5. Start the new server as root:

   service rh-postgresql96-postgresql start

6. Import data from the previously created SQL file:

   su - postgres -c 'scl enable rh-postgresql96 "psql -f ~/pgdump_file.sql postgres"'

7. Optionally, you can configure the PostgreSQL 9.6 server to start automatically at boot time. To disable the old PostgreSQL 9.5 server, type the following command as root:

   chkconfig rh-postgresql95-postgresql off

   To enable the PostgreSQL 9.6 server, type as root:

   chkconfig rh-postgresql96-postgresql on

8. If your configuration differs from the default one, make sure to update configuration files, especially the /var/opt/rh/rh-postgresql96/lib/pgsql/data/pg_hba.conf configuration file. Otherwise only the postgres user will be allowed to access the database.