[mirror] PostGIS spatial database extension to PostgreSQL https://postgis.net
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

8.4 KiB

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

:Version: 3.2.0dev
:Date: 2021-xx-xx
: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.

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

* 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


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.