#1095 cleanup MIGRATION document

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

diff --git a/MIGRATION b/MIGRATION
index 81f530ecdc0f02d0164a74f4afda61e96b900ca3..4e985b49a9d086e952ba53c025f1eb3873beb047 100644 (file)
--- a/MIGRATION
+++ b/MIGRATION
@@ -31,8 +31,10 @@ a table to a view.
     that the geometry type strings will be mixed case and include the
     dimensionality modifiers. For example: PointZM, MultiLineStringZ.
     
-  * If you have views built the old constraint way or that use processing functions to return new geometries, 
-       they will not register correctly in geometry_columns.  They will all appear as Geometry with srid=0.
+  * If you have views built the old constraint way or that use processing
+    functions to return new geometries, they will not register correctly 
+    in geometry_columns.  They will all appear as Geometry with srid=0.
+    
        In order to fix this, you have to cast the geometries in the view.
        So for example, If you had a view that looked like this:
        CREATE OR REPLACE VIEW vwparcels AS
@@ -44,14 +46,19 @@ a table to a view.
                
        You will need to drop and recreate the view. 
        Sadly CREATE OR REPLACE will not work since the casting
-       makes geometries be treated as a different type as far as CREATE OR REPLACE is concerned
-       ---note for this might help to lookup in geometry_columns to see the raw table srid/type
-       Alternatively you can convert some of your table columns to typmod, then you would
-       only need to CAST when doing processing.  This however still requires you rebuild your dependent views
+       makes geometries be treated as a different type as far as CREATE OR REPLACE 
+       is concerned.
+       
+       NOTE for this, it might help to lookup in geometry_columns 
+           to see the raw table srid/type
+       Alternatively you can convert some of your table columns to typmod, 
+       then you would only need to CAST when doing processing.  This however still
+       requires you rebuild your dependent views
        DROP VIEW vwparcels;
        CREATE OR REPLACE VIEW vwparcels AS
                SELECT gid, parcel_id, 
-                       ST_Transform(geom, 26986)::geometry(MultiPolygon,26986) As geom_26986,
+                  ST_Transform(geom, 26986)::geometry(MultiPolygon,26986) 
+                     As geom_26986,
                        geom::geometry(MultiPolygon, 2249) As geom,
                        ST_Centroid(geom)::geometry(Point,2249) As cent_geom
                FROM parcels;
@@ -59,35 +66,47 @@ a table to a view.
     
 Restoring data from prior versions -- GOTCHAS
 -----------------------------------------------
-The populate_geometry_columns() function in PostGIS 1.5 and below, used the deprecated functions
-ndims() and srid() for defining constraints.  As a result these tables will not restore into a fresh PostGIS 2.0 database unless you
+The populate_geometry_columns() function in PostGIS 1.5 and below, 
+used the deprecated functions ndims() and srid() for defining constraints.  
+As a result these tables will not
+restore into a fresh PostGIS 2.0 database unless you
 
 1) Drop these contraints before you restore the data
 
 or 
 
-2) Install the legacy functions srid() and ndims() found in the legacy.sql file before you try to restore these tables.
+2) Install the legacy functions srid() and ndims() found in the legacy.sql file
+before you try to restore these tables.
 
 Function is not unique after restore
 -------------------------------------
-After you restore old data into a fresh PostGIS 2.0 database, YOU MUST install the uninstall_legacy.sql
-file after the restore.  If you don't you will run into "function is not unique" errors in your applications.
-The other issue with having the old functions is the old functions you restore will be bound to the old postgis library which is incompatible with the
+After you restore old data into a fresh PostGIS 2.0 database, 
+YOU MUST install the uninstall_legacy.sql
+file after the restore.  If you don't you will run into 
+"function is not unique" errors in your applications.
+The other issue with having the old functions is the old functions you restore
+will be bound to the old postgis library which is incompatible with the
 new postgis geometry structures.
 
-If you still require legacy functions, you can install the legacy.sql file after the uninstall_legacy.sql.
+If you still require legacy functions, you can install the legacy.sql file 
+after the uninstall_legacy.sql.
 
 GOTCHA with uninstall_legacy.sql
 --------------------------------
-The uninstall_legacy.sql will not be able to uninstall functions and will output errors detailing objects 
-using these functions that are currently being used in views and sql functions.
-If you run it in PgAdmin, the whole script will rollback not uninstalling anything. So you should run it in PSQL mode.
-If you get errors in uninstall_legacy.sql -- convert those views and sql functions to use the newer equivalent functions
+The uninstall_legacy.sql will not be able to uninstall functions and will 
+output errors detailing objects using these functions that are currently 
+being used in views and sql functions.
+
+If you run it in PgAdmin, the whole script will rollback not 
+uninstalling anything. So you should run it in PSQL mode.
+If you get errors in uninstall_legacy.sql -- convert those views and sql
+functions to use the newer equivalent functions 
 and then rerun the script again.
 
 BENCHMARK NOTES
 ------------------------------
-Querying a whole geometry_columns table of 200-240 someodd records (tables/views all constraint based)( On windows 9.1beta2)
+Querying a whole geometry_columns table of 200-240 someodd records 
+(tables/views all constraint based)( On windows 9.1beta2)
 Speed for this set of data I'm okay with though a bit slower
 I think the main issue why fancy is slower is that to get the fancy name
 I need to do a double call to get dims since fancy_name needs dims as well
@@ -108,10 +127,13 @@ SELECT * FROM geometry_columns_v where f_table_name = 'buildings_1995';
 -- these are constraint based (7 rows) -- 76 ms, 240 ms, 68 ms
 SELECT * FROM geometry_columns_v where f_table_schema = 'tiger';
 
--- CONVERTING TO Typmod as I feared is slow for tables with data.  I think it follows the same model 
+-- CONVERTING TO Typmod as I feared is slow for tables with data.  
+   I think it follows the same model 
 -- as converting varchar(100) to text or varchar(100) to varchar(300) etc.
 -- This maybe can be remedied somehow in 9.1 since it hasn't been released
 -- (haven't tried doing this exercise in 8.4, 9.0)
--- This took  36,018 ms for table of 350,572 records.  I assume it will be linear with number of records.
+-- This took  36,018 ms for table of 350,572 records.  
+I assume it will be linear with number of records.
+
 ALTER TABLE buildings_1995 ALTER COLUMN the_geom TYPE geometry(MultiPolygon,2249);