postgis/doc/installation.xml

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

  <para>
	This chapter details the steps required to install PostGIS.
  </para>

  <sect1>
	<title>Short Version</title>
	<note><para>The raster support is currently optional, but in final release it will be required.</para></note>
	<para>All the .sql files once installed will be installed in share/contrib/postgis-&last_release_version; folder
		of your PostgreSQL install</para>
	<para>The <varname>postgis_comments.sql</varname>, <varname>raster_comments.sql</varname>, <varname>topology_comments.sql</varname>
		generate quick help tips for each function that can be accessed via pgAdmin III or psql. In psql with a command of the form e.g.<varname>\dd ST_SetPoint</varname></para>
	<programlisting>tar xvfz postgis-&last_release_version;.tar.gz
cd postgis-&last_release_version;
./configure --with-raster --with-topology --with-gui
make
make install
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
psql -d yourdatabase -f rtpostgis.sql
psql -d yourdatabase -f raster_comments.sql
psql -d yourdatabase -f topology/topology.sql
psql -d yourdatabase -f doc/topology_comments.sql

</programlisting>
<note><para>topology_comments.sql since its an optional feature is not installed by make install or make comments install. However if
you do a <varname>make comments</varname> or <varname>make topology_comments.sql</varname>, it will be generated in the docs folder</para>
</note>

	<para>
	  The rest of this chapter goes into detail each of the above installation
	  steps.
	</para>
  </sect1>

  <sect1>
	<title>Requirements</title>

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

	<para>
	  <emphasis role="bold">Required</emphasis>
	</para>

	<itemizedlist>
	  <listitem>
		<para>
		  PostgreSQL &min_postgres_version; or higher. A complete installation
		  of PostgreSQL (including server headers) is required. PostgreSQL
		  is available from
		  <ulink url="http://www.postgresql.org">
			http://www.postgresql.org
		  </ulink>
		  .
		</para>
		<para>For a full PostgreSQL / PostGIS support matrix and PostGIS/GEOS support matrix refer to 
			<ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS">http://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGIS</ulink>
		</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, version 4.6.0 or greater. The Proj4
		  library is used to provide coordinate reprojection support within
		  PostGIS. Proj4 is available for download from
		  <ulink url="http://trac.osgeo.org/proj/">
			http://trac.osgeo.org/proj/
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
		  GEOS geometry library, version 3.2.2 or greater, but GEOS 3.3 is recommended.  Without GEOS 3.3,
			you will be missing some major enhancements with handling of topological exceptions and improvements to geometry validation and
			making geometries valid such as ST_ValidDetail and ST_MakeValid.  GEOS is available for download from
		  <ulink url="http://trac.osgeo.org/geos/">
			http://trac.osgeo.org/geos/
		  </ulink>
		  .
		</para>
	  </listitem>
	  <listitem>
		<para>
		  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 
		  <ulink url="http://xmlsoft.org/downloads.html">http://xmlsoft.org/downloads.html</ulink>.
		</para>
	  </listitem>
	  
	  <listitem>
		<para>
		  GDAL, version 1.6 or higher.  This is needed for raster support and will be required in final
		  release of PostGIS 2.0.
		  <ulink url="http://trac.osgeo.org/gdal/wiki/DownloadSource">http://trac.osgeo.org/gdal/wiki/DownloadSource</ulink>.
		</para>
	  </listitem>
	</itemizedlist>

	<para>
	  <emphasis role="bold">Optional</emphasis>
	</para>

	<itemizedlist>
	  <listitem>
		<para>
		  GTK (requires GTK+2.0) to compile the shp2pgsql-gui shape file loader.
		  <ulink url="http://www.gtk.org/">
			http://www.gtk.org/
		  </ulink>
		  .
		</para>
	  </listitem>
	  
	  <listitem>
		<para>
		  Apache Ant (<filename>ant</filename>) is required for building any of
		  the drivers under the <filename>java</filename> directory. Ant is
		  available from
		  <ulink url="http://ant.apache.org">
			http://ant.apache.org
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
		  DocBook (<filename>xsltproc</filename>) is required for building the
		  documentation. Docbook is available from
		  <ulink url="http://www.docbook.org/">
			http://www.docbook.org/
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
		  DBLatex (<filename>dblatex</filename>) is required for building the
		  documentation in PDF format. DBLatex is available from
		  <ulink url="http://dblatex.sourceforge.net/">
			http://dblatex.sourceforge.net/
		  </ulink>
		  .
		</para>
	  </listitem>

	  <listitem>
		<para>
		  ImageMagick (<filename>convert</filename>) is required to generate the
		  images used in the documentation. ImageMagick is available from
		  <ulink url="http://www.imagemagick.org/">
			http://www.imagemagick.org/
		  </ulink>
		  .
		</para>
	  </listitem>
	</itemizedlist>
  </sect1>

  <sect1>
	<title>Getting the Source</title>

	<para>
	  Retrieve the PostGIS source archive from the downloads website
	  <ulink url="http://www.postgis.org/download/postgis-&last_release_version;.tar.gz">
		http://www.postgis.org/download/postgis-&last_release_version;.tar.gz
	  </ulink>
	</para>

	<programlisting>wget http://www.postgis.org/download/postgis-&last_release_version;.tar.gz
