Index: README.postgis =================================================================== --- README.postgis (revision 9477) +++ README.postgis (working copy) @@ -1,35 +1,35 @@ PostGIS - Geographic Information Systems Extensions to PostgreSQL -~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================================================= -VERSION: 2.0.0beta2 (YYYY/MM/DD) +:Version: 2.0.0beta2 +:Date: YYYY-MM-DD +:Website: http://postgis.org -MORE INFORMATION: http://postgis.org +This distribution contains a module which implements GIS simple features, ties +the features to R-tree indexing, and provides some spatial functions for +accessing and analyzing geographic data. -This distribution contains a module which implements GIS simple -features, ties the features to rtree indexing, and provides some -spatial functions for accessing and analyzing geographic data. +Directory structure:: -Directory structure: - - ./ Build scripts and install directions. - ./liblwgeom LWGEOM geometry library. - ./postgis PostGIS library source code. - ./raster PostGIS rasters support source code. - ./topology PostGIS topology source code. + ./ Build scripts and install directions + ./doc PostGIS Documentation + ./extensions Support for the PostgreSQL 9.1+ Extensions framework + ./extras Various pieces that didn't belong to mainstream + (package management specfiles, WFS_locks, sample WKB parser) ./java/ejb EJB Java support ./java/jdbc Extensions to the PostgreSQL JDBC drivers to support - the GIS objects. + the GIS objects ./java/pljava PostgreSQL PL/Java spatial object support - ./doc PostGIS Documentation - ./loader A program to convert ESRI Shape files into SQL text - suitable for uploading into a PostGIS/PostgreSQL database - and a program for converting PostGIS spatial tables into - Shape files. + ./liblwgeom LWGEOM geometry library + ./libpgcommon PostGIS library to bridge LWGEOM to PostgreSQL + ./loader A program to convert ESRI Shape files into SQL text suitable + for uploading into a PostGIS/PostgreSQL database and a program + for converting PostGIS spatial tables into shapefiles + ./postgis PostGIS library source code + ./raster PostGIS rasters extension source code + ./regress Online regression tests + ./topology PostGIS topology extension source code ./utils Utility scripts for PostGIS (upgrade, profiling, ...) - ./extras Various pieces that didn't belong to mainstream - (package management specfiles, WFS_locks, sample wkb parser) - ./regress Online regression tests - ./extensions Files to support the PostgreSQL 9.1+ "extensions" framework REQUIREMENTS @@ -37,253 +37,247 @@ PostGIS is compatible with PostgreSQL 8.4 and above. -You *must* have the full PostgreSQL - including server headers - installed -for this to work. +You *must* have the full PostgreSQL - including server headers - installed for +this to work. -* PROJ4 SUPPORT (Required, Version 4.6.0 or higher): +* PROJ4 (Required, Version 4.6.0 or higher): - The Proj4 reprojection library is required if you want to use the - transform() function to reproject features within the database. + The PROJ4 catographic projection library is required if you want to use the + ST_Transform() function to reproject features within the database. http://trac.osgeo.org/proj/ -* SPATIAL PREDICATE / GEOS SUPPORT (Required, Version 3.2.2 or higher): +* GEOS (Required, Version 3.2.2 or higher): - The GEOS library provides support for exact topological tests - such as Touches(), Contains(), Disjoint() and spatial operations - such as Intersection(), Union() and Buffer(). GEOS 3.3.2 or higher - is recomended. + The GEOS library provides support for exact topological tests such as + ST_Touches(), ST_Contains(), ST_Disjoint() and spatial operations such as + ST_Intersection(), ST_Union() and ST_Buffer(). GEOS 3.3.2 or higher is + recommended. http://trac.osgeo.org/geos/ -* XML SUPPORT (Required, Version 2.5.0 or higher): +* XML SUPPORT (Required, Version 2.5.0 or higher): - The LibXML2 library is required to use the ST_GeomFromGML() and + The LibXML2 library is required to use the ST_GeomFromGML() and ST_GeomFromKML() functionality. http://xmlsoft.org/ * GNU gettext - The loader, and hence postgis, requires GNU gettext 0.14 or higher + The loader, and hence PostGIS, requires GNU gettext 0.14 or higher (typically in libc on GNU/Linux, in which case 0.17 is required). -If you want to compile PostGIS with GeoJSON support, you additionally -must have installed: +* JSON-C (Required, Version 0.9 or higher) -* JSON-C (Version 0.9 or higher) + JSON-C is used to import GeoJSON via the function ST_GeomFromGeoJson(). - JSON-C is currently used to import GeoJSON via the function - ST_GeomFromGeoJson. JSON-C is available for download from - http://oss.metaparadigm.com/json-c/. - You can get it installed in apt-based systems using: + You can get it installed in apt-based systems using:: apt-get install libjson0-dev -If you want to compile PostGIS with raster support, you additionally -must have installed: +* GDAL (Optional, Version 1.6.0 or higher) -* GDAL (Version 1.6.0 or higher) + GDAL is required if you want to compile PostGIS with raster support. -* Python GDAL bindings + http://www.gdal.org/ See README.raster for further information on how to compile PostGIS with Raster support. + CONFIGURATION ------------- -To configure PostGIS, run: - +To configure PostGIS, run:: + ./configure The results of the configuration can be easily seen within the -postgis_config.h file. +``postgis_config.h`` file. -If pg_config can't be found in your $PATH configure will complain -and refuse to proceed. You can specify it using the ---with-pgconfig=/path/to/pg_config flag. +If ``pg_config`` can't be found in your ``$PATH`` configure will complain +and refuse to proceed. You can specify it using the +``--with-pgconfig=/path/to/pg_config`` flag. -If PROJ4 has been installed (but cannot be found), configure will -complain and refuse to proceed. You can specify an alternative -installation directory using the --with-projdir=DIR option. +If PROJ4 has been installed but cannot be found, configure will complain and +refuse to proceed. You can specify an alternative installation directory using +the ``--with-projdir=DIR`` option. -If GEOS has been installed (but cannot be found), configure will -complain and refuse to proceed. You can specify an alternative -geos-config file using the --with-geosconfig=/path/to/geos-config -option. +If GEOS has been installed but cannot be found, configure will complain and +refuse to proceed. You can specify an alternative ``geos-config`` file using +the ``--with-geosconfig=/path/to/geos-config`` option. -If you want to compile PostGIS with Raster support, you must provide -the --with-raster option. +By default, both Topology and Raster extensions are enabled in ``./configure``. -If you want to compile PostGIS with Topology support, you must provide -the --with-topology option. +If you want to compile PostGIS *without* Raster support, you must provide the +``--without-raster`` option. -See ./configure --help for more options. +If you want to compile PostGIS *without* Topology support, you must provide the +``--without-topology`` option. +See ``./configure --help`` for more options. + + BUILD ----- -PostGIS uses the GNU make (aka gmake) for building. -To build PostGIS library and utilities, as postgres run: +PostGIS uses the GNU make (aka gmake) for building. To build PostGIS library +and utilities, as postgres run:: make See README.raster to know how to build PostGIS Raster extension. + TESTING ------- -You want to run regress tests before installation. -To do so, as postgres run: +You want to run regress tests before installation. To do so, as postgres run:: - make check + make check -The above will create a test database with postgis extensions, -run tests and then drop the db. +The above will create a test database with PostGIS extensions, run tests and +then drop the test database. -Final lines of output contain a summary of test results: -run, succeeded, failed. If you have any failure please -file a bug report using the online bug tracker: -http://trac.osgeo.org/postgis/report/3. +Final lines of output contain a summary of test results: run, succeeded, +failed. If you have any failure please file a bug report using the online bug +tracker: http://trac.osgeo.org/postgis/report/3 See README.raster to know how to test PostGIS raster extension. - + INSTALLATION ------------ -To install PostGIS library and utilities, as postgres run: +To install PostGIS library and utilities, as postgres run:: make install +Installation paths will typically be derived by ``pg_config``: -Installation paths will typically be derived by ``pg_config'': + - Lib in ``pg_config --pkglibdir`` + - Binaries (loader/dumper) in ``pg_config --bindir`` + - Important support files in ``[prefix]/share/contrib`` + - Manual pages in ``[prefix]/man`` + - Documentation in in ``[prefix]/share/doc`` - - Lib in `pg_config --pkglibdir` - - Binaries (loader/dumper) in `pg_config --bindir` - - Important support files in [prefix]/share/contrib - - Manual pages in [prefix]/man - - Documentation in in [prefix]/share/doc +Where `[prefix]` above is extracted from ``pg_config --configure``. -Where [prefix] above is extracted by `pg_config --configure`. +You can change them using ``./configure`` switches. See CONFIGURATION section. -You can change them using ./configure switches. -See CONFIGURATION section. - See README.raster to know how to install PostGIS Raster extension. + CREATING NEW SPATIAL DATABASES ------------------------------ -PostGIS support must be enabled for each database that requires -its usage. This is done by feeding the postgis.sql (the enabler script) -file to the target database. +PostGIS support must be enabled for each database that requires its usage. +This is done by feeding the ``postgis.sql`` (the enabler script) file to the +target database. -The enabler script requires the PL/pgSQL procedural language in order -to operate correctly, you can use the 'createlang' program from the -PostgreSQL installation. +The enabler script requires the PL/pgSQL procedural language in order to +operate correctly, you can use the ``createlang`` program from the PostgreSQL +installation. + (The PostgreSQL Programmer's Guide has details if you want to do this manually for some reason.) -So, as postgres run: +So, as postgres run:: createlang plpgsql psql -f postgis/postgis.sql -d Your database should now be spatially enabled. + UPGRADING EXISTING SPATIAL DATABASES ------------------------------------ -Upgrading existing spatial databases can be tricky as it requires -replacement or introduction of new PostGIS object definitions. +Upgrading existing spatial databases can be tricky as it requires replacement +or introduction of new PostGIS object definitions. -Unfortunately not all definitions can be easily replaced in -a live database, so sometimes your best bet is a dump/reload -process. +Unfortunately not all definitions can be easily replaced in a live database, so +sometimes your best bet is a dump/reload process. -PostGIS provides a SOFT UPGRADE procedure for minor or bugfix -releases, and an HARD UPGRADE procedure for major releases. +PostGIS provides a SOFT UPGRADE procedure for minor or bugfix releases, and an +HARD UPGRADE procedure for major releases. ---- SOFT UPGRADE --- +SOFT UPGRADE +~~~~~~~~~~~~ +Soft upgrade consists of sourcing the ``postgis_upgrade_*.sql`` script in your +spatial database: -Soft upgrade consists of sourcing the postgis_upgrade_*.sql -script in your spatial database: + * ``postgis_upgrade_13_to_15.sql``, upgrade a 1.3.x database to 1.5 + * ``postgis_upgrade_15_to_15.sql``, upgrade a 1.4.x database to 1.5 + * ``postgis_upgrade_16_minor.sql``, upgrade a 1.5.x database to the latest + minor release - * postgis_upgrade_13_to_15.sql, upgrade a 1.3.x database - to 1.5 - * postgis_upgrade_15_to_15.sql, upgrade a 1.4.x database - to 1.5 - * postgis_upgrade_16_minor.sql, upgrade a 1.5.x database - to the latest minor release +If a soft upgrade is not possible the script will abort and no harm will be +done. You can then move on to the HARD UPGRADE process. Always try a soft +upgrade first; they are much simpler. -If a soft upgrade is not possible the script will abort and -no harm will be done. You can then move on to the -HARD UPGRADE process. Always try a soft upgrade first, they -are much simpler. +HARD UPGRADE +~~~~~~~~~~~~ ---- HARD UPGRADE --- +Hard upgrade is a PostgreSQL dump/restore procedure combined with a filter to +selectively update PostGIS functions and objects to point to a new library +version. -Hard upgrade is a PostgreSQL dump/restore procedure combined -with a filter to selectively update PostGIS functions and -objects to point to a new library version. +Hard upgrades are required when object definitions have changed, aggregates +have changed or been added, and when the underlying PostgreSQL database itself +has undergone a major update. -Hard upgrades are required when object definitions have changed, -aggregates have changed or been added, and when the underlying -PostgreSQL database itself has undergone a major update. +For this purpose, PostGIS provides a utility script to restore a dump in +"custom" format. The hard upgrade procedure is as follows:: -For this purpose, PostGIS provides a utility script to restore a dump -in "custom" format. The hard upgrade procedure is as follows: + # [1] Create a "custom-format" dump of the database you want + # to upgrade (let's call it "olddb") + $ pg_dump -Fc -f olddb.dump olddb - # [1] Create a "custom-format" dump of the database you want - # to upgrade (let's call it "olddb") - $ pg_dump -Fc -f olddb.dump olddb + # [2] Do a fresh install of PostGIS in a new database + # (let's call it "newdb"). + # Refer to CREATING NEW SPATIAL DATABASES for instructions - # [2] Do a fresh install of PostGIS in a new database - # (let's call it "newdb"). - # Refer to CREATING NEW SPATIAL DATABASES for instructions + # [3] Restore the dump into your new database. + $ perl utils/postgis_restore.pl -v olddb.dump \ + 2> restore.log | psql newdb 2> errors.txt - # [3] Restore the dump into your new database. - $ perl utils/postgis_restore.pl -v olddb.dump \ - 2> restore.log | psql newdb 2> errors.txt +The ``spatial_ref_sys`` entries found in your dump will be restored, but they +will not override existing ones in ``spatial_ref_sys``. This is to ensure that +fixes in the official set will be properly propagated to restored databases. +If for any reason you really want your own overrides of standard entries just +don't load the ``spatial_ref_sys.sql`` file when creating the new database. -The spatial_ref_sys entries found in your dump will be restored, but -they will not override existing ones in spatial_ref_sys. This is to -ensure that fixes in the official set will be properly propagated to -restored databases. If for any reason you really want your own overrides -of standard entries just don't load the spatial_ref_sys.sql file when -creating the new db. +If your database is really old or you know you've been using long deprecated +functions in your views and functions, you might need to load ``legacy.sql`` +before restoring the dump for all your functions and views etc. to properly +come back. Only do this if *really* needed. Consider upgrading your views and +functions before dumping instead, if possible. The deprecated functions can be +later removed by loading ``uninstall_legacy.sql``. -If your database is really old or you know you've been using long -deprecated functions in your views and functions, you might need -to load legacy.sql before restoring the dump -for all your functions and views etc. to properly come back. Only do -this if _really_ needed. Consider upgrading your views and functions -before dumping instead, if possible. The deprecated functions can be -later removed by loading uninstall_legacy.sql. USAGE ----- -Try the following example SQL statements to create non-OpenGIS tables and -geometries: +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 ) + 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 ) + 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. +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 @@ -306,34 +300,37 @@ name VARCHAR(32) ); - SELECT AddGeometryColumn('db','geotest','geopoint',1,'POINT',2); + SELECT AddGeometryColumn('db', 'geotest', 'geopoint', 1, 'POINT', 2); INSERT INTO geotest (id, name, geopoint) - VALUES (1, 'Olympia', GeometryFromText('POINT(-122.90 46.97)',1)); + 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)); + VALUES (2, 'Renton', GeometryFromText('POINT(-122.22 47.50)', 1)); - SELECT name,AsText(geopoint) FROM geotest; + SELECT name, AsText(geopoint) FROM geotest; ---- Spatial Indexes --- +Spatial Indexes +~~~~~~~~~~~~~~~ -PostgreSQL provides support for GiST spatial 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. +PostgreSQL provides support for GiST spatial 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: +You can build a GiST index with:: - CREATE INDEX - ON + CREATE INDEX + ON USING GIST ( ); -Always run the "VACUUM ANALYZE " on your tables after -creating an index. This gathers statistics which the query planner -uses to optimize index usage. +Always run the ``VACUUM ANALYZE `` on your tables after creating an +index. This gathers statistics which the query planner uses to optimize index +usage. ---- PostGIS Raster support --- +PostGIS Raster support +~~~~~~~~~~~~~~~~~~~~~~ -See README.raster to know how to enable raster support on a spatially enabled database. +See README.raster to know how to enable raster support on a spatially enabled +database.