Using gpmigrator in Greenplum 4.1.1

In this article, I am going to upgrade a Greenplum cluster from version 4.0 to 4.1 using `gpmigrator`.
`gpmigrator` is an utility shipped with Greenplum Community Edition whose purpose is to perform a live upgrade of an existing database.

Requirements
——————
In order for you to follow this article, you need a Greenplum 4.0 cluster up and running.
I assume it has been installed in the standard path: `/usr/local/greenplum-db-4.0.4.0`.
You must not have mirrors in your cluster, otherwise `gpmigrator` *will fail*.
If you have to upgrade a cluster with mirrors, see `gpmigrator_mirror` instead.
`gpmigrator` 4.1 upgrades a 4.0 cluster to 4.1 *strictly*, do not try to upgrade a prior version.
If you really want to upgrade from 3.3.x to 4.1, please do it in two separate steps: first upgrade to 4.0, then to 4.1.
The preparation ritual
—————————
Details are important.
To upgrade Greenplum and be happy with it, you must perform some preparation steps:
* Install Greenplum 4.1 (I assume you will install it in default path `/usr/local/greenplum-db-4.1.4.1`)
* If you have any custom module, copy it from the actual Greenplum location (`/usr/local/greenplum-db-4.0.4.0/lib`) to the new version location (`/usr/local/greenplum-db-4.1.4.1/lib`)
* Do the same with any PostgreSQL module, if present. Copy it from `/usr/local/greenplum-db-4.0.4.0/lib/postgresql` to `/usr/local/greenplum-db-4.1.4.1/lib/postgresql`
* There must not be any failed segments in your current Greenplum system (you can recover any failed segment using `gprecoverseg` – please refer to the AdminGuide version 4.0 to find detailed information on such a task)
* Make a backup of your cluster! This is not necessary but *highly* recommended, in case any problem should occur
* Remove the standby master from your system configuration (`gpinitstandby -r`)
* Do a clean shutdown of your current system (`gpstop`)
_Yes, `gpmigrator` needs a downtime of the server, so please be careful to take the required precautions about clients connecting to it._
* Update gpadmin’s `.bashrc` or `.bash_profile` to source the new greeenplum path file:

$ cat ~gpadmin/.bashrc | grep greenplum-db-4.1
source /usr/local/greenplum-db-4.1.1.1/greenplum_path.sh

The actual upgrade
------------------------
After all this work, we are able to launch the one-command magic that will upgrade Greenplum.
`gpmigrator` has a very simple usage, you can find detailed informations and the available options with:

$ gpmigrator --help

or by reading the `gpmigrator` page in the Greenplum 4.1 AdminGuide, under the section named _"Appendix B: Management Utility Reference"_.
We are ready to launch it. As `gpadmin`, type:

$ /usr/local/greenplum-db-4.1.1.1/bin/gpmigrator /usr/local/greenplum-db-4.0.4.0 /usr/local/greenplum-db-4.1.1.1

if everything works fine, the last bits of information to be displayed will be:

...
20111014:13:55:05:gpmigrator:centos:gpadmin-[INFO]:-Removing temporary directori
20111014:13:55:05:gpmigrator:centos:gpadmin-[INFO]:-----------------------------
20111014:13:55:05:gpmigrator:centos:gpadmin-[INFO]:-Upgrade Successful
20111014:13:55:05:gpmigrator:centos:gpadmin-[INFO]:-----------------------------
20111014:13:55:05:gpmigrator:centos:gpadmin-[INFO]:-Please consult release notes
20111014:13:55:05:gpmigrator:centos:gpadmin-[INFO]:-instructions to complete env
20111014:13:55:05:gpmigrator:centos:gpadmin-[INFO]:-----------------------------

As you can see in the command above, we have specified on the command line the _old_ `$GP_HOME`, and the _new_ one.
`GP_HOME` is the directory where you have installed Greenplum. Change it accordingly to your installation paths.