tar -xvzf postgis-&last_release_version;.tar.gz</programlisting>

	<para>
	  This will create a directory called
	  <varname>postgis-&last_release_version;</varname> in the current working
	  directory.
	</para>

	<para>
	  Alternatively, checkout the source from the
	  <ulink url="http://subversion.tigris.org/">
		svn
	  </ulink>
	  repository
	  <ulink url="http://svn.osgeo.org/postgis/trunk/">
		http://svn.osgeo.org/postgis/trunk/
	  </ulink>
	  .
	</para>

	<programlisting>svn checkout http://svn.osgeo.org/postgis/trunk/ postgis-&last_release_version;</programlisting>

	<para>
	  Change into the newly created
	  <varname>postgis-&last_release_version;</varname> directory to continue
	  the installation.
	</para>
  </sect1>

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

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

	<para>
	  The PostGIS module is an extension to the PostgreSQL backend server. As
	  such, PostGIS &last_release_version; <emphasis>requires</emphasis> full
	  PostgreSQL server headers access in order to compile. It can be built
	  against PostgreSQL versions &min_postgres_version; or higher. Earlier
	  versions of PostgreSQL are <emphasis>not</emphasis> supported.
	</para>

	<para>
	  Refer to the PostgreSQL installation guides if you haven't already
	  installed PostgreSQL.
	  <ulink url="http://www.postgresql.org">
		http://www.postgresql.org
	  </ulink>
	  .
	</para>

	<note>
	  <para>
		For GEOS functionality, when you install PostgresSQL you may 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>
	</note>

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

	<sect2>
	  <title>Configuration</title>

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

	  <para>
		<command>./configure</command>
	  </para>

	  <para>
		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 <command>./configure</command>, the script accepts
		several parameters for those who have the required libraries and
		programs in non-standard locations.
	  </para>

	  <para>
		The following list shows only the most commonly used parameters. For a
		complete list, use the <command>--help</command> or
		<command>--help=short</command> parameters.
	  </para>

	  <variablelist>
		<varlistentry>
		  <term><command>--prefix=PREFIX</command></term>
		  <listitem>
			<para>
			  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.
			</para>

			<caution>
			  <para>
				This parameter is currently broken, as the package will only
				install into the PostgreSQL installation directory. Visit
				<ulink url="http://trac.osgeo.org/postgis/ticket/160">
				  http://trac.osgeo.org/postgis/ticket/160
				</ulink>
				to track this bug.
			  </para>
			</caution>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-pgconfig=FILE</command></term>
		  <listitem>
			<para>
			  PostgreSQL provides a utility called <command>pg_config</command>
			  to enable extensions like PostGIS to locate the PostgreSQL
			  installation directory. Use this parameter
			  (<command>--with-pgconfig=/path/to/pg_config</command>) to
			  manually specify a particular PostgreSQL installation that PostGIS
			  will build against.
			</para>
		  </listitem>
		</varlistentry>
		
		<varlistentry>
		  <term><command>--with-gdalconfig=FILE</command></term>
		  <listitem>
			<para>
			  GDAL, a required library, provides functionality needed for raster support
			  <command>gdal-config</command> to enable software installations to
			  locate the GDAL installation directory. Use this parameter
			  (<command>--with-gdalconfig=/path/to/gdal-config</command>) to
			  manually specify a particular GDAL installation that PostGIS will
			  build against.			  
			</para>
		  </listitem>
		</varlistentry>

		<varlistentry>
		  <term><command>--with-geosconfig=FILE</command></term>
		  <listitem>
			<para>
			  GEOS, a required geometry library, provides a utility called
			  <command>geos-config</command> to enable software installations to
			  locate the GEOS installation directory. Use this parameter
			  (<command>--with-geosconfig=/path/to/geos-config</command>) to
			  manually specify a particular GEOS installation that PostGIS will
			  build against.
			</para>
		  </listitem>
		</varlistentry>
		

		<varlistentry>
		  <term><command>--with-projdir=DIR</command></term>
		  <listitem>
			<para>
			  Proj4 is a reprojection library required by PostGIS. Use this
			  parameter (<command>--with-projdir=/path/to/projdir</command>) to
			  manually specify a particular Proj4 installation directory that
			  PostGIS will build against.
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <term><command>--with-gui</command></term>
		  <listitem>
			<para>
			  Compile the data import GUI (requires GTK+2.0).  This will create shp2pgsql-gui graphical interface
			  to shp2pgsql.
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <term><command>--with-raster</command></term>
		  <listitem>
			<para>
			  Compile with raster support.  This will build rtpostgis-&last_release_version; library and rtpostgis.sql file.  This may not
			  be required in final release as plan is to build in raster support by default. 
			</para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <term><command>--with-topology</command></term>
		  <listitem>
			<para>
			  Compile with topology support.  This will build the topology.sql file.  There is no corresponding library
			  as all logic needed for topology is in postgis-&last_release_version; library.
			</para>
		  </listitem>
		</varlistentry>
	  </variablelist>
	  <note>
		<para>
		  If you obtained PostGIS from the SVN
		  <ulink url="http://svn.osgeo.org/postgis/trunk/">
			repository
		  </ulink>
		  , the first step is really to run the script
		</para>

		<para>
		  <command>./autogen.sh</command>
		</para>

		<para>
		  This script will generate the <command>configure</command> script that
		  in turn is used to customize the installation of PostGIS.
		</para>

		<para>
		  If you instead obtained PostGIS as a tarball, running
		  <command>./autogen.sh</command> is not necessary as
		  <command>configure</command> has already been generated.
		</para>
	  </note>
	</sect2>

	<sect2>
	  <title>Building</title>

	  <para>
		Once the Makefile has been generated, building PostGIS is as simple as
		running
	  </para>

	  <para>
		<command>make</command>
	  </para>

	  <para>
		The last line of the output should be "<code>PostGIS was built
		successfully. Ready to install.</code>"
	  </para>

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

	  <para>
		<command>make comments</command>
	  </para>
	</sect2>

	<sect2>
	  <title>Testing</title>

	  <para>
		If you wish to test the PostGIS build, run
	  </para>

	  <para>
		<command>make check</command>
	  </para>

	  <para>
		The above command will run through various checks and regression tests
		using the generated library against an actual PostgreSQL database.
	  </para>

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

	  <caution>
		<para>
		  Currently, the <command>make check</command> relies on the
		  <code>PATH</code> and <code>PGPORT</code> environment variables when
		  performing the checks - it does <emphasis>not</emphasis> use the
		  PostgreSQL version that may have been specified using the
		  configuration parameter <command>--with-pgconfig</command>. 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
		  <ulink url="http://trac.osgeo.org/postgis/ticket/186">
			http://trac.osgeo.org/postgis/ticket/186
		  </ulink>
		  to track this bug.
		</para>
	  </caution>

	  <para>
		If successful, the output of the test should be similar to the
		following:
	  </para>

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


