Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
C Java Perl Python Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
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: #  Create a "custom-format" dump of the database you want # to upgrade (let's call it "olddb") $ pg_dump -Fc -f olddb.dump olddb #  Do a fresh install of PostGIS in a new database # (let's call it "newdb"). # Refer to CREATING NEW SPATIAL DATABASES for instructions #  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.