InstallationRequirementsPostGIS has the following requirements for building and
usage:A complete installation of PostgreSQL (including server
headers). PostgreSQL is available from http://www.postgresql.org.
Version 8.1 or higher is required.GNU C compiler (gcc). Some other ANSI C
compilers can be used to compile PostGIS, but we find far fewer
problems when compiling with gcc.GNU Make (gmake or
make). For many systems, GNU
make is the default version of make. Check the
version by invoking make -v. Other versions of
make may not process the PostGIS
Makefile properly.Proj4 reprojection library. The Proj4 library is
used to provide coordinate reprojection support within PostGIS. Proj4
is available for download from http://trac.osgeo.org/proj/.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 http://trac.osgeo.org/geos/.(Recommended) Apache Ant (ant). Required for
building any of the drivers under the java directory. Ant is available for download from http://ant.apache.org.PostGISThe PostGIS module is an extension to the PostgreSQL backend server.
As such, PostGIS &last_release_version; requires
full PostgreSQL server headers access in order to compile. The PostgreSQL
source code is available at http://www.postgresql.org.PostGIS &last_release_version; can be built against PostgreSQL
versions 8.1.0 or higher. Earlier versions of PostgreSQL are
not supported.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.If you would like to compile your own, more specific instructions for Windows Compiling Guide
and others are available in PostGIS User WikiCompiling and Installing from SourceBefore you can compile the PostGIS server modules, you must
compile and install the PostgreSQL package.For GEOS functionality you might need to
explicitly link PostgreSQL against the standard C++ library:LDFLAGS=-lstdc++ ./configure [YOUR OPTIONS HERE]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.The steps that follow are for Linux users. They will not work on Windows or MacFor 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 commandsRetrieve the PostGIS source archive from http://postgis.refractions.net/download/postgis-&last_release_version;.tar.gz.
Uncompress and untar the archive. configure.All files are installed using information provided by
pg_configLibraries are installed
[pkglibdir]/lib/contrib.Important support files such as
postgis.sql are installed in
[prefix]/share/contrib.Loader and dumper binaries are installed in
[bindir]/.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;/
./configureMake and InstallPostgreSQL provides a utility called pg_config to enable
extensions like PostGIS to locate the PostgreSQL installation directory.
If ./configure didn't find pg_config,
try using the --with-pgconfig=/path/to/pg_config switch to specify a particular
PostgreSQL installation.Proj4 is now required in order to build and use PostGIS.
If ./configure didn't find the Proj4 library,
try using the --with-projdir=/path/to/projdir 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.GEOS is now required in order to build and use PostGIS.
If ./configure didn't find it, try using the
--with-geosconfig=/path/to/geos-config switch to specify the full path
to the geos-config program. If you have not compiled or installed Geos, follow the
instructions that follow below to compile Geos from source.make clean && make
make install
ldconfigIf you are missing proj based on above or running a version below 4.5, then install by following these steps.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 ..If you are missing geos based on above or running a version below 3.0, then install by following these steps.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 ..PostGIS requires the PL/pgSQL procedural language extension.
Before loading the postgis.sql file, you must
first enable PL/pgSQL. You should use the
createlang command. The PostgreSQL Programmer's
Guide has the details if you want to this manually for some
reason.# createlang plpgsql [yourdatabase]Now load the PostGIS object and function definitions into your
database by loading the postgis.sql definitions
file.# psql -d [yourdatabase] -f lwgeom/postgis.sqlThe PostGIS server extensions are now loaded and ready to
use.For a complete set of EPSG coordinate system definition
identifiers, you can also load the
spatial_ref_sys.sql definitions file and populate
the SPATIAL_REF_SYS table.# psql -d [yourdatabase] -f spatial_ref_sys.sqlCreating PostGIS spatially-enabled databases from an in-built
templateSome packaged distributions of PostGIS (in particular the Win32
installers for PostGIS >= 1.1.5) load the PostGIS functions into a
template database called template_postgis. If the
template_postgis 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.From the shell:# createdb -T template_postgis my_spatial_dbFrom SQL:postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgisUpgradingUpgrading existing spatial databases can be tricky as it requires
replacement or introduction of new PostGIS object definitions.Unfortunately not all definitions can be easily replaced in a live
database, so sometimes your best bet is a dump/reload process.PostGIS provides a SOFT UPGRADE procedure for minor or bugfix
releases, and an HARD UPGRADE procedure for major releases.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.Soft upgradeSoft upgrade consists of sourcing the postgis_upgrade.sql
script in your spatial database:$ psql -f postgis_upgrade.sql -d your_spatial_databaseIf 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.If you can't find the
postgis_upgrade.sql 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:$ utils/postgis_proc_upgrade.pl postgis.sql > postgis_upgrade.sqlHard upgradeBy 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 Release Notes appendix reports for each
version whether you need a dump/reload (HARD UPGRADE) to
upgrade.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:Create a "custom-format" dump of the database you want to
upgrade (let's call it "olddb")$ pg_dump -Fc olddb > olddb.dumpRestore 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:$ sh utils/postgis_restore.pl postgis.sql newdb olddb.dump -E=UNICODE > restore.logCheck that all restored dump objects really had to be restored
from dump and do not conflict with the ones defined in
postgis.sql$ grep ^KEEPING restore.log | lessIf 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 !$ 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"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:$ psql newdb
newdb=> drop spatial_ref_sys;
DROP
newdb=> \i spatial_ref_sys.sqlCommon ProblemsThere are several things to check when your installation or
upgrade doesn't go as you expected.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:SELECT version();If you are running an RPM based distribution, you can check
for the existence of pre-installed packages using the
rpm command as follows: rpm -qa | grep
postgresqlAlso check that configure has correctly detected the location and
version of PostgreSQL, the Proj4 library and the GEOS library.The output from configure is used to generate the
postgis_config.h file. Check that the
POSTGIS_PGSQL_VERSION, POSTGIS_PROJ_VERSION
and POSTGIS_GEOS_VERSION variables have been set correctly.JDBCThe 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.Enter the java/jdbc sub-directory of the PostGIS
distribution.Run the ant command. Copy the
postgis.jar file to wherever you keep your java
libraries.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:# ant -Dclasspath=/path/to/postgresql-jdbc.jarPostgreSQL JDBC drivers can be downloaded from
http://jdbc.postgresql.org.Loader/DumperThe data loader and dumper are built and installed automatically as
part of the PostGIS build. To build and install them manually:# cd postgis-&last_release_version;/loader
# make
# make installThe loader is called shp2pgsql and converts
ESRI Shape files into SQL suitable for loading in PostGIS/PostgreSQL. The
dumper is called pgsql2shp and converts PostGIS
tables (or queries) into ESRI Shape files. For more verbose documentation,
see the online help, and the manual pages.