Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

Migrating Database Applications

Important

Azure Red Hat OpenShift 3.11 will be retired 30 June 2022. Support for creation of new Azure Red Hat OpenShift 3.11 clusters continues through 30 November 2020. Following retirement, remaining Azure Red Hat OpenShift 3.11 clusters will be shut down to prevent security vulnerabilities.

Follow this guide to create an Azure Red Hat OpenShift 4 cluster. If you have specific questions, please contact us

Overview

This topic reviews how to migrate MySQL, PostgreSQL, and MongoDB database applications from OpenShift version 2 (v2) to OpenShift version 3 (v3).

Supported Databases

v2 v3

MongoDB: 2.4

MongoDB: 2.4, 2.6

MySQL: 5.5

MySQL: 5.5, 5.6

PostgreSQL: 9.2

PostgreSQL: 9.2, 9.4

MySQL

  1. Export all databases to a dump file and copy it to a local machine (into the current directory):

    $ rhc ssh <v2_application_name>
$ mysqldump --skip-lock-tables -h $OPENSHIFT_MYSQL_DB_HOST -P ${OPENSHIFT_MYSQL_DB_PORT:-3306} -u ${OPENSHIFT_MYSQL_DB_USERNAME:-'admin'} \
 --password="$OPENSHIFT_MYSQL_DB_PASSWORD" --all-databases > ~/app-root/data/all.sql
$ exit

  2. Download dbdump to your local machine:

    $ mkdir mysqldumpdir
$ rhc scp -a <v2_application_name> download mysqldumpdir app-root/data/all.sql

  3. Create a v3 mysql-persistent pod from template:

    $ oc new-app mysql-persistent -p \
   MYSQL_USER=<your_V2_mysql_username> -p \
   MYSQL_PASSWORD=<your_v2_mysql_password> -p MYSQL_DATABASE=<your_v2_database_name>

  4. Check to see if the pod is ready to use:

    $ oc get pods

  5. When the pod is up and running, copy database archive files to your v3 MySQL pod:

    $ oc rsync /local/mysqldumpdir <mysql_pod_name>:/var/lib/mysql/data

  6. Restore the database in the v3 running pod:

    $ oc rsh <mysql_pod>
$ cd /var/lib/mysql/data/mysqldumpdir

    In v3, to restore databases you need to access MySQL as root user.

    In v2, the $OPENSHIFT_MYSQL_DB_USERNAME had full privileges on all databases. In v3, you must grant privileges to $MYSQL_USER for each database.

    $ mysql -u root
$ source all.sql

    Grant all privileges on <dbname> to <your_v2_username>@localhost, then flush privileges.

  7. Remove the dump directory from the pod:

    $ cd ../; rm -rf /var/lib/mysql/data/mysqldumpdir

Supported MySQL Environment Variables

v2 v3

OPENSHIFT_MYSQL_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_MYSQL_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_MYSQL_DB_USERNAME

MYSQL_USER

OPENSHIFT_MYSQL_DB_PASSWORD

MYSQL_PASSWORD

OPENSHIFT_MYSQL_DB_URL

OPENSHIFT_MYSQL_DB_LOG_DIR

OPENSHIFT_MYSQL_VERSION

OPENSHIFT_MYSQL_DIR

OPENSHIFT_MYSQL_DB_SOCKET

OPENSHIFT_MYSQL_IDENT

OPENSHIFT_MYSQL_AIO

MYSQL_AIO

OPENSHIFT_MYSQL_MAX_ALLOWED_PACKET

MYSQL_MAX_ALLOWED_PACKET

OPENSHIFT_MYSQL_TABLE_OPEN_CACHE

MYSQL_TABLE_OPEN_CACHE

OPENSHIFT_MYSQL_SORT_BUFFER_SIZE

MYSQL_SORT_BUFFER_SIZE

OPENSHIFT_MYSQL_LOWER_CASE_TABLE_NAMES

MYSQL_LOWER_CASE_TABLE_NAMES

OPENSHIFT_MYSQL_MAX_CONNECTIONS

MYSQL_MAX_CONNECTIONS

OPENSHIFT_MYSQL_FT_MIN_WORD_LEN

MYSQL_FT_MIN_WORD_LEN

OPENSHIFT_MYSQL_FT_MAX_WORD_LEN

MYSQL_FT_MAX_WORD_LEN

OPENSHIFT_MYSQL_DEFAULT_STORAGE_ENGINE

OPENSHIFT_MYSQL_TIMEZONE

MYSQL_DATABASE

MYSQL_ROOT_PASSWORD

MYSQL_MASTER_USER

MYSQL_MASTER_PASSWORD

PostgreSQL

  1. Back up the v2 PostgreSQL database from the gear:

    $ rhc ssh -a <v2-application_name>
$ mkdir ~/app-root/data/tmp
$ pg_dump <database_name> | gzip > ~/app-root/data/tmp/<database_name>.gz

  2. Extract the backup file back to your local machine:

    $ rhc scp -a <v2_application_name> download <local_dest> app-root/data/tmp/<db-name>.gz
$ gzip -d <database-name>.gz

    Save the backup file to a separate folder for step 4.

  3. Create the PostgreSQL service using the v2 application database name, user name and password to create the new service:

    $ oc new-app postgresql-persistent -p POSTGRESQL_DATABASE=dbname -p
