2.1. Requirements

A complete installation of PostgreSQL (including server
headers). PostgreSQL is available from http://www.postgresql.org.
Version 7.2 or higher is required.

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 (ST_Touches(), ST_Contains(), ST_Intersects()) and
operations (ST_Buffer(), ST_Union(), ST_Difference()) within PostGIS.
GEOS is available for download from http://geos.refractions.net.

2.2. PostGIS Compile from Source and Install

The PostGIS module is a extension to the PostgreSQL backend
server. As such, PostGIS 1.3.6 requires
full PostgreSQL server headers access in order to compile. The
PostgreSQL source code is available at http://www.postgresql.org.

PostGIS 1.3.6 can be built against PostgreSQL
versions 7.2.0 or higher. Earlier versions of PostgreSQL are
not supported.

Before you can compile the PostGIS server modules, you must
compile and install the PostgreSQL package.

Note

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.

If you want support for coordinate reprojection, you must
have the Proj4 library installed. If ./configure didn't find
it, try using --with-proj=PATH switch specify a
specific Proj4 installation directory.

If you want to use GEOS functionality, you must have the
GEOS library installed. Geos 3.0.3+ is preferred and is required for some functions
such as ST_SimplifyPreserveTopology to be available. If ./configure didn't find it, try
using --with-geos=PATH to specify the full path to
the geos-config program full path.

Run the compile and install commands.

# make # make install

All files are installed using information provided by
pg_config

Libraries are installed [pkglibdir]/lib/contrib.

Important support files such as lwpostgis.sql
are installed in [prefix]/share/contrib.

Loader and dumper binaries are installed in
[bindir]/.

If you are missing proj based on above or running a version below 4.5, then install by following these steps.

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

For helpful descriptions about functions included in postgis, install the postgis_comments.sql file.

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_postgis

2.2.2. Upgrading

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.

2.2.2.1. Soft upgrade

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.

Note

If you can't find the lwpostgis_upgrade.sql
file 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 lwpostgis.sql > lwpostgis_upgrade.sql

2.2.2.2. Hard 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:

Check that all restored dump objects really had to be restored
from dump and do not conflict with the ones defined in lwpostgis.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 !

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:

2.2.3. Common Problems

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) distribution 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.config. 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.config.

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

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

2.4. 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-1.3.6/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.