Skip to content


Subversion checkout URL

You can clone with
Download ZIP
mirror of official svn. synchronized hourly.
C Java Perl Python Shell

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
doc Add Jose and Even to credits
extensions remove more obsolete protos in docs and up extension alpha version nu…
extras more revisions to cross streets logic -- don't rely on start point wo…
java - removed a few compile errors from the javadoc build
liblwgeom ST_AddPoint returns incorrect result on Linux (#1335) from roualt
libpgcommon Remove redundant prototype
loader Fix 'clean' rule under loader to drop stuff under .libs
macros Now for sure.
postgis Have ST_Estimated_Extent return NULL when no stats are found for a ta…
raster Added rt_raster_set_pixel_line for use when setting values for sequen…
topology topology.AddToSearchPath: quote database identifier.
utils Renaming of 3D functions, #817
.gitignore Ignore more generated files
COPYING Initial revision
CREDITS clean up credits a bit
ChangeLog Some function renaming: lwgeom_typename => lwtype_name. The internal … xsl to generate postgis cheatsheet, add make cheatsheet to gnumake, b…
HOWTO_RELEASE #1063 - add update website with released doc version to HOWTO_RELEASE…
LICENSE.TXT update license to provide detail about documentation license and copy…
MIGRATION more column width cleanup
NEWS Add Jose and Even to credits
README.postgis README files updated with the new raster extension information.
README.raster Fixes on PostGIS Raster debug system. The raster core uses
STYLE forgot to save last change
TODO remove ST_Maxdistance from TODO and note that C-version is still TODO…
Version.config Push version numbers on trunk forward to next release. Check astyle version prior to do anything. 'blessed' version is 1.23.…
authors.svn Add Bborie Park to development team lists. Assume Paul, you've given … Can't put backslash-commands in 'echo' parameter in a standard way
config.rpath Added a flag --with-raster-dblwarning so as to provide the software b…
install-sh Newer script (2009 rather than 2006). Hoping others' won't have it up… Add comment about postgis_comments.sql handling in 'clean' target of … Add ST_GeomFromGeoJSON (#376)
spatial_ref_sys.sql Change parameter order in 900913 (magic!)


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



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:

  ./            Build scripts and install directions.
  ./liblwgeom   LWGEOM access library.
  ./postgis     PostGIS library source code.
  ./java/ejb    EJB Java support
  ./java/jdbc   Extensions to the PostgreSQL JDBC drivers to support
                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)
  ./regress     Regression tests


PostGIS is compatible with PostgreSQL 8.3 and above.

You *must* have the full PostgreSQL - including server headers - installed
for this to work. 

* PROJ4 SUPPORT (Required, Version 4.5.0 or better): 

  The Proj4 reprojection library is required if you want to use the 
  transform() function to reproject features within the database.

* SPATIAL PREDICATE / GEOS SUPPORT (Required, Version 3.1.1 or better):

  The GEOS library provides support for exact topological tests
  such as Touches(), Contains(), Disjoint() and spatial operations
  such as Intersection(), Union() and Buffer().

* XML SUPPORT (Required): 

  The LibXML2 library is required to use the ST_GeomFromGML() and 
  ST_GeomFromKML() functionality.

If you want to compile PostGIS with raster support, you additionally 
must have installed:

* GDAL (Version 1.6.0 or higher)

* Python GDAL bindings

See README.raster for further information on how to compile PostGIS with
Raster support.


To configure PostGIS, run:

The results of the configuration can be easily seen within the
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 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 

If you want to compile PostGIS with Raster support, you must provide
the --with-raster option.

See ./configure --help for more options.


PostGIS uses the GNU make (aka gmake) for building. 
To build PostGIS library and utilities, as postgres run:


See README.raster to know how to build PostGIS Raster extension.


You want to run regress tests before installation.
To do so, as postgres run:  

	make check

The above will create a test database with postgis extensions,
run tests and then drop the db.

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:

See README.raster to know how to test PostGIS raster extension.


To install PostGIS library and utilities, as postgres run:

  make install

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

Where [prefix] above is extracted by `pg_config --configure`.

You can change them using ./configure switches.

See README.raster to know how to install PostGIS Raster extension.


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 PostgreSQL Programmer's Guide has details if you want to do this
manually for some reason.)

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 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

PostGIS provides a SOFT UPGRADE procedure for minor or bugfix
releases, and an HARD UPGRADE procedure for major releases.


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

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 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.

For this purpose, PostGIS provides a utility script to restore a dump
in "custom" format. The hard upgrade procedure is as follows:

	# 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 while upgrading postgis into
	# a new database. 
        # Note: The new database does NOT have to exist.
	# Let's call it "newdb"
	$ sh utils/ postgis.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 postgis.sql
	$ grep ^KEEPING restore.log | less

	# If upgrading from PostgreSQL < 8.0 to >= 8.0 you will want to 
	# drop the attrelid, varattnum and stats columns in the geometry_columns
	# table, which are no-more needed. Keeping them won't 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"

	# The spatial_ref_sys table is restored 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 it with the new like this:
	$ psql newdb
	newdb=> DELETE FROM spatial_ref_sys;
	newdb=> \i spatial_ref_sys.sql


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

  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.

    ( 1, 'EPSG', 4269,
          "GRS 1980",

  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;

--- 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.

You can build a GiST index with:

  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.

--- PostGIS Raster support ---

See README.raster to know how to enable raster support on a spatially enabled database.
Something went wrong with that request. Please try again.