The Greenplum pg_upgrade code has been extended to work with
Apache Cloudberry. 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 Apache Cloudberry cluster with
pg_upgrade is done by first upgrading the QD and then the QEs.


Distributed Apache Cloudberry upgrades
------------------------------

Apache Cloudberry 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 Apache Cloudberry 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 Cloudberry
Database 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.
