src/bin/pg_upgrade/TESTING

THE SHORT VERSION
-----------------

On non-Windows machines, you can execute the testing process
described below by running the following command in this directory:

	make check

This will run the TAP tests to run pg_upgrade, performing an upgrade
from the version in this source tree to a new instance of the same
version.

Testing an upgrade from a different PG version is also possible, and
provides a more thorough test that pg_upgrade does what it's meant for.
This requires both a source tree and an installed tree for the old
version, as well as a dump file to set up the instance to be upgraded.
The following environment variables must be set to enable this testing:
export olddump=...somewhere/dump.sql	(old version's dump)
export oldinstall=...otherversion/	(old version's install base path)
See DETAILS below for more information about creation of the dump.

You can also test the different transfer modes (--copy, --link,
--clone) by setting the environment variable PG_TEST_PG_UPGRADE_MODE
to the respective command-line option, like

	make check PG_TEST_PG_UPGRADE_MODE=--link

The default is --copy.  Note that the other modes are not supported on
all operating systems.

DETAILS
-------

The most effective way to test pg_upgrade, aside from testing on user
data, is by upgrading the PostgreSQL regression database.

This testing process first requires the creation of a valid regression
database dump that can then be used for $olddump.  Such files contain
most database features and are specific to each major version of Postgres.

Here are the steps needed to create a dump file:

1)  Create and populate the regression database in the old cluster.
    This database can be created by running 'make installcheck' from
    src/test/regress in the old version's source code tree.

    If you like, you can also populate regression databases for one or
    more contrib modules by running 'make installcheck USE_MODULE_DB=1'
    in their directories.  (USE_MODULE_DB is essential so that the
    pg_upgrade test script will understand which database is which.)

2)  Use pg_dumpall to dump out the contents of the instance, including the
    regression database(s), into a SQL file.  Use the *old* version's
    pg_dumpall so that the dump created is compatible with that version.

Once the dump file is created, it can be used repeatedly.  Set $olddump
to point to the dump file and run 'make check' or 'make installcheck'
in the new version's src/bin/pg_upgrade directory.  (If you included any
contrib databases in the old dump, you must use 'make installcheck' and
ensure that the corresponding contrib modules have been installed in
the new version's installation tree.)  This will build a temporary cluster
using the old installation's executables, populate it from the dump file,
and then try to pg_upgrade it to the new version.  Success is reported
if pg_dumpall output matches between the pre-upgrade and post-upgrade
databases.  In case of trouble, manually comparing those dump files may
help to isolate the problem.