src/bin/pg_upgrade/TESTING

   1 THE SHORT VERSION
   2 -----------------
   3
   4 On non-Windows machines, you can execute the testing process
   5 described below by running the following command in this directory:
   6
   7         make check
   8
   9 This will run the TAP tests to run pg_upgrade, performing an upgrade
  10 from the version in this source tree to a new instance of the same
  11 version.
  12
  13 Testing an upgrade from a different PG version is also possible, and
  14 provides a more thorough test that pg_upgrade does what it's meant for.
  15 This requires both a source tree and an installed tree for the old
  16 version, as well as a dump file to set up the instance to be upgraded.
  17 The following environment variables must be set to enable this testing:
  18 export olddump=...somewhere/dump.sql    (old version's dump)
  19 export oldinstall=...otherversion/      (old version's install base path)
  20 See DETAILS below for more information about creation of the dump.
  21
  22 You can also test the different transfer modes (--copy, --link,
  23 --clone, --copy-file-range) by setting the environment variable
  24 PG_TEST_PG_UPGRADE_MODE to the respective command-line option, like
  25
  26         make check PG_TEST_PG_UPGRADE_MODE=--link
  27
  28 The default is --copy.  Note that the other modes are not supported on
  29 all operating systems.
  30
  31 DETAILS
  32 -------
  33
  34 The most effective way to test pg_upgrade, aside from testing on user
  35 data, is by upgrading the PostgreSQL regression database.
  36
  37 This testing process first requires the creation of a valid regression
  38 database dump that can then be used for $olddump.  Such files contain
  39 most database features and are specific to each major version of Postgres.
  40
  41 Here are the steps needed to create a dump file:
  42
  43 1)  Create and populate the regression database in the old cluster.
  44     This database can be created by running 'make installcheck' from
  45     src/test/regress in the old version's source code tree.
  46
  47     If you like, you can also populate regression databases for one or
  48     more contrib modules by running 'make installcheck USE_MODULE_DB=1'
  49     in their directories.  (USE_MODULE_DB is essential so that the
  50     pg_upgrade test script will understand which database is which.)
  51
  52 2)  Use pg_dumpall to dump out the contents of the instance, including the
  53     regression database(s), into a SQL file.  Use the *old* version's
  54     pg_dumpall so that the dump created is compatible with that version.
  55
  56 Once the dump file is created, it can be used repeatedly.  Set $olddump
  57 to point to the dump file and run 'make check' or 'make installcheck'
  58 in the new version's src/bin/pg_upgrade directory.  (If you included any
  59 contrib databases in the old dump, you must use 'make installcheck' and
  60 ensure that the corresponding contrib modules have been installed in
  61 the new version's installation tree.)  This will build a temporary cluster
  62 using the old installation's executables, populate it from the dump file,
  63 and then try to pg_upgrade it to the new version.  Success is reported
  64 if pg_dumpall output matches between the pre-upgrade and post-upgrade
  65 databases.  In case of trouble, manually comparing those dump files may
  66 help to isolate the problem.