Table of Contents
PostGIS has the following requirements for building and usage:
A complete configured and built PostgreSQL source code tree. PostGIS uses definitions from the PostgreSQL configure/build process to conform to the particular platform you are building on. PostgreSQL is available from http://www.postgresql.org.
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.
(Recommended) Proj4 reprojection library. The Proj4 library is used to provide coordinate reprojection support within PostGIS. Proj4 is available for download from http://www.remotesensing.org/proj.
(Recommended) GEOS geometry library. The GEOS library is used to provide geometry tests (Touches(), Contains(), Intersects()) and operations (Buffer(), GeomUnion(), Difference()) within PostGIS. GEOS is available for download from http://geos.refractions.net.
The PostGIS module is a extension to the PostgreSQL backend server. As such, PostGIS 1.0.0 requires a full copy of the PostgreSQL source tree in order to compile. The PostgreSQL source code is available at http://www.postgresql.org.
PostGIS 1.0.0 can be built against PostgreSQL versions 7.2.0 to 7.4.x. Earlier versions of PostgreSQL are not supported.
Before you can compile the PostGIS server modules, you must compile and install the PostgreSQL package.
If you plan to use GEOS functionality you might 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.
Retrieve the PostGIS source archive from http://postgis.refractions.net/postgis-1.0.0.tar.gz. Uncompress and untar the archive in the "contrib" directory of the PostgreSQL source tree.
# cd [postgresql source tree]/contrib # gzip -d -c postgis-1.0.0.tar.gz | tar xvf -
Once your PostgreSQL installation is up-to-date, enter the
"postgis" directory, and edit the
Makefile
.
If want support for coordinate reprojection you must have
the Proj4 library installed, set the USE_PROJ
variable to 1, and adjust the
PROJ_DIR
variable to point to your Proj4
installation directory.
If want to use GEOS functionality you must have the GEOS
library installed, set the USE_GEOS
variable
to 1, and adjust the
GEOS_DIR
variable to point to your GEOS
installation directory.
Run the compile and install commands.
# make # make install
All files are installed relative to the PostgreSQL install
directory, [prefix]
.
Libraries are installed
[prefix]/lib/contrib
.
Important support files such as
lwpostgis.sql
are installed in
[prefix]/share/contrib
.
Loader and dumber binaries are installed in
[prefix]/bin
.
PostGIS requires the PL/pgSQL procedural language extension.
Before loading the lwpostgis.sql
file, you must
first enable PL/pgSQL. You should use the
createlang
command. The PostgreSQL
Programmer's Guide has the details if you want to this manually for
some reason.
# createlang plpgsql [yourdatabase]
Now load the PostGIS object and function definitions into your
database by loading the lwpostgis.sql
definitions
file.
# psql -d [yourdatabase] -f lwpostgis.sql
The PostGIS server extensions are now loaded and ready to use.
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.
# psql -d [yourdatabase] -f spatial_ref_sys.sql
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, execute the new lwpostgis.sql
file, then upload your database dump:
# pg_dump -t spatialtable -f dumpfile.sql yourdatabase # dropdb yourdatabase # createdb yourdatabase # createlang plpgsql yourdatabse # psql -f lwpostgis.sql -d yourdatabase # psql -f dumpfile.sql -d yourdatabase # vacuumdb -z yourdatabase
There are several things to check when your installation or upgrade doesn't go as you expected.
It is easiest if you untar the PostGIS distribution into the
contrib directory under the PostgreSQL source tree. However, if
this is not possible for some reason, you can set the
PGSQL_SRC
environment variable to the path to
the PostgreSQL source directory. This will allow you to compile
PostGIS, but the make install may not work, so
be prepared to copy the PostGIS library and executable files to
the appropriate locations yourself.
Check that you you have installed PostgreSQL 7.2 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) distrubution has already installed PostgreSQL, or you have otherwise installed PostgreSQL before and forgotten about it. PostGIS will only work with PostgreSQL 7.2 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 you have made any necessary changes to the top of the Makefile. This includes:
If you want to be able to do coordinate reprojections, you
must install the Proj4 library on your system, set the
USE_PROJ
variable to 1 and the
PROJ_DIR
to your installation prefix in the
Makefile.
If you want to be able to use GEOS functions you must
install the GEOS library on your system, and set the
USE_GEOS
to 1 and the
GEOS_DIR
to your installation prefix in the
Makefile.
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 jdbc
sub-directory of the
PostGIS distribution.
Edit the Makefile
to provide the correct
paths of your java compiler (JAVAC
) and
interpreter (JAVA
).
Run the make
command. Copy the
postgis.jar
file to wherever you keep your java
libraries.
The data loader and dumper are built and installed automatically as part of the PostGIS build. To build and install them manually:
# cd postgis-1.0.0/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.