1 files changed, 89 insertions, 0 deletions
diff --git a/src/bin/pg_upgrade/TESTING b/src/bin/pg_upgrade/TESTING
new file mode 100644
index 0000000..e69874b
--- /dev/null
+++ b/src/bin/pg_upgrade/TESTING
@@ -0,0 +1,89 @@
+THE SHORT VERSION
+-----------------
+
+On non-Windows machines, you can execute the testing process
+described below by running
+	make check
+in this directory.  This will run the shell script test.sh, performing
+an upgrade from the version in this source tree to a new instance of
+the same version.
+
+To test an upgrade from a different version, you must have a built
+source tree for the old version as well as this version, and you
+must have done "make install" for both versions.  Then do:
+
+export oldsrc=...somewhere/postgresql	(old version's source tree)
+export oldbindir=...otherversion/bin	(old version's installed bin dir)
+export bindir=...thisversion/bin	(this version's installed bin dir)
+export libdir=...thisversion/lib	(this version's installed lib dir)
+sh test.sh
+
+In this case, you will have to manually eyeball the resulting dump
+diff for version-specific differences, as explained below.
+
+
+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.  Such files contain most database features and are
+specific to each major version of Postgres.
+
+Here are the steps needed to create a regression database 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.
+
+2)  Use pg_dump to dump out the regression database.  Use the new
+    cluster's pg_dump on the old database to minimize whitespace
+    differences in the diff.
+
+3)  Adjust the regression database dump file
+
+    a)  Perform the load/dump twice
+        This fixes problems with the ordering of COPY columns for
+        inherited tables.
+
+    b)  Change CREATE FUNCTION shared object paths to use '$libdir'
+        The old and new cluster will have different shared object paths.
+
+    c)  Fix any wrapping format differences
+        Commands like CREATE TRIGGER and ALTER TABLE sometimes have
+        differences.
+
+    d)  For pre-9.0, change CREATE OR REPLACE LANGUAGE to CREATE LANGUAGE
+
+    e)  For pre-9.0, remove 'regex_flavor'
+
+    f)  For pre-9.0, adjust extra_float_digits
+        Postgres 9.0 pg_dump uses extra_float_digits=-2 for pre-9.0
+        databases, and extra_float_digits=-3 for >= 9.0 databases.
+        It is necessary to modify 9.0 pg_dump to always use -3, and
+        modify the pre-9.0 old server to accept extra_float_digits=-3.
+
+Once the dump is created, it can be repeatedly loaded into the old
+database, upgraded, and dumped out of the new database, and then
+compared to the original version. To test the dump file, perform these
+steps:
+
+1)  Create the old and new clusters in different directories.
+
+2)  Copy the regression shared object files into the appropriate /lib
+    directory for old and new clusters.
+
+3)  Create the regression database in the old server.
+
+4)  Load the dump file created above into the regression database;
+    check for errors while loading.
+
+5)  Upgrade the old database to the new major version, as outlined in
+    the pg_upgrade manual section.
+
+6)  Use pg_dump to dump out the regression database in the new cluster.
+
+7)  Diff the regression database dump file with the regression dump
+    file loaded into the old server.