mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-25 17:42:38 +00:00
feef574560
git-svn-id: http://svn.osgeo.org/postgis/trunk@3534 b70326c6-7e19-0410-871a-916f4a2858ee
430 lines
17 KiB
XML
430 lines
17 KiB
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://trac.osgeo.org/proj/">http://trac.osgeo.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://trac.osgeo.org/geos/">http://trac.osgeo.org/geos/</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 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>
|
|
|
|
<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-4.6.0.tar.gz
|
|
tar xvzf proj-4.6.0.tar.gz
|
|
cd proj-4.6.0
|
|
./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-3.0.3.tar.bz2
|
|
tar xvjf geos-3.0.3.tar.bz2
|
|
cd geos-3.0.3
|
|
./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>
|