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

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

2. Retrieve the PostGIS source archive from http://postgis.refractions.net/postgis-1.3.3SVN.tar.gz. Uncompress and untar the archive.

   # gzip -d -c postgis-1.3.3SVN.tar.gz | tar xvf -

3. Enter the postgis-1.3.3SVN directory, and run:

   # ./configure

   • 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. If ./configure didn't find it, try using --with-geos=PATH to specify the full path to the geos-config program full path.

4. 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]/.

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

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

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

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

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.

$ psql -f lwpostgis_upgrade.sql -d your_spatial_database

$ utils/postgis_proc_upgrade.pl lwpostgis.sql > lwpostgis_upgrade.sql

$ pg_dump -Fc olddb > olddb.dump

$ sh utils/postgis_restore.pl lwpostgis.sql newdb olddb.dump -E=UNICODE > restore.log

$ grep ^KEEPING restore.log | less

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

$ psql newdb 
newdb=> drop spatial_ref_sys; 
DROP 
newdb=> \i spatial_ref_sys.sql

There are several things to check when your installation or upgrade doesn't go as you expected.

Also check that you have made any necessary changes to the top of the Makefile.config. This includes:

1. Enter the jdbc sub-directory of the PostGIS distribution.

2. Edit the Makefile to provide the correct paths of your java compiler (JAVAC) and interpreter (JAVA).

3. Run the make command. Copy the postgis.jar file to wherever you keep your java libraries.