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

(1)  Optionally move the old cluster

If you are using a version-specific PostgreSQL install directory, e.g.
/opt/PostgreSQL/8.4, you do not need to move the old cluster.  The
one-click installers all use version-specific install directories.

If your PostgreSQL install directory is not version-specific, e.g.
/usr/local/pgsql, 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)  For PostgreSQL source installs, build the new PostgreSQL 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 starting the upgrade.

Migrating from 8.3.X:
Specifically, the default datetimes storage format 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 the
datetime storage formats match.


(3)  Install the new Postgres binaries

Install the new server's binaries and support files. You can use the
same port numbers for both clusters, typically 5432, because the old and
new clusters will not be running at the same time.

For source installs, if you wish to install the new server in a custom
location, use 'prefix':

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



(4)  Initialize the new PostgreSQL cluster

Initialize the new cluster using initdb.  Again, use compatible initdb
flags that match the old cluster (pg_migrator will check that too.) Many
prebuilt installers do this step automatically.  There is no need to
start the new cluster.

If migrating EnterpriseDB's Postgres Plus Advanced Server, you must:

	o  _not_ install "sample tables and procedures/functions"
	   in the new server
	o  delete the empty 'edb' schema in the 'enterprisedb' database
	o  copy dbserver/lib/pgmemcache.so from the old server
	   to the new server  (AS8.3 to AS8.3R2 migrations only)


(5)  Install custom shared object files (or DLLs)

Install any custom shared object files (or DLLs) used by the old cluster
into the new cluster, e.g. pgcrypto.so, whether they are from /contrib
or some other source.  Do not install the schema definitions, e.g.
pgcrypto.sql --- these will be migrated from the old cluster.


(6)  Adjust authentication

pg_migrator will connect to the old and new servers several times, so
you might want to set authentication to 'trust' in pg_hba.conf, or if
using 'md5' authentication, use a 'pgpass' file to avoid being prompted
repeatedly for a password.


(7)  Build pg_migrator

For pg_migrator source installs, keep in mind the compile must use the
_new_ PostgreSQL source directory and be installed in the new Postgres
install directory.

The simplest build option is to use PGXS:

	gmake USE_PGXS=1 PG_CONFIG=/usr/local/pgsql/bin/pg_config install


Another option is to point to the top of the new PostgreSQL source tree
by running something like:

	gmake top_builddir=/usr/src/pgsql install

Replace '/usr/src/pgsql' with your new source directory.  pg_migrator
also understands the 'prefix=' specification if you installed Postgres
in a custom location.


(8)  Install pg_migrator

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).

If using prebuilt binaries, copy them to the proper locations, e.g for
Unix:

	cp pg_migrator /opt/PostgreSQL/8.5/bin
	cp pg_migrator.so  /opt/PostgreSQL/8.5/lib
	cp pg_migrator_sysoids.so  /opt/PostgreSQL/8.5/lib

for for Windows:

	COPY pg_migrator.exe "C:\Program Files\PostgreSQL\8.5\bin"
	COPY pg_migrator.dll "C:\Program Files\PostgreSQL\8.5\lib"
	COPY pg_migrator_sysoids.dll "C:\Program Files\PostgreSQL\8.5\lib"

If building from source, 'gmake install' should install the files into
the proper locations in the new cluster.


(9)  Stop both servers

Make sure both database servers are stopped using on Unix, e.g.:

	pg_ctl --pgdata /opt/PostgreSQL/8.4 stop
	pg_ctl --pgdata /opt/PostgreSQL/8.5 stop

or on Windows:

        NET STOP postgresql-8.4
        NET STOP postgresql-8.5


(10)  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 once you start the new cluster after the upgrade.  See
pg_migrator --help for a full list of options.

For Windows users, you must be logged into an administrative account, and
then start a shell as the 'postgres' user and set the proper path:

	RUNAS /USER:postgres "CMD.EXE"
	SET PATH=%PATH%;C:\Program Files\PostgreSQL\8.5\bin;

and then run pg_migrator with quoted directories, e.g.:

	pg_migrator.exe
		--old-datadir "C:/Program Files/PostgreSQL/8.4/data"
		--new-datadir "C:/Program Files/PostgreSQL/8.5/data"
		--old-bindir  "C:/Program Files/PostgreSQL/8.4/bin"
		--new-bindir  "C:/Program Files/PostgreSQL/8.5/bin"

Once started, 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, even if the old server is still running.  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.

If an error occurs while restoring the database schema, pg_migrator will
exit and you will have to revert to the old cluster as outlined in step
#15 below.  To try pg_migrator again, you will need to modify the old
cluster so the pg_migrator schema restore succeeds.  If the problem is a
/contrib module, you might need to uninstall the /contrib module from
the old cluster and install it in the new cluster after the migration,
assuming the module is not being used to store user data.


(11)  Restore pg_hba.conf

If you modified pg_hba.conf to use 'trust', restore its original
authentication settings.


(12)  Post-Migration processing

If any post-migration processing is required, pg_migrator will issue
warnings as it completes.  It will also generate script files that must
be run by the administrator.  The script files will connect to each
database that needs post-migration processing.  Each script should be
run using:

	psql --username postgres --file script.sql postgres

The scripts can be run in any order and can be deleted once they have
been run.

In general it is unsafe to access tables referenced in rebuild scripts
until the rebuild scripts have run to completion;  doing so could yield
incorrect results or poor performance.  Tables not referenced in rebuild
scripts can be accessed immediately.


(13)  Statistics

Because optimizer statistics and free space information is not
transferred by pg_migrator, consider running "vacuumdb --all --analyze".


(14) Delete old cluster

You can delete the old Postgres installation, including old tablespace
directories, once you are satisfied with the upgrade.


(15)  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 or did not start the new server,
the old cluster was not modified except that an ".old" suffix was
appended to $PGDATA/global/pg_control and tablespace directories.  To
reuse the old cluster, remove the tablespace directories created by the
new cluster and remove the ".old" suffix from $PGDATA/global/pg_control
and the old cluster tablespace directory names; then you can restart the
old cluster.

