mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-24 17:12:35 +00:00
e7b239a993
git-svn-id: http://svn.osgeo.org/postgis/trunk@7695 b70326c6-7e19-0410-871a-916f4a2858ee
1037 lines
32 KiB
XML
1037 lines
32 KiB
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 (1.8 or higher is preferable since some things will not work well with lower versions). 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>
|
|
CUnit (<filename>CUnit</filename>). This is needed for regression testing. <ulink url="http://cunit.sourceforge.net/">http://cunit.sourceforge.net/</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 and other
|
|
package comments files raster_comments.sql, topology_comments.sql are
|
|
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 id="create_new_db">
|
|
<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 below command. For PostgreSQL 8.4+, this is generally already installed
|
|
</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>
|
|
|
|
<para>
|
|
Install raster support
|
|
</para>
|
|
|
|
<para>
|
|
<command>psql -d [yourdatabase] -f rtpostgis.sql</command>
|
|
</para>
|
|
|
|
<para>
|
|
Install raster support comments. This will provide quick help info for each raster function
|
|
using psql or PgAdmin or any other PostgreSQL tool that can show function comments
|
|
</para>
|
|
|
|
<para>
|
|
<command>psql -d [yourdatabase] -f raster_comments.sql</command>
|
|
</para>
|
|
<para>
|
|
Install topology support
|
|
</para>
|
|
|
|
<para>
|
|
<command>psql -d [yourdatabase] -f topology/topology.sql</command>
|
|
</para>
|
|
|
|
<para>
|
|
Install topology support comments. This will provide quick help info for each topology function / type
|
|
using psql or PgAdmin or any other PostgreSQL tool that can show function comments
|
|
</para>
|
|
|
|
<para>
|
|
<command>psql -d [yourdatabase] -f topology/topology_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 >= 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 a 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 a 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. If you are moving from PostGIS 1.* to PostGIS 2.* or from PostGIS 2.* prior to r7409, you need to do a HARD UPGRADE.
|
|
</para>
|
|
|
|
<programlisting>psql -f postgis_upgrade_20_minor.sql -d your_spatial_database</programlisting>
|
|
|
|
<note>
|
|
<para>
|
|
If you can't find the <filename>postgis_upgrade*.sql</filename> specific for upgrading your version you are using a version too early for
|
|
a soft upgrade and need to do a HARD UPGRADE.
|
|
</para>
|
|
</note>
|
|
</sect2>
|
|
|
|
<sect2 id="hard_upgrade">
|
|
<title>Hard upgrade</title>
|
|
|
|
<para>
|
|
By HARD UPGRADE we mean full dump/reload of postgis-enabled databases.
|
|
You need a 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>
|
|
Create a "custom-format" dump of the database you want to upgrade (let's
|
|
call it "olddb") include binary blobs (-b) and verbose (-v) output. The user can be the owner of the db, need not be postgres
|
|
super account.
|
|
</para>
|
|
<note><para>The following described process will show quite a few errors. DO NOT BE ALARMED. This is expected
|
|
since functions and objects already defined in the new version of postgis will fail when pg_restore tries to restore them.
|
|
This is desired. Errors you do need to be cognizant of are those of failed restore of tables other than geometry_columns and spatial_ref_sys.</para>
|
|
</note>
|
|
|
|
<programlisting>pg_dump -h localhost -p 5432 -U postgres -Fc -b -v -f "/somepath/olddb.backup" olddb</programlisting>
|
|
|
|
<para>If you made custom entries to your spatial_ref_sys.sql, you may want to backup this table separately or copy out the custom records.
|
|
The spatial_ref_sys you will end up with will be the new one packaged with the PostGIS install.</para>
|
|
|
|
<para>Do a fresh install of PostGIS in a new database -- we'll refer to this database as <varname>newdb</varname>.
|
|
Please refer to <xref linkend="create_new_db" /> for instructions on how to do this.</para>
|
|
|
|
<para>Install the <filename>legacy_compatibility_layer.sql</filename>. This installs the minimum legacy functions needed to restore
|
|
most old databases. If your database is really old or you know you've been using long
|
|
deprecated functions in your views and functions, you might need to install the <filename>legacy.sql</filename>
|
|
instead of <filename>legacy_compatbility_layer.sql</filename>
|
|
for all your functions and views etc. to properly come back.</para>
|
|
|
|
<programlisting>psql -h localhost -p 5432 -U postgres -d newdb -f legacy_compatibility_layer.sql</programlisting>
|
|
|
|
<para>Restore your backup into your fresh <varname>newdb</varname> database using pg_restore.</para>
|
|
|
|
<programlisting>pg_restore -h localhost -p 5432 -U postgres -d newdb "/somepath/olddb.backup"</programlisting>
|
|
|
|
<para>Finally run the <filename>postgis_upgrade_20_minor.sql</filename> script in this new database. NOTE: This step is
|
|
very important because many functions have been revised to use default parameters, and
|
|
your old install would therefore restore these which would result in ambiguous name conflicts when called.</para>
|
|
<programlisting>psql -h localhost -p 5432 -U postgres -d newdb -f postgis_upgrade_20_minor.sql</programlisting>
|
|
|
|
<para>If your applications or GIS tools rely on old deprecated functions, you can restore these by installing the <filename>legacy.sql</filename></para>
|
|
<programlisting>psql -h localhost -p 5432 -U postgres -d newdb -f legacy.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 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>
|
|
|
|
<listitem>
|
|
<para>If your upgrade fails, make sure you are restoring into a database that already has PostGIS installed.</para>
|
|
<programlisting>SELECT postgis_full_version();</programlisting>
|
|
</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>
|