COMMAND NAME: gpmigrator

Upgrades an existing Greenplum Database 4.2.x system 
without mirrors to 4.3.x.

Use gpmigrator_mirror to upgrade a 4.2.x system that 
has mirrors.

NOTE: Using gpmigrator on a system with mirrors causes 
      an error.

*****************************************************
SYNOPSIS
*****************************************************

gpmigrator <old_GPHOME_path> <new_GPHOME_path>
           [-d <master_data_directory>] 
           [-l <logfile_directory>] [-q] 
           [--check-only] [--debug] [-R]

gpmigrator --version | -v

gpmigrator --help | -h


*****************************************************
PREREQUISITES
*****************************************************

The following tasks should be performed prior to executing an upgrade:

* Make sure you are logged in to the master host as the Greenplum Database 
  superuser (gpadmin).
* Install the Greenplum Database 4.3 binaries on all Greenplum hosts.
* Copy any custom modules you use into your 4.3 installation.  Make sure 
  you obtain the latest version of any custom modules and that they are 
  compatible with Greenplum Database 4.3.
* Copy or preserve any additional folders or files (such as backup folders) 
  that you have added in the Greenplum data directories or $GPHOME directory. 
  Only files or folders strictly related to Greenplum Database operations are 
  preserved by the migration utility.
* (Optional) Run VACUUM on all databases, and remove old server log files 
  from pg_log in your master and segment data directories. This is not required, 
  but will reduce the size of Greenplum Database files to be backed up and migrated.
* Check for and recover any failed segments in your current Greenplum Database 
  system (gpstate, gprecoverseg).
* (Optional, but highly recommended) Backup your current databases (gpcrondump 
   or ZFS snapshots). If you find any issues when testing your upgraded system, 
   you can restore this backup.
* Remove the standby master from your system configuration (gpinitstandby -r).
* Do a clean shutdown of your current system (gpstop).
* Update your environment to source the 4.3 installation.
* Inform all database users of the upgrade and lockout time frame. Once the 
  upgrade is in process, users will not be allowed on the system until the 
  upgrade is complete.


*****************************************************
DESCRIPTION
*****************************************************

The gpmigrator utility upgrades an existing Greenplum Database 4.2.x.x 
system without mirrors to 4.3. This utility updates the system catalog 
and internal version number, but not the actual software binaries. 
During the migration process, all client connections to Greenplum 
Database will be locked out.


*****************************************************
OPTIONS
*****************************************************

<old_GPHOME_path>

 Required. The absolute path to the current version of Greenplum 
 Database software you want to migrate away from.


<new_GPHOME_path>

 Required. The absolute path to the new version of Greenplum Database 
 software you want to migrate to.


-d <master_data_directory>

 Optional. The current master host data directory. If not specified, 
 the value set for $MASTER_DATA_DIRECTORY will be used.


-l <logfile_directory>

 The directory to write the log file. Defaults to ~/gpAdminLogs.


-q (quiet mode)

 Run in quiet mode. Command output is not displayed on the screen, but is 
 still written to the log file.


-R (revert)
 
 In the event of an error during upgrade, reverts all changes made by gpmigrator.


--check-only

 Runs pre-migrate checks to verify that your database is healthy.
 Checks include: 
  * Check catalog health
  * Check that the Greenplum Database binaries on each segment match 
    those on the master
  * Check for a minimum amount of free disk space

 NOTE: Performing a pre-migration check of your database should done 
 during a database maintenance period. If the utility detects catalog 
 errors, the utility stops the database.


--help | -h
 Displays the online help.


--debug
 Sets logging level to debug.


--version | -v
 Displays the version of this utility. 


*****************************************************
EXAMPLE
*****************************************************

Upgrade to version 4.3.x from version 4.2.x (make sure you are using the 
4.3 version of gpmigrator). This example upgrades to version 4.3.0.0 
from version 4.2.6.3: 

/usr/local/greenplum-db-4.3.0.0/bin/gpmigrator \
  /usr/local/greenplum-db-4.2.6.3 \
  /usr/local/greenplum-db-4.3.0.0


*****************************************************
SEE ALSO
*****************************************************

gpmigrator_mirror, gpstop, gpstate, gprecoverseg, gpcrondump