Suite: print_suite
  Test: test_lwprint_default_format ... passed
  Test: test_lwprint_format_orders ... passed
  Test: test_lwprint_optional_format ... passed
  Test: test_lwprint_oddball_formats ... passed
  Test: test_lwprint_bad_formats ... passed
Suite: Misc Suite
  Test: test_misc_force_2d ... passed
  Test: test_misc_simplify ... passed
  Test: test_misc_count_vertices ... passed
  Test: test_misc_area ... passed
  Test: test_misc_wkb ... passed
Suite: PointArray Suite
  Test: test_ptarray_append_point ... passed
  Test: test_ptarray_append_ptarray ... passed
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_lwline_crossing_bugs ... 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
  Test: test_isclosed ... passed
Suite: PostGIS Measures Suite
  Test: test_mindistance2d_tolerance ... passed
  Test: test_rect_tree_contains_point ... passed
  Test: test_rect_tree_intersects_tree ... passed
  Test: test_lwgeom_segmentize2d ... passed
Suite: WKT Out Suite
  Test: test_wkt_out_point ... passed
  Test: test_wkt_out_linestring ... passed
  Test: test_wkt_out_polygon ... passed
  Test: test_wkt_out_multipoint ... passed
  Test: test_wkt_out_multilinestring ... passed
:
:
--Run Summary: Type      Total     Ran  Passed  Failed
               suites       17      17     n/a       0
               tests       143     143     143       0
               asserts    1228    1228    1228       0


