Migrating Database Applications

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

v2v3

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):

    1. $ rhc ssh <v2_application_name>
    2. $ mysqldump --skip-lock-tables -h $OPENSHIFT_MYSQL_DB_HOST -P ${OPENSHIFT_MYSQL_DB_PORT:-3306} -u ${OPENSHIFT_MYSQL_DB_USERNAME:-'admin'} \
    3. --password="$OPENSHIFT_MYSQL_DB_PASSWORD" --all-databases > ~/app-root/data/all.sql
    4. $ exit
  2. Download dbdump to your local machine:

    1. $ mkdir mysqldumpdir
    2. $ rhc scp -a <v2_application_name> download mysqldumpdir app-root/data/all.sql
  3. Create a v3 mysql-persistent pod from template:

    1. $ oc new-app mysql-persistent -p \
    2. MYSQL_USER=<your_V2_mysql_username> -p \
    3. MYSQL_PASSWORD=<your_v2_mysql_password> -p MYSQL_DATABASE=<your_v2_database_name>
  4. Check to see if the pod is ready to use:

    1. $ oc get pods
  5. When the pod is up and running, copy database archive files to your v3 MySQL pod:

    1. $ oc rsync /local/mysqldumpdir <mysql_pod_name>:/var/lib/mysql/data
  6. Restore the database in the v3 running pod:

    1. $ oc rsh <mysql_pod>
    2. $ 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.

    1. $ mysql -u root
    2. $ source all.sql

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

  7. Remove the dump directory from the pod:

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

Supported MySQL Environment Variables

v2v3

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:

    1. $ rhc ssh -a <v2-application_name>
    2. $ mkdir ~/app-root/data/tmp
    3. $ pg_dump <database_name> | gzip > ~/app-root/data/tmp/<database_name>.gz
  2. Extract the backup file back to your local machine:

    1. $ rhc scp -a <v2_application_name> download <local_dest> app-root/data/tmp/<db-name>.gz
    2. $ 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:

    1. $ oc new-app postgresql-persistent -p POSTGRESQL_DATABASE=dbname -p
    2. POSTGRESQL_PASSWORD=password -p POSTGRESQL_USER=username
  4. Check to see if the pod is ready to use:

    1. $ oc get pods
  5. When the pod is up and running, sync the backup directory to pod:

    1. $ oc rsync /local/path/to/dir <postgresql_pod_name>:/var/lib/pgsql/data
  6. Remotely access the pod:

    1. $ oc rsh <pod_name>
  7. Restore the database:

    1. psql dbname < /var/lib/pgsql/data/<database_backup_file>
  8. Remove all backup files that are no longer needed:

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

Supported PostgreSQL Environment Variables

v2v3

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:

    1. $ 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:

    1. $ mongodump -h $OPENSHIFT_MONGODB_DB_HOST -o app-root/repo/mydbdump -u 'admin' -p $OPENSHIFT_MONGODB_DB_PASSWORD
    2. $ cd app-root/repo/mydbdump/<database_name>; tar -cvzf dbname.tar.gz
    3. $ exit
  3. Download dbdump to a local machine in the mongodump directory:

    1. $ mkdir mongodump
    2. $ rhc scp -a <v2 appname> download mongodump \
    3. 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:

    1. $ 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**.

    1. $ oc new-app --template=mongodb-persistent -n <project-name-that-template-was-created-in> \
    2. MONGODB_USER=user_from_v2_app -p \
    3. MONGODB_PASSWORD=password_from_v2_db -p \
    4. MONGODB_DATABASE=v2_dbname -p \
    5. MONGODB_ADMIN_PASSWORD=password_from_v2_db
    6. $ oc get pods
  5. When the mongodb pod is up and running, copy the database archive files to the v3 MongoDB pod:

    1. $ oc rsync local/path/to/mongodump <mongodb_pod_name>:/var/lib/mongodb/data
    2. $ oc rsh <mongodb_pod>
  6. In the MongoDB pod, complete the following for each database you want to restore:

    1. $ cd /var/lib/mongodb/data/mongodump
    2. $ tar -xzvf dbname.tar.gz
    3. $ mongorestore -u $MONGODB_USER -p $MONGODB_PASSWORD -d dbname -v /var/lib/mongodb/data/mongodump
  7. Check if the database is restored:

    1. $ mongo admin -u $MONGODB_USER -p $MONGODB_ADMIN_PASSWORD
    2. $ use dbname
    3. $ show collections
    4. $ exit
  8. Remove the mongodump directory from the pod:

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

Supported MongoDB Environment Variables

v2v3

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