mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-24 17:12:35 +00:00
648 lines
22 KiB
XML
648 lines
22 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter>
|
|
<title>Installation</title>
|
|
|
|
<para>
|
|
This chapter details the steps required to install PostGIS.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>Short Version</title>
|
|
|
|
<programlisting>tar xvfz postgis-&last_release_version;.tar.gz
|
|
cd postgis-&last_release_version;
|
|
./configure
|
|
make
|
|
make install
|
|
createlang plpgsql yourdatabase
|
|
psql -d yourdatabase -f lwpostgis.sql
|
|
psql -d yourdatabase -f spatial_ref_sys.sql</programlisting>
|
|
|
|
<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 8.1 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>
|
|
</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.5.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.0.0 or greater. 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://trac.osgeo.org/geos/">
|
|
http://trac.osgeo.org/geos/
|
|
</ulink>
|
|
.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
<emphasis role="bold">Optional</emphasis>
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<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 id="PGInstall">
|
|
<title>PostGIS</title>
|
|
|
|
<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. 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>
|
|
|
|
<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>
|
|
|
|
<note>
|
|
<para>
|
|
If you would like to compile your own, more specific instructions for
|
|
<ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiWinCompile">
|
|
Windows Compiling Guide
|
|
</ulink>
|
|
and others are available in
|
|
<ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiMain">
|
|
PostGIS User Wiki
|
|
</ulink>
|
|
</para>
|
|
</note>
|
|
|
|
<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>
|
|
For 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 or Mac
|
|
</para>
|
|
|
|
<para>
|
|
For the below - if you are not logged in as root, you may need to
|
|
use sudo or su commands to run the make make install commands
|
|
</para>
|
|
</note>
|
|
</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>postgis.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;/
|
|
./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. If you have not
|
|
compiled or installed Proj4, follow the instructions below if
|
|
you wish to compile Proj4 from source.
|
|
</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. If you have not compiled or installed Geos, follow the
|
|
instructions that follow below to compile Geos from source.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<programlisting>make clean && make
|
|
make install
|
|
ldconfig</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-&last_proj_release_version;.tar.gz
|
|
gzip -d -c proj-&last_proj_release_version;.tar.gz | tar xvf -
|
|
cd proj-&last_proj_release_version;
|
|
./configure && make clean && make
|
|
make install
|
|
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://download.osgeo.org/geos/geos-&last_geos_release_version;.tar.bz2
|
|
bunzip2 -d -c geos-&last_geos_release_version;.tar.bz2 | tar xvf -
|
|
cd geos-&last_geos_release_version;
|
|
./configure && make clean && make
|
|
make install
|
|
ldconfig
|
|
cd ..</programlisting>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
PostGIS requires the PL/pgSQL procedural language extension. Before
|
|
loading the <filename>postgis.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>postgis.sql</filename> definitions
|
|
file.
|
|
</para>
|
|
|
|
<programlisting># psql -d [yourdatabase] -f lwgeom/postgis.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 >= 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 postgis_upgrade.sql script in
|
|
your spatial database:
|
|
</para>
|
|
|
|
<programlisting>$ psql -f postgis_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>postgis_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 postgis.sql > postgis_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 > 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 > 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 < 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 !
|
|
</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=> drop spatial_ref_sys;
|
|
DROP
|
|
newdb=> \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>
|