# Installation

This chapter details the steps required to install PostGIS.

## Short Version

    tar xvfz postgis-&last_release_version;.tar.gz
    cd postgis-&last_release_version;
    ./configure
    make
    make install
    #BEGIN OPTIONAL -- this is already part of the tar
    # only really need this if installing from SVN
    cd doc/
    make comments-install
    #END OPTIONAL
    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

NOTE: The postgis.sql and spatial_ref_sys.sql will be installed in the /share/contrib/postgis-&last_minor_release_version; of your PostGIS install. If you didn't install the OPTIONAL comments section, you will need to manually copy the postgis_comments.sql file from the doc folder of your source install to your /share/contrib/postgis-&last_minor_release_version; 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 8.3 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.1.1 or greater, but GEOS 3.2 is recommended. Without GEOS 3.2, you will be missing some major enhancements with handling of topological exceptions and improvements to ST_Buffer that allow beveling and mitre and much faster buffering. The GEOS library is used to provide geometry tests (ST_Touches(), ST_Contains(), ST_Intersects()) and operations (ST_Buffer(), ST_Union(),ST_Intersection() ST_Difference()) within PostGIS. 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.

Optional

- GTK (requires GTK+2.0) to compile the shp2pgsql-gui shape file loader. http://www.gtk.org/ .

- CUnit (`CUnit`). This is needed for regression tests. http://cunit.sourceforge.net/

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

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 intallation 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 comments`

### Testing

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 paramter `--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 similiar to the following:

         CUnit - A Unit testing framework for C - Version 2.1-0
    	 http://cunit.sourceforge.net/

    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_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
    Suite: PostGIS Measures Suite
      Test: test_mindistance2d_recursive_tolerance() ... passed

    --Run Summary: Type      Total     Ran  Passed  Failed
    			   suites        2       2     n/a       0
    			   tests        14      14      14       0
    			   asserts      84      84      84       0

    Creating spatial db postgis_reg
    TMPDIR is /tmp/pgis_reg_15328

     PostgreSQL 8.3.7 on i686-pc-linux-gnu, compiled by GCC gcc (GCC) 4.1.2 20080704 (Red Hat 4.1.2-44)
     Postgis 1.4.0SVN - 2009-05-25 20:21:55
       GEOS: 3.1.0-CAPI-1.5.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
     wkt. 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
     geojson. ok
     gml. ok
     svg. ok
     kml. ok
     regress_ogc. ok
     regress_bdpoly. ok
     regress_proj. ok
     regress_ogc_cover. ok
     regress_ogc_prep. ok

    Run tests: 42
    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` file, install the sql file by running

`make comments-install`

`postgis_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.sql`

## Create 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_postgis

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

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

### 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:

    $ 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;
    TRUNCATE
    newdb=> \i spatial_ref_sys.sql

## Common Problems

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

1. Check that you you have installed PostgreSQL 8.1 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 8.1 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.

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

1. Enter the `java/jdbc` sub-directory of the PostGIS distribution.

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