PostGIS - Geographic Information Systems Extensions to PostgreSQL
-~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================================================================
-VERSION: 2.0.0beta2 (YYYY/MM/DD)
+:Version: 2.0.0
+: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 many 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.
- ./utils Utility scripts for PostGIS (upgrade, profiling, ...)
- ./extras Various pieces that didn't belong to mainstream
- (package management specfiles, WFS_locks, sample wkb parser)
+ ./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
- ./extensions Files to support the PostgreSQL 9.1+ "extensions" framework
+ ./topology PostGIS topology extension source code
+ ./utils Utility scripts for PostGIS (upgrade, profiling, ...)
REQUIREMENTS
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 currently used to import GeoJSON via the function
- ST_GeomFromGeoJson. JSON-C is available for download from
+ JSON-C is used to import GeoJSON via the function ST_GeomFromGeoJson().
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.
+By default, both Topology and Raster extensions are enabled in ``./configure``.
-If you want to compile PostGIS with Raster support, you must provide
-the --with-raster option.
+If you want to compile PostGIS *without* Raster support, you must provide the
+``--without-raster`` option.
-If you want to compile PostGIS with Topology support, you must provide
-the --with-topology option.
+If you want to compile PostGIS *without* Topology support, you must provide the
+``--without-topology`` option.
+
+See ``./configure --help`` for more options.
-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 <yourdatabase>
psql -f postgis/postgis.sql -d <your_database>
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 <filename>legacy.sql</filename> 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 <filename>uninstall_legacy.sql</filename>.
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
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 <indexname>
- ON <tablename>
+ CREATE INDEX <indexname>
+ ON <tablename>
USING GIST ( <geometryfield> );
-Always run the "VACUUM ANALYZE <tablename>" on your tables after
-creating an index. This gathers statistics which the query planner
-uses to optimize index usage.
+Always run the ``VACUUM ANALYZE <tablename>`` 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.
projects / postgis / commitdiff