Installation
This chapter details the steps required to install PostGIS.
Short VersionThe raster support is currently optional, but in final release it will be required.All the .sql files once installed will be installed in share/contrib/postgis-&last_release_version; folder
of your PostgreSQL installThe postgis_comments.sql, raster_comments.sql, topology_comments.sql
generate quick help tips for each function that can be accessed via pgAdmin III or psql. In psql with a command of the form e.g.\dd ST_SetPointtar xvfz postgis-&last_release_version;.tar.gz
cd postgis-&last_release_version;
./configure --with-raster --with-topology --with-gui
make
make install
createdb yourdatabase
createlang plpgsql yourdatabase
psql -d yourdatabase -f postgis.sql
psql -d yourdatabase -f postgis_comments.sql
psql -d yourdatabase -f spatial_ref_sys.sql
psql -d yourdatabase -f rtpostgis.sql
psql -d yourdatabase -f raster_comments.sql
psql -d yourdatabase -f topology/topology.sql
psql -d yourdatabase -f doc/topology_comments.sql
topology_comments.sql since its an optional feature is not installed by make install or make comments install. However if
you do a make comments or make topology_comments.sql, it will be generated in the docs folder
The rest of this chapter goes into detail each of the above installation
steps.
Requirements
PostGIS has the following requirements for building and usage:
Required
PostgreSQL &min_postgres_version; or higher. A complete installation
of PostgreSQL (including server headers) is required. PostgreSQL
is available from
http://www.postgresql.org
.
For a full PostgreSQL / PostGIS support matrix and PostGIS/GEOS support matrix refer to
http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS
GNU C compiler (gcc). Some other ANSI C compilers
can be used to compile PostGIS, but we find far fewer problems when
compiling with gcc.
GNU Make (gmake or make).
For many systems, GNU make is the default version
of make. Check the version by invoking make -v.
Other versions of make may not process the
PostGIS Makefile properly.
Proj4 reprojection library, version 4.6.0 or greater. The Proj4
library is used to provide coordinate reprojection support within
PostGIS. Proj4 is available for download from
http://trac.osgeo.org/proj/
.
GEOS geometry library, version 3.2.2 or greater, but GEOS 3.3 is recommended. Without GEOS 3.3,
you will be missing some major enhancements with handling of topological exceptions and improvements to geometry validation and
making geometries valid such as ST_ValidDetail and ST_MakeValid. GEOS is available for download from
http://trac.osgeo.org/geos/
.
LibXML2, version 2.5.x or higher. LibXML2 is currently used in some imports
functions (ST_GeomFromGML and ST_GeomFromKML). LibXML2 is available for download from
http://xmlsoft.org/downloads.html.
GDAL, version 1.6 or higher. This is needed for raster support and will be required in final
release of PostGIS 2.0.
http://trac.osgeo.org/gdal/wiki/DownloadSource.
Optional
GTK (requires GTK+2.0) to compile the shp2pgsql-gui shape file loader.
http://www.gtk.org/
.
Apache Ant (ant) is required for building any of
the drivers under the java directory. Ant is
available from
http://ant.apache.org
.
DocBook (xsltproc) is required for building the
documentation. Docbook is available from
http://www.docbook.org/
.
DBLatex (dblatex) is required for building the
documentation in PDF format. DBLatex is available from
http://dblatex.sourceforge.net/
.
ImageMagick (convert) is required to generate the
images used in the documentation. ImageMagick is available from
http://www.imagemagick.org/
.
Getting the Source
Retrieve the PostGIS source archive from the downloads website
http://www.postgis.org/download/postgis-&last_release_version;.tar.gz
wget http://www.postgis.org/download/postgis-&last_release_version;.tar.gz
tar -xvzf postgis-&last_release_version;.tar.gz
This will create a directory called
postgis-&last_release_version; in the current working
directory.
Alternatively, checkout the source from the
svn
repository
http://svn.osgeo.org/postgis/trunk/
.
svn checkout http://svn.osgeo.org/postgis/trunk/ postgis-&last_release_version;
Change into the newly created
postgis-&last_release_version; directory to continue
the installation.
Installation
Many OS systems now include pre-built packages for PostgreSQL/PostGIS.
In many cases compilation is only necessary if you want the most
bleeding edge versions or you are a package maintainer.
The PostGIS module is an extension to the PostgreSQL backend server. As
such, PostGIS &last_release_version; requires full
PostgreSQL server headers access in order to compile. It can be built
against PostgreSQL versions &min_postgres_version; or higher. Earlier
versions of PostgreSQL are not supported.
Refer to the PostgreSQL installation guides if you haven't already
installed PostgreSQL.
http://www.postgresql.org
.
For GEOS functionality, when you install PostgresSQL you may need to
explicitly link PostgreSQL against the standard C++ library:
LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]
This is a workaround for bogus C++ exceptions interaction with older
development tools. If you experience weird problems (backend
unexpectedly closed or similar things) try this trick. This will require
recompiling your PostgreSQL from scratch, of course.
The following steps outline the configuration and compilation of the
PostGIS source. They are written for Linux users and will not work on
Windows or Mac.
Configuration
As with most linux installations, the first step is to generate the
Makefile that will be used to build the source code. This is done by
running the shell script
./configure
With no additional parameters, this command will attempt to
automatically locate the required components and libraries needed to
build the PostGIS source code on your system. Although this is the most
common usage of ./configure, the script accepts
several parameters for those who have the required libraries and
programs in non-standard locations.
The following list shows only the most commonly used parameters. For a
complete list, use the --help or
--help=short parameters.
--prefix=PREFIX
This is the location the PostGIS libraries and SQL scripts will be
installed to. By default, this location is the same as the
detected PostgreSQL installation.
This parameter is currently broken, as the package will only
install into the PostgreSQL installation directory. Visit
http://trac.osgeo.org/postgis/ticket/160
to track this bug.
--with-pgconfig=FILE
PostgreSQL provides a utility called pg_config
to enable extensions like PostGIS to locate the PostgreSQL
installation directory. Use this parameter
(--with-pgconfig=/path/to/pg_config) to
manually specify a particular PostgreSQL installation that PostGIS
will build against.
--with-gdalconfig=FILE
GDAL, a required library, provides functionality needed for raster support
gdal-config to enable software installations to
locate the GDAL installation directory. Use this parameter
(--with-gdalconfig=/path/to/gdal-config) to
manually specify a particular GDAL installation that PostGIS will
build against.
--with-geosconfig=FILE
GEOS, a required geometry library, provides a utility called
geos-config to enable software installations to
locate the GEOS installation directory. Use this parameter
(--with-geosconfig=/path/to/geos-config) to
manually specify a particular GEOS installation that PostGIS will
build against.
--with-projdir=DIR
Proj4 is a reprojection library required by PostGIS. Use this
parameter (--with-projdir=/path/to/projdir) to
manually specify a particular Proj4 installation directory that
PostGIS will build against.
--with-gui
Compile the data import GUI (requires GTK+2.0). This will create shp2pgsql-gui graphical interface
to shp2pgsql.
--with-raster
Compile with raster support. This will build rtpostgis-&last_release_version; library and rtpostgis.sql file. This may not
be required in final release as plan is to build in raster support by default.
--with-topology
Compile with topology support. This will build the topology.sql file. There is no corresponding library
as all logic needed for topology is in postgis-&last_release_version; library.
If you obtained PostGIS from the SVN
repository
, the first step is really to run the script
./autogen.sh
This script will generate the configure script that
in turn is used to customize the installation of PostGIS.
If you instead obtained PostGIS as a tarball, running
./autogen.sh is not necessary as
configure has already been generated.
Building
Once the Makefile has been generated, building PostGIS is as simple as
running
make
The last line of the output should be "PostGIS was built
successfully. Ready to install."
As of PostGIS v1.4.0, all the functions have comments generated from the
documentation. If you wish to install these comments into your spatial
databases later, run the command which requires docbook. The postgis_comments.sql
is also packaged in the tar.gz distribution in the doc folder so no need to make comments
if installing from the tar ball.
make commentsTesting
If you wish to test the PostGIS build, run
make check
The above command will run through various checks and regression tests
using the generated library against an actual PostgreSQL database.
If you configured PostGIS using non-standard PostgreSQL, GEOS, or
Proj4 locations, you may need to add their library locations to the
LD_LIBRARY_PATH environment variable.
Currently, the make check relies on the
PATH and PGPORT environment variables when
performing the checks - it does not use the
PostgreSQL version that may have been specified using the
configuration parameter --with-pgconfig. So make
sure to modify your PATH to match the detected PostgreSQL installation
during configuration or be prepared to deal with the impending
headaches. Visit
http://trac.osgeo.org/postgis/ticket/186
to track this bug.
If successful, the output of the test should be similar to the
following:
CUnit - A Unit testing framework for C - Version 2.1-0
http://cunit.sourceforge.net/
Suite: print_suite
Test: test_lwprint_default_format ... passed
Test: test_lwprint_format_orders ... passed
Test: test_lwprint_optional_format ... passed
Test: test_lwprint_oddball_formats ... passed
Test: test_lwprint_bad_formats ... passed
Suite: Misc Suite
Test: test_misc_force_2d ... passed
Test: test_misc_simplify ... passed
Test: test_misc_count_vertices ... passed
Test: test_misc_area ... passed
Test: test_misc_wkb ... passed
Suite: PointArray Suite
Test: test_ptarray_append_point ... passed
Test: test_ptarray_append_ptarray ... passed
Suite: PostGIS Computational Geometry Suite
Test: test_lw_segment_side ... passed
Test: test_lw_segment_intersects ... passed
Test: test_lwline_crossing_short_lines ... passed
Test: test_lwline_crossing_long_lines ... passed
Test: test_lwline_crossing_bugs ... passed
Test: test_lwpoint_set_ordinate ... passed
Test: test_lwpoint_get_ordinate ... passed
Test: test_lwpoint_interpolate ... passed
Test: test_lwline_clip ... passed
Test: test_lwline_clip_big ... passed
Test: test_lwmline_clip ... passed
Test: test_geohash_point ... passed
Test: test_geohash_precision ... passed
Test: test_geohash ... passed
Test: test_isclosed ... passed
Suite: PostGIS Measures Suite
Test: test_mindistance2d_tolerance ... passed
Test: test_rect_tree_contains_point ... passed
Test: test_rect_tree_intersects_tree ... passed
Test: test_lwgeom_segmentize2d ... passed
Suite: WKT Out Suite
Test: test_wkt_out_point ... passed
Test: test_wkt_out_linestring ... passed
Test: test_wkt_out_polygon ... passed
Test: test_wkt_out_multipoint ... passed
Test: test_wkt_out_multilinestring ... passed
:
:
--Run Summary: Type Total Ran Passed Failed
suites 17 17 n/a 0
tests 143 143 143 0
asserts 1228 1228 1228 0
Creating spatial db postgis_reg
Postgis 2.0.0SVN - 2011-01-11 15:33:37
GEOS: 3.3.0-CAPI-1.7.0
PROJ: Rel. 4.6.1, 21 August 2008
Running tests
loader/Point.............. ok
loader/PointM.............. ok
loader/PointZ.............. ok
loader/MultiPoint.............. ok
loader/MultiPointM.............. ok
loader/MultiPointZ.............. ok
loader/Arc.............. ok
loader/ArcM.............. ok
loader/ArcZ.......... ok
loader/Polygon.............. ok
loader/PolygonM.............. ok
loader/PolygonZ.............. ok
regress. ok
regress_index. ok
regress_index_nulls. ok
lwgeom_regress. ok
regress_lrs. ok
removepoint. ok
setpoint. ok
simplify. ok
snaptogrid. ok
affine. ok
measures. ok
long_xact. ok
ctors. ok
sql-mm-serialize. ok
sql-mm-circularstring. ok
sql-mm-compoundcurve. ok
sql-mm-curvepoly. ok
sql-mm-general. ok
sql-mm-multicurve. ok
sql-mm-multisurface. ok
polyhedralsurface. ok
out_geometry. ok
out_geography. ok
in_gml. ok
in_kml. ok
iscollection. ok
regress_ogc. ok
regress_ogc_cover. ok
regress_ogc_prep. ok
regress_bdpoly. ok
regress_proj. ok
dump. ok
dumppoints. ok
wmsservers_new. ok
tickets. ok
remove_repeated_points. ok
split. ok
relatematch. ok
regress_buffer_params. ok
hausdorff. ok
clean. ok
sharedpaths. ok
snap. ok
Run tests: 55
Failed: 0
Installation
To install PostGIS, type
make install
This will copy the PostGIS installation files into their appropriate
subdirectory specified by the --prefix configuration
parameter. In particular:
The loader and dumper binaries are installed in
[prefix]/bin.
The SQL files, such as postgis.sql, are
installed in [prefix]/share/contrib.
The PostGIS libraries are installed in
[prefix]/lib.
If you previously ran the make comments command to
generate the postgis_comments.sql, raster_comments.sql file, install the
sql file by running
make comments-installpostgis_comments.sql and raster_comments.sql was separated from the
typical build and installation targets since with it comes the extra
dependency of xsltproc.
Create a spatially-enabled database
The first step in creating a PostGIS database is to create a simple
PostgreSQL database.
createdb [yourdatabase]
Many of the PostGIS functions are written in the PL/pgSQL procedural
language. As such, the next step to create a PostGIS database is to enable
the PL/pgSQL language in your new database. This is accomplish by the
command
createlang plpgsql [yourdatabase]
Now load the PostGIS object and function definitions into your database by
loading the postgis.sql definitions file (located in
[prefix]/share/contrib as specified during the
configuration step).
psql -d [yourdatabase] -f postgis.sql
For a complete set of EPSG coordinate system definition identifiers, you
can also load the spatial_ref_sys.sql definitions
file and populate the spatial_ref_sys table. This will
permit you to perform ST_Transform() operations on geometries.
psql -d [yourdatabase] -f spatial_ref_sys.sql
If you wish to add comments to the PostGIS functions, the final step is to
load the postgis_comments.sql into your spatial
database. The comments can be viewed by simply typing \dd
[function_name] from a psql terminal window.
psql -d [yourdatabase] -f postgis_comments.sqlCreate a spatially-enabled database from a template
Some packaged distributions of PostGIS (in particular the Win32 installers
for PostGIS >= 1.1.5) load the PostGIS functions into a template
database called template_postgis. If the
template_postgis database exists in your PostgreSQL
installation then it is possible for users and/or applications to create
spatially-enabled databases using a single command. Note that in both
cases, the database user must have been granted the privilege to create
new databases.
From the shell:
# createdb -T template_postgis my_spatial_db
From SQL:
postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgisUpgrading
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.
PostGIS provides a SOFT UPGRADE procedure for minor or bugfix releases,
and an HARD UPGRADE procedure for major releases.
Before attempting to upgrade PostGIS, it is always worth to backup your
data. If you use the -Fc flag to pg_dump you will always be able to
restore the dump with an HARD UPGRADE.
Soft upgrade
After compiling you should find several postgis_upgrade*.sql files. Install the one
for your version of PostGIS. For example postgis_upgrade_13_to_15.sql should be used if you are upgrading
from PostGIS 1.3 to 1.5.
$ psql -f postgis_upgrade_13_to_15.sql -d your_spatial_database
If a soft upgrade is not possible the script will abort and you will be
warned about HARD UPGRADE being required, so do not hesitate to try a
soft upgrade first.
If you can't find the postgis_upgrade*.sql files
you are probably using a version prior to 1.1 and must generate that
file by yourself. This is done with the following command:
$ utils/postgis_proc_upgrade.pl postgis.sql > postgis_upgrade.sqlHard upgrade
By HARD UPGRADE we intend full dump/reload of postgis-enabled databases.
You need an HARD UPGRADE when PostGIS objects' internal storage changes
or when SOFT UPGRADE is not possible. The
Release Notes
appendix reports for each version whether you need a dump/reload (HARD
UPGRADE) to upgrade.
PostGIS provides an utility script to restore a dump produced with the
pg_dump -Fc command. It is experimental so redirecting its output to a
file will help in case of problems. The procedure is as follow:
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 contextually upgrading PostGIS into a new database. The
new database doesn't have to exist. postgis_restore accepts createdb
parameters after the dump file name, and that can for instance be used
if you are using a non-default character encoding for your database.
Let's call it "newdb", with UNICODE as the character encoding:
$ sh utils/postgis_restore.pl postgis.sql newdb olddb.dump -E=UNICODE > 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 might want to
drop the attrelid, varattnum and stats columns in the geometry_columns
table, which are no-more needed. Keeping them won't hurt. DROPPING THEM
WHEN REALLY NEEDED WILL DO 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"
spatial_ref_sys table is restore 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 of it with the new one is done like
this:
$ psql newdb
newdb=> truncate spatial_ref_sys;
DROP
newdb=> \i spatial_ref_sys.sqlCommon Problems
There are several things to check when your installation or upgrade
doesn't go as you expected.
Check that you you have installed PostgreSQL &min_postgres_version;
or newer, and that you are compiling against the same version of the
PostgreSQL source as the version of PostgreSQL that is running.
Mix-ups can occur when your (Linux) distribution has already
installed PostgreSQL, or you have otherwise installed PostgreSQL
before and forgotten about it. PostGIS will only work with PostgreSQL
&min_postgres_version; or newer, and strange, unexpected
error messages will result if you use an older version. To check the
version of PostgreSQL which is running, connect to the database using
psql and run this query:
SELECT version();
If you are running an RPM based distribution, you can check for the
existence of pre-installed packages using the rpm
command as follows: rpm -qa | grep postgresql
Also check that configure has correctly detected the location and version
of PostgreSQL, the Proj4 library and the GEOS library.
The output from configure is used to generate the
postgis_config.h file. Check that the
POSTGIS_PGSQL_VERSION,
POSTGIS_PROJ_VERSION and
POSTGIS_GEOS_VERSION variables have been set
correctly.
JDBC
The JDBC extensions provide Java objects corresponding to the internal
PostGIS types. These objects can be used to write Java clients which query
the PostGIS database and draw or do calculations on the GIS data in
PostGIS.
Enter the java/jdbc sub-directory of the PostGIS
distribution.
Run the ant command. Copy the
postgis.jar file to wherever you keep your java
libraries.
The JDBC extensions require a PostgreSQL JDBC driver to be present in the
current CLASSPATH during the build process. If the PostgreSQL JDBC driver
is located elsewhere, you may pass the location of the JDBC driver JAR
separately using the -D parameter like this:
# ant -Dclasspath=/path/to/postgresql-jdbc.jar
PostgreSQL JDBC drivers can be downloaded from
http://jdbc.postgresql.org
.
Loader/Dumper
The data loader and dumper are built and installed automatically as part
of the PostGIS build. To build and install them manually:
# cd postgis-&last_release_version;/loader
# make
# make install
The loader is called shp2pgsql and converts ESRI
Shape files into SQL suitable for loading in PostGIS/PostgreSQL. The
dumper is called pgsql2shp and converts PostGIS
tables (or queries) into ESRI Shape files. For more verbose documentation,
see the online help, and the manual pages.