README.postgis

PostGIS - Geographic Information Systems Extensions to PostgreSQL
=================================================================

:Version: 2.1.0
:Date: 2013-MM-DD
:Website: http://postgis.org

This distribution contains a module which implements GIS simple features, ties
the features to R-tree indexing, and provides many spatial functions for
accessing and analyzing geographic data.

Directory structure::

  ./            Build scripts and install directions
  ./doc         PostGIS Documentation
  ./extensions  Support for the PostgreSQL 9.1+ Extensions framework
  ./extras      Various pieces that didn't belong to mainstream
                (package management specfiles, WFS_locks, sample WKB parser)
  ./java/ejb    EJB Java support
  ./java/jdbc   Extensions to the PostgreSQL JDBC drivers to support
                the GIS objects
  ./liblwgeom   LWGEOM geometry library
  ./libpgcommon PostGIS library to bridge LWGEOM to PostgreSQL
  ./loader      A program to convert ESRI Shape files into SQL text suitable
                for uploading into a PostGIS/PostgreSQL database and a program
                for converting PostGIS spatial tables into shapefiles
  ./postgis     PostGIS library source code
  ./raster      PostGIS rasters extension source code
  ./regress     Online regression tests
  ./topology    PostGIS topology extension source code
  ./utils       Utility scripts for PostGIS (upgrade, profiling, ...)


REQUIREMENTS
------------

PostGIS is compatible with PostgreSQL 9.0 and above.

You *must* have the full PostgreSQL - including server headers - installed for
this to work.

* PROJ4 (Required, Version 4.6.0 or higher):

  The PROJ4 catographic projection library is required if you want to use the
  ST_Transform() function to reproject features within the database.

    http://trac.osgeo.org/proj/

* GEOS (Required, Version 3.3.0 or higher):

  The GEOS library provides support for exact topological tests such as
  ST_Touches(), ST_Contains(), ST_Disjoint() and spatial operations such as
  ST_Intersection(), ST_Union() and ST_Buffer(). GEOS 3.4+ is recommended.

    http://trac.osgeo.org/geos/

* XML SUPPORT (Required, Version 2.5.0 or higher):

  The LibXML2 library is required to use the ST_GeomFromGML() and
  ST_GeomFromKML() functionality.

    http://xmlsoft.org/

* GNU gettext

   The loader, and hence PostGIS, requires GNU gettext 0.14 or higher
   (typically in libc on GNU/Linux, in which case 0.17 is required).

* JSON-C (Optional, Version 0.9 or higher)

  JSON-C is used to import GeoJSON via the function ST_GeomFromGeoJson().

    http://github.com/json-c/json-c/wiki

  You can get it installed in apt-based systems using::

    apt-get install libjson0-dev