Creating spatial db postgis_reg
 Postgis 2.0.0SVN - 2011-01-11 15:33:37
   GEOS: 3.3.0-CAPI-1.7.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
 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
 polyhedralsurface. ok
 out_geometry. ok
 out_geography. ok
 in_gml. ok
 in_kml. ok
 iscollection. ok
 regress_ogc. ok
 regress_ogc_cover. ok
 regress_ogc_prep. ok
 regress_bdpoly. ok
 regress_proj. ok
 dump. ok
 dumppoints. ok
 wmsservers_new. ok
 tickets. ok
 remove_repeated_points. ok
 split. ok
 relatematch. ok
 regress_buffer_params. ok
 hausdorff. ok
 clean. ok
 sharedpaths. ok
 snap. ok

Run tests: 55
Failed: 0
</programlisting>
	</sect2>

	<sect2>
	  <title>Installation</title>

	  <para>
		To install PostGIS, type
	  </para>

	  <para>
		<command>make install</command>
	  </para>

	  <para>
		This will copy the PostGIS installation files into their appropriate
		subdirectory specified by the <command>--prefix</command> configuration
		parameter. In particular:
	  </para>

	  <itemizedlist>
		<listitem>
		  <para>
			The loader and dumper binaries are installed in
			<filename>[prefix]/bin</filename>.
		  </para>
		</listitem>

		<listitem>
		  <para>
			The SQL files, such as <filename>postgis.sql</filename>, are
			installed in <filename>[prefix]/share/contrib</filename>.
		  </para>
		</listitem>

		<listitem>
		  <para>
			The PostGIS libraries are installed in
			<filename>[prefix]/lib</filename>.
		  </para>
		</listitem>
	  </itemizedlist>

	  <para>
		If you previously ran the <command>make comments</command> command to
		generate the <filename>postgis_comments.sql</filename>, <filename>raster_comments.sql</filename> file, install the
		sql file by running
	  </para>

	  <para>
		<command>make comments-install</command>
	  </para>

	  <note>
		<para>
		  <filename>postgis_comments.sql</filename> and <filename>raster_comments.sql</filename> was separated from the
		  typical build and installation targets since with it comes the extra
		  dependency of <command>xsltproc</command>.
		</para>
	  </note>
	</sect2>
  </sect1>

  <sect1>
	<title>Create a spatially-enabled database</title>

	<para>
	  The first step in creating a PostGIS database is to create a simple
	  PostgreSQL database.
	</para>

	<para>
	  <command>createdb [yourdatabase]</command>
	</para>

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

	<para>
	  <command>createlang plpgsql [yourdatabase]</command>
	</para>

	<para>
	  Now load the PostGIS object and function definitions into your database by
	  loading the <filename>postgis.sql</filename> definitions file (located in
	  <filename>[prefix]/share/contrib</filename> as specified during the
	  configuration step).
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f postgis.sql</command>
	</para>

	<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. This will
	  permit you to perform ST_Transform() operations on geometries.
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f spatial_ref_sys.sql</command>
	</para>

	<para>
	  If you wish to add comments to the PostGIS functions, the final step is to
	  load the <filename>postgis_comments.sql</filename> into your spatial
	  database. The comments can be viewed by simply typing <command>\dd
	  [function_name]</command> from a <command>psql</command> terminal window.
	</para>

	<para>
	  <command>psql -d [yourdatabase] -f postgis_comments.sql</command>
	</para>
  </sect1>

  <sect1 id="templatepostgis">
	<title>Create a spatially-enabled database from a 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>
  </sect1>

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

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

	  <para>
		After compiling you should find several <filename>postgis_upgrade*.sql</filename> files.  Install the one
		for your version of PostGIS.  For example <filename>postgis_upgrade_13_to_15.sql</filename> should be used if you are upgrading 
		from PostGIS 1.3 to 1.5.
	  </para>

	  <programlisting>$ psql -f postgis_upgrade_13_to_15.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>postgis_upgrade*.sql</filename> 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:
		</para>

		<programlisting>$ utils/postgis_proc_upgrade.pl postgis.sql &gt; postgis_upgrade.sql</programlisting>
	  </note>
	</sect2>

	<sect2 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 postgis.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 postgis.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; truncate spatial_ref_sys;
DROP
newdb=&gt; \i spatial_ref_sys.sql</programlisting>
	</sect2>
  </sect1>

  <sect1>
	<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 &min_postgres_version;
		  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
		  &min_postgres_version; 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>
  </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>