pg_migrator Usage
-----------------

1.  Move the old cluster

It is necessary to move the current Postgres install directory so it
does not interfere with the new Postgres installation.  Once the current
Postgres server is shut down, it is safe to rename the Postgres install
directory.  Assuming the old directory is /usr/local/pgsql, you can do:

	mv /usr/local/pgsql /usr/local/pgsql.old

to rename the directory.


2.  Build the new Postgres version

Build the new Postgres source with configure flags that are compatible
with the old cluster.  pg_migrator will check pg_controldata to make
sure all settings are compatible before doing the upgrade.

8.3.X -> 8.4.X:
Specifically, the default storage format for datetimes changed between
8.3.X and 8.4.X, so if you used the default datetimes storage setting
in 8.3, you will need to run configure with
--disable-integer-datetimes so datetime storage matches.


3.  Install the new Postgres binaries

You will need to install the new server's binaries and support files. If
you wish to install the new server in a custom location, use 'prefix=':

	gmake prefix=/usr/local/pgsql.new install

You can use the same port numbers for both clusters, typically 5432,
because both clusters will not be running at the same time.


4.  Install pg_migrator

There are several ways to build pg_migrator.  Keep in mind the compile
must use the _new_ PostgreSQL source directory and be installed in the
new Postgres install directory.

While it doesn't matter where the pg_migrator executable is installed,
the pg_migrator shared object file (pg_migrator.so) must be installed in
the new cluster's library directory (e.g. /usr/local/pgsql/lib).

The simplest build option is to point to the top of the PostgreSQL
source tree by running something like:

	gmake top_builddir=/usr/src/pgsql install

Replace '/usr/src/pgsql' with your source directory.  pg_migrator also
understands the 'prefix=' specification if you installed Postgres in a
custom location.  Another build option is to copy the pg_migratory
directory into contrib/pg_migrator in the new PostgreSQL source tree and
run a simple 'gmake install'.  A third install method is to use PGXS
(assuming the new 'pg_config' is in your $PATH):

	USE_PGXS=1 gmake prefix=/usr/local/pgsql.new install



5.  Initialize the new cluster

Initialize the new cluster using initdb.  Again, use compatible initdb
flags that match the old cluster (pg_migrator will check that too.)
There is no need to start the new cluster.

pg_migrator will connect to both old and new databases several times, so
if you are using password authentication, you might want to create a
pgpass file in your home directory to avoid being prompted repeatedly
for a password.


6.  Run pg_migrator

pg_migrator requires the specification of the old and new cluster's
PGDATA and executable (/bin) directories.  You can also specify separate
user and port values, and whether you want the data linked instead of
copied (the default).  If you use linking, the migration will be much
faster (no data copying), but you will no longer be able to access your
old cluster after the upgrade.  See pg_migrator --help for a full list
of options.

pg_migrator will verify the two clusters are compatible and then do the
migration.  You can use pg_migrator --check to perform only the checks.
pg_migrator --check will also outline any manual adjustments you will
need to make after the migration.

Obviously, no one should be accessing the clusters during the migration.


7.  Cleanup

Any manual cleanup necessary will be reported when pg_migrator
completes.  You can delete the old Postgres installation once you are
satisfied with the upgrade.


8.  Reverting to old cluster

If, after running pg_migrator, you wish to revert to the old cluster,
there are several options.

If you ran pg_migrator with --check, no modifications were made to the
old cluster and you can re-use it anytime.

If you ran pg_migrator with --link, the data files are shared between
the old and new cluster.  If you started the new cluster, the new server
has written to those shared files and it is unsafe to use the old
cluster.

If you ran pg_migrator _without_ --link, the old cluster was not
modified except that the tablespaces directories were renamed ".old". 
To reuse the old cluster, remove the tablespace directories created by
the new cluster and remove the ".old" prefix from the old cluster
tablespace directory names; then you can restart the old cluster.
