1 contrib/pg_upgrade/TESTING
3 The most effective way to test pg_upgrade, aside from testing on user
4 data, is by upgrading the PostgreSQL regression database.
6 This testing process first requires the creation of a valid regression
7 database dump. Such files contain most database features and are
8 specific to each major version of Postgres.
10 Here are the steps needed to create a regression database dump file:
12 1) Create and populate the regression database in the old cluster
13 This database can be created by running 'gmake installcheck' from
16 2) Use pg_dump to dump out the regression database. Use the new
17 cluster's pg_dump on the old database to minimize whitespace
18 differences in the diff.
20 3) Adjust the regression database dump file
22 a) Perform the load/dump twice
23 This fixes problems with the ordering of COPY columns for
26 b) Change CREATE FUNCTION shared object paths to use '$libdir'
27 The old and new cluster will have different shared object paths.
29 c) Fix any wrapping format differences
30 Commands like CREATE TRIGGER and ALTER TABLE sometimes have
33 d) For pre-9.0, change CREATE OR REPLACE LANGUAGE to CREATE LANGUAGE
35 e) For pre-9.0, remove 'regex_flavor'
37 f) For pre-9.0, adjust extra_float_digits
38 Postgres 9.0 pg_dump uses extra_float_digits=-2 for pre-9.0
39 databases, and extra_float_digits=-3 for >= 9.0 databases.
40 It is necessary to modify 9.0 pg_dump to always use -3, and
41 modify the pre-9.0 old server to accept extra_float_digits=-3.
43 Once the dump is created, it can be repeatedly loaded into the old
44 database, upgraded, and dumped out of the new database, and then
45 compared to the original version. To test the dump file, perform these
48 1) Create the old and new clusters in different directories.
50 2) Copy the regression shared object files into the appropriate /lib
51 directory for old and new clusters.
53 3) Create the regression database in the old server.
55 4) Load the dump file created above into the regression database;
56 check for errors while loading.
58 5) Upgrade the old database to the new major version, as outlined in
59 the pg_upgrade manual section.
61 6) Use pg_dump to dump out the regression database in the new cluster.
63 7) Diff the regression database dump file with the regression dump
64 file loaded into the old server.
66 The shell script test.sh in this directory performs more or less this
67 procedure. You can invoke it by running
75 if "gmake install" (or "gmake install-world") were done beforehand.
76 When invoked without arguments, it will run an upgrade from the
77 version in this source tree to a new instance of the same version. To
78 test an upgrade from a different version, invoke it like this:
80 gmake installcheck oldbindir=...otherversion/bin oldsrc=...somewhere/postgresql
82 In this case, you will have to manually eyeball the resulting dump
83 diff for version-specific differences, as explained above.