* GDAL (Optional, Version 1.6.0 or higher)

  GDAL (http://gdal.org) is *required* if you want to compile PostGIS 
  with raster support.  To compile without raster support you 
  must ``./configure --without-raster``


CONFIGURATION
-------------

To configure PostGIS, run::

  ./configure

The results of the configuration can be easily seen within the
``postgis_config.h`` file.

If ``pg_config`` can't be found in your ``$PATH`` configure will complain
and refuse to proceed. You can specify it using the
``--with-pgconfig=/path/to/pg_config`` flag.

If PROJ4 has been installed but cannot be found, configure will complain and
refuse to proceed. You can specify an alternative installation directory using
the ``--with-projdir=DIR`` option.

If GEOS has been installed but cannot be found, configure will complain and
refuse to proceed. You can specify an alternative ``geos-config`` file using
the ``--with-geosconfig=/path/to/geos-config`` option.

If GDAL cannot be found, configure will complain and refuse to proceed.
You can either procede without raster support using ``--without-raster``
or use ``--with-gdalconfig=/path/to/gdal-config`` option.

By default, both Topology and Raster extensions are enabled in ``./configure``.

If you want to compile PostGIS *without* Raster support, you must provide the
``--without-raster`` option.

If you want to compile PostGIS *without* Topology support, you must provide the
``--without-topology`` option.

See ``./configure --help`` for more options.


BUILD
-----

PostGIS uses the GNU make (aka gmake) for building. To build PostGIS library
and utilities, as postgres run::

  make


TESTING
-------

You want to run regress tests before installation. To do so, as postgres run::

  make check

The above will create a test database with PostGIS extensions, run tests and
then drop the test database.

Final lines of output contain a summary of test results: run, succeeded,
failed. If you have any failure please file a bug report using the online bug
tracker: http://trac.osgeo.org/postgis/report/3


INSTALLATION
------------

To install PostGIS library and utilities, as root run::

  make install

Installation paths will typically be derived by ``pg_config``:

 - Lib in ``pg_config --pkglibdir``
 - Binaries (loader/dumper) in ``pg_config --bindir``
 - Important support files in ``[prefix]/share/contrib``
 - Manual pages in ``[prefix]/man``
 - Documentation in in ``[prefix]/share/doc``

Where `[prefix]` above is extracted from ``pg_config --configure``.

You can change them using ``./configure`` switches. See CONFIGURATION section.


CREATING NEW SPATIAL DATABASES
------------------------------

PostGIS support must be enabled for each database that requires its usage.
This is done by feeding the ``postgis.sql`` (the enabler script) file to the
target database.

The enabler script requires the PL/pgSQL procedural language in order to
operate correctly, you can use the ``createlang`` program from the PostgreSQL
installation.

(The PostgreSQL Programmer's Guide has details if you want to do this
manually for some reason.)

So, as postgres run::

  createlang plpgsql <yourdatabase>
  psql -f postgis/postgis.sql -d <your_database>

Your database should now be spatially enabled.


ADDING RASTER SUPPORT TO A SPATIAL DATABASE
-------------------------------------------

To enable raster support you must first load the ``postgis.sql`` file.
You can then load the ``rtpostgis.sql`` file.

  psql -f postgis/rtpostgis.sql -d <your_database>


UPGRADING EXISTING SPATIAL DATABASES
------------------------------------

Upgrading 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.

SOFT UPGRADE
~~~~~~~~~~~~

Soft upgrade consists of sourcing the ``postgis_upgrade_*.sql`` script in your
spatial database:

 * ``postgis_upgrade_13_to_15.sql``, upgrade a 1.3.x database to 1.5
 * ``postgis_upgrade_15_to_15.sql``, upgrade a 1.4.x database to 1.5
 * ``postgis_upgrade_16_minor.sql``, upgrade a 1.5.x database to the latest
   minor release

If a soft upgrade is not possible the script will abort and no harm will be
done. You can then move on to the HARD UPGRADE process. Always try a soft
upgrade first; they are much simpler.

HARD UPGRADE
~~~~~~~~~~~~

Hard upgrade is a PostgreSQL dump/restore procedure combined with a filter to
selectively update PostGIS functions and objects to point to a new library
version.

Hard upgrades are required when object definitions have changed, aggregates
have changed or been added, and when the underlying PostgreSQL database itself
has undergone a major update.

For this purpose, PostGIS provides a utility script to restore a dump in
"custom" format. The hard upgrade procedure is as follows::

  # [1] Create a "custom-format" dump of the database you want
  # to upgrade (let's call it "olddb")
  $ pg_dump -Fc -f olddb.dump olddb

  # [2] Do a fresh install of PostGIS in a new database
  # (let's call it "newdb").
  # Refer to CREATING NEW SPATIAL DATABASES for instructions

  # [3] Restore the dump into your new database.
  $ perl utils/postgis_restore.pl -v olddb.dump \
      2> restore.log | psql newdb 2> errors.log

The ``spatial_ref_sys`` entries found in your dump will be restored, but they
will not override existing ones in ``spatial_ref_sys``.  This is to ensure that
fixes in the official set will be properly propagated to restored databases.
If for any reason you really want your own overrides of standard entries just
don't load the ``spatial_ref_sys.sql`` file when creating the new database.

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 load ``legacy.sql``
before restoring the dump for all your functions and views etc. to properly
come back.  Only do this if *really* needed. Consider upgrading your views and
functions before dumping instead, if possible.  The deprecated functions can be
later removed by loading ``uninstall_legacy.sql``.


USAGE
-----

Try the following example SQL statements to create non-OpenGIS tables and
geometries::

  CREATE TABLE geom_test ( gid int4, geom geometry, name varchar(25) );
  INSERT INTO geom_test ( gid, geom, name )
    VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square');
  INSERT INTO geom_test ( gid, geom, name )
    VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' );
  INSERT INTO geom_test ( gid, geom, name )
    VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' );
  SELECT * from geom_test WHERE geom && 'BOX3D(2 2 0,3 3 0)'::box3d;

The following SQL creates proper OpenGIS entries in the ``SPATIAL_REF_SYS``
and ``GEOMETRY_COLUMNS`` tables, and ensures that all geometries are created
with an SRID::

  INSERT INTO SPATIAL_REF_SYS
    ( SRID, AUTH_NAME, AUTH_SRID, SRTEXT ) VALUES
    ( 1, 'EPSG', 4269,
      'GEOGCS["NAD83",
        DATUM[
          "North_American_Datum_1983",
          SPHEROID[
          "GRS 1980",
          6378137,
          298.257222101
        ]
      ],
      PRIMEM["Greenwich",0],
      UNIT["degree",0.0174532925199433]]'
    );

  CREATE TABLE geotest (
    id INT4,
    name VARCHAR(32)
    );

  SELECT AddGeometryColumn('db', 'geotest', 'geopoint', 1, 'POINT', 2);

  INSERT INTO geotest (id, name, geopoint)
    VALUES (1, 'Olympia', ST_GeomFromText('POINT(-122.90 46.97)', 1));
  INSERT INTO geotest (id, name, geopoint)
    VALUES (2, 'Renton', ST_GeomFromText('POINT(-122.22 47.50)', 1));

  SELECT name, AsText(geopoint) FROM geotest;


Spatial Indexes
~~~~~~~~~~~~~~~

PostgreSQL provides support for GiST spatial indexing. The GiST scheme offers
indexing even on large objects, using a system of "lossy" indexing where a
large object is proxied by a smaller one in the index.  In the case of the
PostGIS indexing system, all objects are proxied in the index by their
bounding boxes.

You can build a GiST index with::

  CREATE INDEX <indexname>
    ON <tablename>
    USING GIST ( <geometryfield> );

Always run the ``VACUUM ANALYZE <tablename>`` on your tables after creating an
index. This gathers statistics which the query planner uses to optimize index
usage.


PostGIS Topology support
~~~~~~~~~~~~~~~~~~~~~~~~

See topology/README for more informations about topology support.