The Greenplum pg_upgrade code has been extended to work with Greenplum. This
README is intended to document the changes that have been done.

Operation of pg_upgrade remains unchanged as are the available command line
parameters. Upgrading a Greenplum cluster with pg_upgrade is done by first
upgrading the QD and then the QEs.


Distributed Greenplum upgrades
------------------------------

Greenplum requires that all Oids are synchronized between the QD and the QEs,
so the upgrade must maintain this invariant.  Further, the upgrade must do as
much as it can in parallel to ensure the cluster is upgraded with as little
downtime as possible.  To satisfy both requirements, the upgrade process is
split between QD and QE.  The QD is first upgraded, and the schema dumped and
restored.  The new data directory created as part of the upgrade is transferred
to all QEs, with the local QE configuration retained.  The QE upgrade can then
skip the schema dump/reload part and only transfer the files.


Extensions to upstream pg_upgrade
---------------------------------

Functionality for restoring the append-only catalog relations is in
aotable.c.

Upgrading from 5.0 to 6.0
-------------------------

The name_pattern_ops and pattern equality operators were removed in 6.0 and
text equality is treated like bitwise equality. This will cause internal sort
order in bpchar_pattern_ops which is now trailing-blank-insensitive. This means
that indexes must be dropped and recreated as part of the upgrade to ensure
correct results.


Testing Greenplum pg_upgrade
----------------------------

There is a testrunner script in contrib/pg_upgrade which runs a full upgrade of
the gpdemo cluster and it's current contents. The idea is that it can be used
to test upgrades by running as the final step of ICW. The test can be invoked
by "make installcheck" in the contrib/pg_upgrade directory.

The testscript also has a "smoketest" option which only tests upgrading a
single node.  This is *not* a test of an actual Greenplum cluster upgrade,
but a test of the Oid synchronization required to handle a node upgrade. The
intention is for this to be a quick test that all objects are handled by
pg_upgrade; upgrade testing still requires the full run across all
segments/mirrors. The smoketest can be invoked by "make check" in the
contrib/pg_upgrade directory.

GPDB Merge notice:
------------------
We added the gp_fatal_log() function to replace some of the pg_fatal() calls in
check.c and check_gp.c to support --continue-check-on-fatal, which allows
running through all the checks even if we get a fatal failure. We need to
update any newly added checks to ensure they work with the flag by replacing
pg_fatal function calls with gp_fatal_log calls.

Note: we cannot skip few checks despite using the --continue-check-on-fatal
flag. See gp_fatal_log() for details.

For --skip-target-check flag while merging upstream, if we have new checks for
new/target cluster, they should be skipped when the flag is enabled. See
is_skip_target_check(). There might be new pre-check steps for the target
cluster before we check_new_cluster(), such as get_sock_dir(), which must be
guarded.
