postgis/README.postgis

PostGIS - Geographic Information Systems Extensions to PostgreSQL
~~~~~~~   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

VERSION: 0.6 (2001/09/20)

MORE INFORMATION: http://postgis.refractions.net

INTRODUCTION:
This distribution contains a module which implements GIS simple features, ties 
the features to rtree indexing, and provides some basic functions for accessing 
and analyzing geographic data.

Directory structure:

  ./      Core source code, makefiles and install directions.
  ./jdbc  Extensions to the PostgreSQL JDBC drivers to support
          the GIS objects. 
  ./doc   Documentation on the code, objects and functions 
          provided. 
  ./loader  A program to convert ESRI Shape files into SQL text
          suitable for uploading into a PostGIS/PostgreSQL database.
  ./examples  Small programs which demonstrate ways of accessing 
          GIS data.
	        

INSTALLATION:

To install the module, move this directory to the "contrib" directory of your
PostgreSQL source installation. Alternately, edit the "top_buildir" in the 
Makefile and point it at your PostgreSQL source tree. You must have a 
PostgreSQL source tree, and you must have run succesfully built and installed
it for this to work.

Then run:
	
  make
  make install

PostGIS now requires the PL/pgSQL procedural language in order to operate
correctly. To install PL/pgSQL, locate the plpgsql.so library in your
PostgreSQL installation (usually in the 'lib' directory). Then run the
following SQL commands in your database, replacing the plpgsql.so 
location with the correct one for your system:

  CREATE FUNCTION plpgsql_call_handler() 
     RETURNS OPAQUE AS '/usr/local/pgsql/lib/plpgsql.so' 
     LANGUAGE 'C';
  CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
     HANDLER plpgsql_call_handler
     LANCOMPILER 'PL/pgSQL';

Finally, load the function and object definitions into your database 
with psql (you must run this as a database user with system privledges):

  psql -f postgis.sql -d yourdatabase

Installation should be complete.


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, upload the
new postgis.sql file, then upload your database dump:

  pg_dump -t "*" -f dumpfile.sql yourdatabase
  dropdb yourdatabase
  createdb yourdatabase
  psql -f postgis.sql -d yourdatabase
  psql -f dumpfile.sql -d yourdatabase
  vacuumdb -z yourdatabase

When upgrading to 0.6, all your geometries will be created with an SRID
of -1. To create valid OpenGIS geometries, you will have to create a 
valid SRID in the SPATIAL_REF_SYS table, and then update your geometries
to reference the SRID with the following SQL (with the appropriate
substitutions:

  UPDATE TABLE <table> SET <geocolumn> = SetSRID(<geocolumn>,<SRID>);


USAGE:

Try the following example SQL statements to create non-OpenGIS tables and 
geometries:

  CREATE TABLE geom_test ( gid int4, geom geometry,name varchar(25) );
  INSERT INTO geom_test ( gid, geom, name ) 
    VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square');
  INSERT INTO geom_test ( gid, geom, name ) 
    VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' );
  INSERT INTO geom_test ( gid, geom, name )
    VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' );
  SELECT * from geom_test WHERE geom && 'BOX3D(2 2 0,3 3 0)'::box3d;

The following SQL creates proper OpenGIS entries in the SPATIAL_REF_SYS
and GEOMETRY_COLUMNS tables, and ensures that all geometries are created
with an SRID.

  INSERT INTO SPATIAL_REF_SYS
    ( SRID, AUTH_NAME, AUTH_SRID, SRTEXT ) VALUES
    ( 1, 'EPSG', 4269,
      'GEOGCS["NAD83",
        DATUM[
          "North_American_Datum_1983",
          SPHEROID[
          "GRS 1980",
          6378137,
          298.257222101
        ]
      ],
      PRIMEM["Greenwich",0],
      UNIT["degree",0.0174532925199433]]'
    );

  CREATE TABLE geotest (
    id INT4,
    name VARCHAR(32)
    );

  SELECT AddGeometryColumn('db','geotest','geopoint',1,'POINT',2);

  INSERT INTO geotest (id, name, geopoint)
    VALUES (1, 'Olympia', GeometryFromText('POINT(-122.90,46.97)',1));
  INSERT INTO geotest (id, name, geopoint)
    VALUES (2, 'Renton', GeometryFromText('POINT(-122.22,47.50)',1));

  SELECT name,AsText(geopoint) FROM geotest;


RTREE vs GIST:

PostgreSQL provides support for GiST indexing. The GiST scheme offers 
indexing even on large objects, using a system of "lossy" indexing where 
a large object is proxied by a smaller one in the index.  In the case 
of the PostGIS indexing system, all objects are proxied in the index by 
their bounding boxes.

You can build a GiST index with:

  CREATE INDEX <indexname> ON <tablename>  
     USING gist ( <geometryfield> gist_geometry_ops ) WITH ( islossy );

Note that PostgreSQL may not use the GiST indexes when performing 
searches unless *forced* to do so. If you find your system is not
using the indexes automatically (use 'EXPLAIN' to see the query plan)
you can force index use with the command: 

  SET ENABLE_SEQSCAN = OFF

Try doing an EXPLAIN on your query before and after the 'enable_seqscan'
command to see the different query plans.