mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-24 09:02:37 +00:00
325 lines
10 KiB
Plaintext
325 lines
10 KiB
Plaintext
PostGIS - Geographic Information Systems Extensions to PostgreSQL
|
|
~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
VERSION: 2.0.0alpha4 (YYYY/MM/DD)
|
|
|
|
MORE INFORMATION: http://postgis.org
|
|
|
|
This distribution contains a module which implements GIS simple
|
|
features, ties the features to rtree indexing, and provides some
|
|
spatial functions for accessing and analyzing geographic data.
|
|
|
|
Directory structure:
|
|
|
|
./ Build scripts and install directions.
|
|
./liblwgeom LWGEOM geometry library.
|
|
./postgis PostGIS library source code.
|
|
./raster PostGIS rasters support source code.
|
|
./topology PostGIS topology source code.
|
|
./java/ejb EJB Java support
|
|
./java/jdbc Extensions to the PostgreSQL JDBC drivers to support
|
|
the GIS objects.
|
|
./java/pljava PostgreSQL PL/Java spatial object support
|
|
./doc PostGIS Documentation
|
|
./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
|
|
Shape files.
|
|
./utils Utility scripts for PostGIS (upgrade, profiling, ...)
|
|
./extras Various pieces that didn't belong to mainstream
|
|
(package management specfiles, WFS_locks, sample wkb parser)
|
|
./regress Online regression tests
|
|
./extensions Files to support the PostgreSQL 9.1+ "extensions" framework
|
|
|
|
|
|
REQUIREMENTS
|
|
------------
|
|
|
|
PostGIS is compatible with PostgreSQL 8.3 and above.
|
|
|
|
You *must* have the full PostgreSQL - including server headers - installed
|
|
for this to work.
|
|
|
|
* PROJ4 SUPPORT (Required, Version 4.5.0 or better):
|
|
|
|
The Proj4 reprojection library is required if you want to use the
|
|
transform() function to reproject features within the database.
|
|
|
|
http://trac.osgeo.org/proj/
|
|
|
|
* SPATIAL PREDICATE / GEOS SUPPORT (Required, Version 3.1.1 or better):
|
|
|
|
The GEOS library provides support for exact topological tests
|
|
such as Touches(), Contains(), Disjoint() and spatial operations
|
|
such as Intersection(), Union() and Buffer().
|
|
|
|
http://trac.osgeo.org/geos/
|
|
|
|
* XML SUPPORT (Required):
|
|
|
|
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).
|
|
|
|
If you want to compile PostGIS with raster support, you additionally
|
|
must have installed:
|
|
|
|
* GDAL (Version 1.6.0 or higher)
|
|
|
|
* Python GDAL bindings
|
|
|
|
See README.raster for further information on how to compile PostGIS with
|
|
Raster support.
|
|
|
|
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 you want to compile PostGIS with Raster support, you must provide
|
|
the --with-raster option.
|
|
|
|
If you want to compile PostGIS with Topology support, you must provide
|
|
the --with-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
|
|
|
|
See README.raster to know how to build PostGIS Raster extension.
|
|
|
|
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 db.
|
|
|
|
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.
|
|
|
|
See README.raster to know how to test PostGIS raster extension.
|
|
|
|
|
|
INSTALLATION
|
|
------------
|
|
|
|
To install PostGIS library and utilities, as postgres 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 by `pg_config --configure`.
|
|
|
|
You can change them using ./configure switches.
|
|
See CONFIGURATION section.
|
|
|
|
See README.raster to know how to install PostGIS Raster extension.
|
|
|
|
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.
|
|
|
|
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.txt
|
|
|
|
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 db.
|
|
|
|
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 <filename>legacy.sql</filename> 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 <filename>uninstall_legacy.sql</filename>.
|
|
|
|
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', GeometryFromText('POINT(-122.90 46.97)',1));
|
|
INSERT INTO geotest (id, name, geopoint)
|
|
VALUES (2, 'Renton', GeometryFromText('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 Raster support ---
|
|
|
|
See README.raster to know how to enable raster support on a spatially enabled database.
|