POSTGRESQL_PASSWORD=password -p POSTGRESQL_USER=username

  4. Check to see if the pod is ready to use:

    $ oc get pods

  5. When the pod is up and running, sync the backup directory to pod:

    $ oc rsync /local/path/to/dir <postgresql_pod_name>:/var/lib/pgsql/data

  6. Remotely access the pod:

    $ oc rsh <pod_name>

  7. Restore the database:

    psql dbname < /var/lib/pgsql/data/<database_backup_file>

  8. Remove all backup files that are no longer needed:

    $ rm /var/lib/pgsql/data/<database-backup-file>

Supported PostgreSQL Environment Variables

v2 v3

OPENSHIFT_POSTGRESQL_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_POSTGRESQL_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_POSTGRESQL_DB_USERNAME

POSTGRESQL_USER

OPENSHIFT_POSTGRESQL_DB_PASSWORD

POSTGRESQL_PASSWORD

OPENSHIFT_POSTGRESQL_DB_LOG_DIR

OPENSHIFT_POSTGRESQL_DB_PID

OPENSHIFT_POSTGRESQL_DB_SOCKET_DIR

OPENSHIFT_POSTGRESQL_DB_URL

OPENSHIFT_POSTGRESQL_VERSION

OPENSHIFT_POSTGRESQL_SHARED_BUFFERS

OPENSHIFT_POSTGRESQL_MAX_CONNECTIONS

OPENSHIFT_POSTGRESQL_MAX_PREPARED_TRANSACTIONS

OPENSHIFT_POSTGRESQL_DATESTYLE

OPENSHIFT_POSTGRESQL_LOCALE

OPENSHIFT_POSTGRESQL_CONFIG

OPENSHIFT_POSTGRESQL_SSL_ENABLED

POSTGRESQL_DATABASE

POSTGRESQL_ADMIN_PASSWORD

MongoDB

  • For OpenShift v3: MongoDB shell version 3.2.6

  • For OpenShift v2: MongoDB shell version 2.4.9

  1. Remotely access the v2 application via the ssh command:

    $ rhc ssh <v2_application_name>

  2. Run mongodump, specifying a single database with -d <database_name> -c <collections>. Without those options, dump all databases. Each database is dumped in its own directory:

    $ mongodump -h $OPENSHIFT_MONGODB_DB_HOST -o app-root/repo/mydbdump -u 'admin' -p $OPENSHIFT_MONGODB_DB_PASSWORD
$ cd app-root/repo/mydbdump/<database_name>; tar -cvzf dbname.tar.gz
$ exit

  3. Download dbdump to a local machine in the mongodump directory:

    $ mkdir mongodump
$ rhc scp -a <v2 appname> download mongodump \
  app-root/repo/mydbdump/<dbname>/dbname.tar.gz

  4. Start a MongoDB pod in v3. Because the latest image (3.2.6) does not include mongo-tools, to use mongorestore or mongoimport commands you need to edit the default mongodb-persistent template to specify the image tag that contains the mongo-tools, “mongodb:2.4”. For that reason, the following oc get --export command and edit are necessary:

    $ oc get -o json --export template mongodb-persistent -n openshift > mongodb-24persistent.json

    Edit L80 of mongodb-24persistent.json; replace mongodb:latest with mongodb:2.4.

    $ oc new-app --template=mongodb-persistent -n <project-name-that-template-was-created-in> \
  MONGODB_USER=user_from_v2_app -p \
  MONGODB_PASSWORD=password_from_v2_db -p \
  MONGODB_DATABASE=v2_dbname -p \
  MONGODB_ADMIN_PASSWORD=password_from_v2_db
$ oc get pods

  5. When the mongodb pod is up and running, copy the database archive files to the v3 MongoDB pod:

    $ oc rsync local/path/to/mongodump <mongodb_pod_name>:/var/lib/mongodb/data
$ oc rsh <mongodb_pod>

  6. In the MongoDB pod, complete the following for each database you want to restore:

    $ cd /var/lib/mongodb/data/mongodump
$ tar -xzvf dbname.tar.gz
$ mongorestore -u $MONGODB_USER -p $MONGODB_PASSWORD -d dbname -v /var/lib/mongodb/data/mongodump

  7. Check if the database is restored:

    $ mongo admin -u $MONGODB_USER -p $MONGODB_ADMIN_PASSWORD
$ use dbname
$ show collections
$ exit

  8. Remove the mongodump directory from the pod:

    $ rm -rf /var/lib/mongodb/data/mongodump

Supported MongoDB Environment Variables

v2 v3

OPENSHIFT_MONGODB_DB_HOST

[service_name]_SERVICE_HOST

OPENSHIFT_MONGODB_DB_PORT

[service_name]_SERVICE_PORT

OPENSHIFT_MONGODB_DB_USERNAME

MONGODB_USER

OPENSHIFT_MONGODB_DB_PASSWORD

MONGODB_PASSWORD

OPENSHIFT_MONGODB_DB_URL

OPENSHIFT_MONGODB_DB_LOG_DIR

MONGODB_DATABASE

MONGODB_ADMIN_PASSWORD

MONGODB_NOPREALLOC

MONGODB_SMALLFILES

MONGODB_QUIET

MONGODB_REPLICA_NAME

MONGODB_KEYFILE_VALUE