postgis/README.postgis

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

:Version: 3.2.0alpha1
:Date: 2021-09-10
:Website: https://postgis.net

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
  ./deps        Extra dependencies
  ./doc         PostGIS Documentation
  ./extensions  Support for the PostgreSQL Extensions framework
  ./extras      Various pieces that didn't belong to mainstream
                (package management specfiles, WFS_locks
                  , sample WKB parser, postgis_tiger_geocoder)
  ./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.6 and above.

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

* PROJ4 (Required, Version 4.9.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.

    https://proj.org

* GEOS (Required, Version 3.6 or higher)
  - 3.9+ is needed to take advantage of
    fixed precision enhancements in overlay functions
  - 3.7+ is needed just for the ST_FrechetDistance function

  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().

    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
  for translation support
  (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 2 or higher 3+ is strongly recommended)

  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``

* CGAL 4.1+ and SFCGAL 1.3.2+ (Optional) needed for advanced 3D support

  https://github.com/Oslandia/SFCGAL

* protobuf-c (Optional, Version 1.1.0 or higher)

  The protobuf-c library and compiler is required for ST_AsMVT and
  ST_AsGeobuf output. Also, pkg-config is required to verify the correct
  minimum version of protobuf-c.

    https://github.com/protobuf-c/protobuf-c

  To get packages on apt-based systems:

    apt-get install libprotobuf-c-dev protobuf-c-compiler

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

To configure PostGIS, run::

  ./configure

If the file is missing you must be using a development version
of the code. In that case call ./autogen.sh to generate it.

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

If you want to compile PostGIS *without* Protobuf formats support,
you must provide the ``--without-protobuf`` option.

PostGIS will be compiled with sfcgal support if it is found.
You can explicitly state the location with --with-sfcgal=path/to/sfcgal

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

DEBUGGING
---------

The normal build and testing procedure might not be enough for development and
debugging as that requires a debug build of PostgreSQL and other proper compilation
flags throughout. A way to get such an environment is to use the same docker images
as the PostGIS CI setup and that can be done on a *nix host by first running this
in a cloned postgis repository to later get core dump log output:

> sudo bash ./ci/travis/logbt --setup

Then you can run the following to get a docker container up and running with the
correct requirements already in place and the postgis repository (at `/postgis`)
mounted into it:

> docker run -it --mount type=bind,source=/postgis,target=/src/postgis \
postgis/postgis-build-env:pg13-geos39-gdal31-proj71 /bin/bash

And finally the following command inside the container will build and run all the
postgis tests:

> bash ./ci/travis/run_usan_gcc.sh

You can make customized versions of `run_usan_gcc.sh` to run only specific tests
and skip redundant steps.

If you need to get debug level logging in the PostgreSQL logs you can get it by
manipulating configuration in the container. Add these lines after the `./configure`
step:

```sh
sed -i 's/POSTGIS_DEBUG_LEVEL [0-9]$/POSTGIS_DEBUG_LEVEL 4/' postgis_config.h
sed -i 's/#log_min_messages = warning/log_min_messages = debug5/' \
/var/lib/postgresql/postgresql.conf
```

Note that PostgreSQL logs are directed to `/tmp/logfile` in fx. `run_usan_gcc.sh`.

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.
Enabling spatial functionality requires a PostgreSQL super-user.

    CREATE EXTENSION postgis;


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

Upgrade PostGIS using the "ALTER EXTENSION" facility.

  ALTER EXTENSION postgis UPDATE TO '2.2.0';


USAGE
-----

Try the following example SQL statements to create tables with
geometry columns::

  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 ST_Intersects(geom, ST_MakeEnvelope(2,2,3,3));

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

  CREATE TABLE geotest (
    id INT4,
    name VARCHAR(32),
    geopoint GEOMETRY(POINT, 4326)
    );

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

  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.