PostGIS - Geographic Information Systems Extensions to PostgreSQL ================================================================= :Version: 2.3.0beta1 :Date: 2016-09-06 :Website: http://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 ./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) ./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.1 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 - 3.4+ is strongly recommended and needed for full features): 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 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 1.8.0 or higher 1.9+ is strongly recommended) GDAL (http://gdal.org) is *required* if you want to compile PostGIS with raster or extension support. To compile without raster support you must ``./configure --without-raster`` (also disables extension) * CGAL 4.1+ and SFCGAL (Optional) needed for advanced 3D support https://github.com/Oslandia/SFCGAL 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. 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 ON USING GIST ( ); Always run the ``VACUUM ANALYZE `` 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.