Modified upgrade section to show postgis_restore.pl based procedure.

git-svn-id: http://svn.osgeo.org/postgis/trunk@1475 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/README.postgis b/README.postgis
index e32e503de4139d89715c48b4e81aa3f87806039e..12163a4764531381cdc9d28db4abe9177c8bb86a 100644 (file)
--- a/README.postgis
+++ b/README.postgis
@@ -95,22 +95,54 @@ UPGRADING:
 
 Upgrading PostGIS can be tricky, because the underlying C libraries which 
 support the object types and geometries may have changed between versions.
-To avoid problems when upgrading, you will have to dump all the tables
-in your database, destroy the database, create a new one, add the PL/pgSQL
-language, upload the new postgis.sql file, then upload your database dump:
 
-  pg_dump -t "*" -f dumpfile.sql yourdatabase
-  dropdb yourdatabase
-  createdb yourdatabase
-  createlang plpgsql yourdatabase
-  psql -f lwpostgis.sql -d yourdatabase
-  psql -f dumpfile.sql -d yourdatabase
-  vacuumdb -z yourdatabase
-
-You might find the utils/postgis_restore.pl useful. It will
-automatically create a new db, feed it the  lwpostgis.sql file
-and restore all but postgis objects from a 'custom' dump.
-Run with no args to have a usage string printed.
+For this purpose PostGIS provides an utility script to restore a dump
+produced with the pg_dump -Fc command. It is experimental so redirecting
+its output to a file will help in case of problems. The procedure is
+as follow:
+
+       # Create a "custom-format" dump of the database you want
+       # to upgrade (let's call it "olddb")
+       $ pg_dump -Fc olddb olddb.dump
+
+       # Restore the dump contextually upgrading postgis into
+       # a new database. The new database doesn't have to exist.
+       # Let's call it "newdb"
+       $ sh utils/postgis_restore.pl lwpostgis.sql newdb olddb.dump > restore.log
+
+       # Check that all restored dump objects really had to be restored from dump
+       # and do not conflict with the ones defined in lwpostgis.sql
+       $ grep ^KEEPING restore.log | less
+
+       # If upgrading from PostgreSQL < 7.5 to >= 7.5 you might want to 
+       # drop the attrelid, varattnum and stats columns in the geometry_columns
+       # table, which are no-more needed. Keeping them won't hurt.
+       # !!! DROPPING THEM WHEN REALLY NEEDED WILL DO HURT !!!!
+       $ psql newdb -c "ALTER TABLE geometry_columns DROP attrelid"
+       $ psql newdb -c "ALTER TABLE geometry_columns DROP varattnum"
+       $ psql newdb -c "ALTER TABLE geometry_columns DROP stats"
+
+       # spatial_ref_sys table is restore from the dump, to ensure your custom
+       # additions are kept, but the distributed one might contain modification
+       # so you should backup your entries, drop the table and source the new one.
+       # If you did make additions we assume you know how to backup them before
+       # upgrading the table. Replace of it with the new one is done like this:
+       $ psql newdb
+       newdb=> drop table spatial_ref_sys;
+       DROP
+       newdb=> \i spatial_ref_sys.sql
+
+Following is the "old" procedure description. IT SHOULD BE AVOIDED if possible,
+as it will leave in the database many spurious functions. It is kept in this document
+as a "backup" in case postgis_restore.pl won't work for you:
+
+       pg_dump -t "*" -f dumpfile.sql yourdatabase
+       dropdb yourdatabase
+       createdb yourdatabase
+       createlang plpgsql yourdatabase
+       psql -f lwpostgis.sql -d yourdatabase
+       psql -f dumpfile.sql -d yourdatabase
+       vacuumdb -z yourdatabase
 
 
 USAGE: