postgis/doc/installation.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter>
  <title>Installation</title>

  <sect1>
    <title>Requirements</title>

    <para>PostGIS has the following requirements for building and
    usage:</para>

    <itemizedlist>
      <listitem>
        <para>A complete installation of PostgreSQL (including server
        headers). PostgreSQL is available from <ulink
        url="http://www.postgresql.org">http://www.postgresql.org</ulink>.
        Version 8.1 or higher is required.</para>
      </listitem>

      <listitem>
        <para>GNU C compiler (<filename>gcc</filename>). Some other ANSI C
        compilers can be used to compile PostGIS, but we find far fewer
        problems when compiling with <filename>gcc</filename>.</para>
      </listitem>

      <listitem>
        <para>GNU Make (<filename>gmake</filename> or
        <filename>make</filename>). For many systems, GNU
        <filename>make</filename> is the default version of make. Check the
        version by invoking <filename>make -v</filename>. Other versions of
        <filename>make</filename> may not process the PostGIS
        <filename>Makefile</filename> properly.</para>
      </listitem>

      <listitem>
        <para>Proj4 reprojection library. The Proj4 library is
        used to provide coordinate reprojection support within PostGIS. Proj4
        is available for download from <ulink
        url="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj</ulink>.</para>
      </listitem>

      <listitem>
        <para>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 <ulink
        url="http://geos.refractions.net">http://geos.refractions.net</ulink>.</para>
      </listitem>

      <listitem>
        <para>(Recommended) Apache Ant (<filename>ant</filename>). Required for 
        building any of the drivers under the <filename>java</filename> directory. Ant is available for download from <ulink url="http://ant.apache.org">http://ant.apache.org</ulink>.</para>
      </listitem>

    </itemizedlist>
  </sect1>

  <sect1 id="PGInstall">
    <title>PostGIS</title>

    <para>The PostGIS module is a extension to the PostgreSQL backend server.
    As such, PostGIS &last_release_version; <emphasis>requires</emphasis>
    full PostgreSQL server headers access in order to compile. The PostgreSQL
    source code is available at <ulink
    url="http://www.postgresql.org">http://www.postgresql.org</ulink>.</para>

    <para>PostGIS &last_release_version; can be built against PostgreSQL
    versions 8.1.0 or higher. Earlier versions of PostgreSQL are
    <emphasis>not</emphasis> supported.</para>

	<sect2 id="firsttimeinstall">
		<title>Compiling and Installing from Source</title>
		<orderedlist>
		<listitem>
			<para>Before you can compile the PostGIS server modules, you must
			compile and install the PostgreSQL package.</para>
			
			<note>
			  <para>If you plan to use GEOS functionality you might need to
			  explicitly link PostgreSQL against the standard C++ library:</para>
			
			  <programlisting>LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]</programlisting>
			
			  <para>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.</para>
			  
			  <para>The steps that follow are for Linux users.  They will not work on Windows without MingW and some other stuff</para>
			</note>
		</listitem>
		
		<listitem>
			<para>Check your settings to see which versions of things will be used</para>
			<programlisting>
			which gcc
			which make &amp;&amp; which autoconf
			which pg_config
			sudo ldconfig -v | grep iconv
			which flex &amp;&amp; which bison
			sudo ldconfig -v | grep /usr/local/lib
			which geos-config
			sudo ldconfig -v | grep proj
			</programlisting>
		</listitem>
		
		<listitem>
			<para>If you are missing proj based on above or running a version below 4.5, then install by following these steps.</para>
			<programlisting>
			wget http://download.osgeo.org/proj/proj-4.6.0.tar.gz
			tar xvzf proj4-4.6.0.tar.gz
			cd proj4-4.6.0
			./configure &amp;&amp; make clean &amp;&amp; make
			sudo make install
			sudo ldconfig
			cd ..
			</programlisting>
		</listitem>
		
		<listitem>
			<para>If you are missing geos based on above or running a version below 3.0, then install by following these steps.</para>
			<programlisting>
			wget http://geos.refractions.net/downloads/geos-3.0.0.tar.bz2
			tar xvjf geos-3.0.0.tar.bz2
			cd geos-3.0.0
			./configure &amp;&amp; make clean &amp;&amp; make
			sudo make install
			sudo ldconfig
			cd ..
			</programlisting>
		</listitem>
		
		<listitem>
			<para>Retrieve the PostGIS source archive from <ulink
			url="http://postgis.refractions.net/download/postgis-&last_release_version;.tar.gz">http://postgis.refractions.net/download/postgis-&last_release_version;.tar.gz</ulink>.
			Uncompress and untar the archive. configure.</para>
			
			<para>All files are installed using information provided by
			<filename>pg_config</filename></para>
			
			<itemizedlist>
			  <listitem>
				<para>Libraries are installed
				<filename>[pkglibdir]/lib/contrib</filename>.</para>
			  </listitem>
			
			  <listitem>
				<para>Important support files such as
				<filename>lwpostgis.sql</filename> are installed in
				<filename>[prefix]/share/contrib</filename>.</para>
			  </listitem>
			
			  <listitem>
				<para>Loader and dumper binaries are installed in
				<filename>[bindir]/</filename>.</para>
			  </listitem>
			</itemizedlist>
			
			<programlisting>
				wget http://postgis.refractions.net/download/postgis-&last_release_version;.tar.gz
				gzip -d -c postgis-&last_release_version;.tar.gz | tar xvf -
				cd postgis-&last_release_version;/
				sh autogen.sh
				./configure
			</programlisting>
		</listitem>
		
		
		<listitem>
			 <para>Make and Install</para>
			<itemizedlist>
			  <listitem>
				<para>PostgreSQL provides a utility called <filename>pg_config</filename> to enable
				extensions like PostGIS to locate the PostgreSQL installation directory.
				If ./configure didn't find <filename>pg_config</filename>,
				try using the <code>--with-pgconfig=/path/to/pg_config</code> switch to specify a particular 
				PostgreSQL installation.</para>
			  </listitem>
			
			  <listitem>
				<para>Proj4 is now required in order to build and use PostGIS.
				If ./configure didn't find the Proj4 library,
				try using the <code>--with-projdir=/path/to/projdir</code> switch to specify an alternative
				Proj4 installation directory.</para>
			  </listitem>
			
			  <listitem>
				<para>GEOS is now required in order to build and use PostGIS.
				If ./configure didn't find it, try using the 
				<code>--with-geosconfig=/path/to/geos-config</code> switch to specify the full path 
				to the <filename>geos-config</filename> program.</para>
			  </listitem>
			</itemizedlist>
			<programlisting>
				make clean &amp;&amp; make
				sudo make install
				sudo ldconfig
			</programlisting>
		</listitem>
		
		
		<listitem>
			<para>PostGIS requires the PL/pgSQL procedural language extension.
			Before loading the <filename>lwpostgis.sql</filename> file, you must
			first enable PL/pgSQL. You should use the
			<filename>createlang</filename> command. The PostgreSQL Programmer's
			Guide has the details if you want to this manually for some
			reason.</para>
			
			<programlisting># createlang plpgsql [yourdatabase]</programlisting>
			</listitem>
			
			<listitem>
			<para>Now load the PostGIS object and function definitions into your
			database by loading the <filename>lwpostgis.sql</filename> definitions
			file.</para>
			
			<programlisting># psql -d [yourdatabase] -f lwpostgis.sql</programlisting>
			
			<para>The PostGIS server extensions are now loaded and ready to
			use.</para>
		</listitem>
		
		<listitem>
			<para>For a complete set of EPSG coordinate system definition
			identifiers, you can also load the
			<filename>spatial_ref_sys.sql</filename> definitions file and populate
			the <varname>SPATIAL_REF_SYS</varname> table.</para>
			
			<programlisting># psql -d [yourdatabase] -f spatial_ref_sys.sql</programlisting>
		</listitem>
		</orderedlist>
	</sect2>


    <sect2 id="templatepostgis">
      <title>Creating PostGIS spatially-enabled databases from an in-built
      template</title>

      <para>Some packaged distributions of PostGIS (in particular the Win32
      installers for PostGIS &gt;= 1.1.5) load the PostGIS functions into a
      template database called <varname>template_postgis</varname>. If the
      <varname>template_postgis</varname> 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.</para>

      <para>From the shell:</para>

      <programlisting># createdb -T template_postgis my_spatial_db</programlisting>

      <para>From SQL:</para>

      <programlisting>postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgis</programlisting>
    </sect2>

    <sect2 id="upgrading">
      <title>Upgrading</title>

      <para>Upgrading existing spatial databases can be tricky as it requires
      replacement or introduction of new PostGIS object definitions.</para>

      <para>Unfortunately not all definitions can be easily replaced in a live
      database, so sometimes your best bet is a dump/reload process.</para>

      <para>PostGIS provides a SOFT UPGRADE procedure for minor or bugfix
      releases, and an HARD UPGRADE procedure for major releases.</para>

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

      <sect3 id="soft_upgrade">
        <title>Soft upgrade</title>

        <para>Soft upgrade consists of sourcing the lwpostgis_upgrade.sql
        script in your spatial database:</para>

        <programlisting>$ psql -f lwpostgis_upgrade.sql -d your_spatial_database</programlisting>

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

        <note>
          <para>If you can't find the
          <filename>lwpostgis_upgrade.sql</filename> 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:</para>

          <programlisting>$ utils/postgis_proc_upgrade.pl lwpostgis.sql &gt; lwpostgis_upgrade.sql</programlisting>
        </note>
      </sect3>

      <sect3 id="hard_upgrade">
        <title>Hard upgrade</title>

        <para>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 <link
        linkend="release_notes">Release Notes</link> appendix reports for each
        version whether you need a dump/reload (HARD UPGRADE) to
        upgrade.</para>

        <para>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:</para>

        <para>Create a "custom-format" dump of the database you want to
        upgrade (let's call it "olddb")</para>

        <programlisting>$ pg_dump -Fc olddb &gt; olddb.dump</programlisting>

        <para>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:</para>

        <programlisting>$ sh utils/postgis_restore.pl lwpostgis.sql newdb olddb.dump -E=UNICODE &gt; restore.log</programlisting>

        <para>Check that all restored dump objects really had to be restored
        from dump and do not conflict with the ones defined in
        lwpostgis.sql</para>

        <programlisting>$ grep ^KEEPING restore.log | less</programlisting>

        <para>If upgrading from PostgreSQL &lt; 8.0 to &gt;= 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 !</para>

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

        <para>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:</para>

        <programlisting>$ psql newdb 
newdb=&gt; drop spatial_ref_sys; 
DROP 
newdb=&gt; \i spatial_ref_sys.sql</programlisting>
      </sect3>
    </sect2>

    <sect2>
      <title>Common Problems</title>

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

      <orderedlist>
        <listitem>
          <para>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:</para>

          <programlisting>SELECT version();</programlisting>

          <para>If you are running an RPM based distribution, you can check
          for the existence of pre-installed packages using the
          <command>rpm</command> command as follows: <command>rpm -qa | grep
          postgresql</command></para>
        </listitem>
      </orderedlist>

      <para>Also check that configure has correctly detected the location and 
      version of PostgreSQL, the Proj4 library and the GEOS library.</para>

      <orderedlist>
        <listitem>
          <para>The output from configure is used to generate the
          <filename>postgis_config.h</filename> file. Check that the 
          <varname>POSTGIS_PGSQL_VERSION</varname>, <varname>POSTGIS_PROJ_VERSION</varname>
          and <varname>POSTGIS_GEOS_VERSION</varname> variables have been set correctly.</para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1>
    <title>JDBC</title>

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

    <orderedlist>
      <listitem>
        <para>Enter the <filename>java/jdbc</filename> sub-directory of the PostGIS
        distribution.</para>
      </listitem>

      <listitem>
        <para>Run the <filename>ant</filename> command. Copy the
        <filename>postgis.jar</filename> file to wherever you keep your java
        libraries.</para>
      </listitem>
    </orderedlist>

    <para>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:</para>

    <programlisting># ant -Dclasspath=/path/to/postgresql-jdbc.jar</programlisting>

    <para>PostgreSQL JDBC drivers can be downloaded from 
    <ulink url="http://jdbc.postgresql.org">http://jdbc.postgresql.org</ulink>.</para> 
  </sect1>

  <sect1>
    <title>Loader/Dumper</title>

    <para>The data loader and dumper are built and installed automatically as
    part of the PostGIS build. To build and install them manually:</para>

    <programlisting># cd postgis-&last_release_version;/loader 
# make 
# make install</programlisting>

    <para>The loader is called <filename>shp2pgsql</filename> and converts
    ESRI Shape files into SQL suitable for loading in PostGIS/PostgreSQL. The
    dumper is called <filename>pgsql2shp</filename> and converts PostGIS
    tables (or queries) into ESRI Shape files. For more verbose documentation,
    see the online help, and the manual pages.</para>
  </sect1>
</chapter>