mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-25 09:32:46 +00:00
c5835306e4
git-svn-id: http://svn.osgeo.org/postgis/trunk@11413 b70326c6-7e19-0410-871a-916f4a2858ee
348 lines
12 KiB
Plaintext
348 lines
12 KiB
Plaintext
PostGIS - Geographic Information Systems Extensions to PostgreSQL
|
|
=================================================================
|
|
|
|
:Version: 2.1.0
|
|
:Date: 2013-MM-DD
|
|
: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 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
|
|
- 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) needed for raster support
|
|
Also needed to install PostGIS using CREATE EXTENSION postgis; syntax
|
|
|
|
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 (Optional) needed for advanced 3D support
|
|
https://github.com/Oslandia/SFCGAL
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
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.
|