Chapter 2. Installation

Table of Contents

2.1. Requirements
2.2. PostGIS
2.2.1. Upgrading
2.2.2. Common Problems
2.3. JDBC
2.4. Loader/Dumper

2.1. Requirements

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.

2.2. PostGIS

The PostGIS module is a extension to the PostgreSQL backend server. As such, PostGIS 1.0.4 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.4 can be built against PostgreSQL versions 7.2.0 to 7.4.x. Earlier versions of PostgreSQL are not supported.

  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.0.4.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.4.tar.gz | tar xvf -
  3. Once your PostgreSQL installation is up-to-date, enter the "postgis" directory, and edit the Makefile.config file.

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

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

  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

2.2.1. Upgrading

Upgrading PostGIS can be tricky, because it is composed by both a shared library and a set of definitions that are stored in the host database.

When the set of definitions changes (new objects, or procedural language functions modifications) it is not always easy to have them replace the old ones. Having a mismatch between definitions and implementations can bring to an unstable or unsable system.

Since postgis version 0.9.0 You can check your installation state using postgis_full_version(). The function will warn you with a "need proc upgrade" message if a mismatch is found.

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.1.1. 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 wheter 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.
	# Let's call it "newdb"
	$ sh utils/postgis_restore.pl lwpostgis.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 lwpostgis.sql
	$ grep ^KEEPING restore.log | less

	# If upgrading from PostgreSQL < 7.5 to >= 7.5 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=> delete from spatial_ref_sys; 
	DROP
	newdb=> \i spatial_ref_sys.sql
	

2.2.1.2. Soft upgrade

By SOFT UPGRADE we intend a live replacement of objects definitions. This is only possible in certain circumstances as not all objects are replaceable in a live system.

To know wheter a SOFT UPGRADE should work for you refer to your new version section in the Release Notes appendix of this manual.

The postgis_full_version() function will also show you current state and by that you should be able to find out wheter or not SOFT UPGRADE will be possible. You should look at the DBPROC and RELPROC values. DBPROC are the procedures stored in the database, RELPROC are the procedures expected by the shared library (RELeased PROCedures). Their values represent SCRIPTS versions. If they don't match the function will warn you with a message: "needs proc upgrade".

Soft (proc) upgrade will only be possible when the DBPROC and RELPROC versions share MAJOR and MINOR numbers. If this is the case you can try to use the utils/postgis_proc_upgrade.pl script. Note that the script will check for this itself so you should be safe attempting w/out checking it manually. Here is how you do:


	$ make install # DON'T DO IT IF WITHOUT BACKING UP YOUR DATA !  

	$ utils/postgis_proc_upgrade.pl lwpostgis.sql | psql <db>  

	

2.2.1.3. Old method

Following is the "old" procedure description. IT SHOULD BE AVOIDED if possible, as it will leave in the database many spurious functions. It is kept in this document as a "backup" in case HARD UPGRADE or SOFT UPGRADE won't work for you:

	pg_dump -t "*" -f dumpfile.sql yourdatabase
	dropdb yourdatabase
	createdb yourdatabase
	createlang plpgsql yourdatabase
	psql -f lwpostgis.sql -d yourdatabase
	psql -f dumpfile.sql -d yourdatabase
	vacuumdb -z yourdatabase
	

2.2.2. Common Problems

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

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

  2. 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.config. This includes:

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

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

  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.

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