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
   6         make check
   7 in this directory.  This will run the shell script test.sh, performing
   8 an upgrade from the version in this source tree to a new instance of
   9 the same version.
  10
  11 To test an upgrade from a different version, you must have a built
  12 source tree for the old version as well as this version, and you
  13 must have done "make install" for both versions.  Then do:
  14
  15 export oldsrc=...somewhere/postgresql   (old version's source tree)
  16 export oldbindir=...otherversion/bin    (old version's installed bin dir)
  17 export bindir=...thisversion/bin        (this version's installed bin dir)
  18 export libdir=...thisversion/lib        (this version's installed lib dir)
  19 sh test.sh
  20
  21 In this case, you will have to manually eyeball the resulting dump
  22 diff for version-specific differences, as explained below.
  23
  24
  25 DETAILS
  26 -------
  27
  28 The most effective way to test pg_upgrade, aside from testing on user
  29 data, is by upgrading the PostgreSQL regression database.
  30
  31 This testing process first requires the creation of a valid regression
  32 database dump.  Such files contain most database features and are
  33 specific to each major version of Postgres.
  34
  35 Here are the steps needed to create a regression database dump file:
  36
  37 1)  Create and populate the regression database in the old cluster.
  38     This database can be created by running 'make installcheck' from
  39     src/test/regress.
  40
  41 2)  Use pg_dump to dump out the regression database.  Use the new
  42     cluster's pg_dump on the old database to minimize whitespace
  43     differences in the diff.
  44
  45 3)  Adjust the regression database dump file
  46
  47     a)  Perform the load/dump twice
  48         This fixes problems with the ordering of COPY columns for
  49         inherited tables.
  50
  51     b)  Change CREATE FUNCTION shared object paths to use '$libdir'
  52         The old and new cluster will have different shared object paths.
  53
  54     c)  Fix any wrapping format differences
  55         Commands like CREATE TRIGGER and ALTER TABLE sometimes have
  56         differences.
  57
  58     d)  For pre-9.0, change CREATE OR REPLACE LANGUAGE to CREATE LANGUAGE
  59
  60     e)  For pre-9.0, remove 'regex_flavor'
  61
  62     f)  For pre-9.0, adjust extra_float_digits
  63         Postgres 9.0 pg_dump uses extra_float_digits=-2 for pre-9.0
  64         databases, and extra_float_digits=-3 for >= 9.0 databases.
  65         It is necessary to modify 9.0 pg_dump to always use -3, and
  66         modify the pre-9.0 old server to accept extra_float_digits=-3.
  67
  68 Once the dump is created, it can be repeatedly loaded into the old
  69 database, upgraded, and dumped out of the new database, and then
  70 compared to the original version. To test the dump file, perform these
  71 steps:
  72
  73 1)  Create the old and new clusters in different directories.
  74
  75 2)  Copy the regression shared object files into the appropriate /lib
  76     directory for old and new clusters.
  77
  78 3)  Create the regression database in the old server.
  79
  80 4)  Load the dump file created above into the regression database;
  81     check for errors while loading.
  82
  83 5)  Upgrade the old database to the new major version, as outlined in
  84     the pg_upgrade manual section.
  85
  86 6)  Use pg_dump to dump out the regression database in the new cluster.
  87
  88 7)  Diff the regression database dump file with the regression dump
  89     file loaded into the old server.