mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-25 01:22:47 +00:00
d13b2d4a5a
git-svn-id: http://svn.osgeo.org/postgis/trunk@2196 b70326c6-7e19-0410-871a-916f4a2858ee |
||
---|---|---|
doc | ||
extras | ||
jdbc | ||
jdbc2 | ||
loader | ||
lwgeom | ||
regress | ||
topology | ||
utils | ||
.cvsignore | ||
autogen.sh | ||
CHANGES | ||
config.guess | ||
config.h.in | ||
config.sub | ||
configure.in | ||
COPYING | ||
CREDITS | ||
geos_version.sh | ||
GNUmakefile | ||
install-sh | ||
make_dist.sh | ||
Makefile | ||
Makefile.config.in | ||
README.postgis | ||
spatial_ref_sys.sql | ||
TODO | ||
Version.config |
PostGIS - Geographic Information Systems Extensions to PostgreSQL ~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ VERSION: 1.1.0 (2005/12/??) MORE INFORMATION: http://postgis.refractions.net 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. ./lwgeom Library source code. ./jdbc2 Extensions to the PostgreSQL JDBC drivers to support the GIS objects. ./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 Regression tests REQUIREMENTS ------------ PostGIS is compatible with PostgreSQL 7.2 and above. You *must* have full PostgreSQL - including server headers - installed for this to work. Note that server headers are not installed by default until PostgreSQL 8.0.0 and require the special 'install-all-headers' Makefile rule. SEE THE NOTE ON GEOS SUPPORT BELOW FOR SPECIAL COMPILATION INSTRUCTIONS * PROJ4 SUPPORT (Recommended): The Proj4 reprojection library is required if you want to use the transform() function to reproject features within the database. http://www.remotesensing.org/proj * SPATIAL PREDICATE / GEOS SUPPORT (Recommended): The GEOS library provides support for exact topological tests such as Touches(), Contains(), Disjoint() and spatial operations such as Intersection(), Union() and Buffer(). http://geos.refractions.net In order to use the GEOS support, you *may* need to specially compile your version of PostgreSQL to link the C++ runtime library. To do this, invoke the PgSQL configuration script this way: LDFLAGS=-lstdc++ ./configure --your-options-go-here The initial LDFLAGS variable is passed through to the Makefile and adds the C++ library to the linking stage. CONFIGURATION ------------- To configure PostGIS, as root run: ./configure Last lines from configure output will give a configuration summary. If pg_config can't be found in your $PATH configure will complan and refuse to proceed. You can specify it using the --with-pgsql-PATH flag. If you don't see PROJ4 in the report (and you did have installed it) this means that proj4 installation dir could not be found. You can specify it using the --with-proj=DIR flag. If you don't see GEOS in the report (and you did have installed it) this means that geos-config could not be found. You can specify it using the --with-geos=PATH flag. See ./configure --help for more options. INSTALLATION ------------ To build and install PostGIS library and utilities, as root run: make make install Installation paths will be derived by ``pg_config'': - Lib in `pg_config --pkglibdir` - Binaries (loader/dumper) in `pg_config --bindir` - Important support files in [prefix]/share/contrib - Manpages in [prefix]/man - Documentation in in [prefix]/share/doc Where [prefix] above is exctracted by `pg_config --configure`. TESTING ------- To run PostGIS regression tests, as postgres run: make regress 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://postgis.refractions.net/bugs. SPATIAL DATABASE CREATION ------------------------- PostGIS support must be enabled for each database that requires its usage. This is done by feeding the lwpostgis.sql (the enabler script) file to the targed 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 lwpostgis.sql -d yourdatabase Your database should now be spatially enabled. UPGRADE ------- Upgrading PostGIS can be tricky, because the underlying C libraries which support the object types and geometries may have changed between versions. For this purpose PostGIS provides an utility script to restore a dump produced with the pg_dump -Fc command. It is experimental so redirecting its output to a file will help in case of problems. The procedure is as follow: # Create a "custom-format" dump of the database you want # to upgrade (let's call it "olddb") $ pg_dump -Fc olddb olddb.dump # Restore the dump contextually upgrading postgis into # a new database. The new database doesn't have to exist. # Let's call it "newdb" $ sh utils/postgis_restore.pl lwpostgis.sql newdb olddb.dump > restore.log # Check that all restored dump objects really had to be restored from dump # and do not conflict with the ones defined in lwpostgis.sql $ grep ^KEEPING restore.log | less # If upgrading from PostgreSQL < 7.5 to >= 7.5 you might want to # drop the attrelid, varattnum and stats columns in the geometry_columns # table, which are no-more needed. Keeping them won't hurt. # !!! DROPPING THEM WHEN REALLY NEEDED WILL DO HURT !!!! $ psql newdb -c "ALTER TABLE geometry_columns DROP attrelid" $ psql newdb -c "ALTER TABLE geometry_columns DROP varattnum" $ psql newdb -c "ALTER TABLE geometry_columns DROP stats" # spatial_ref_sys table is restore from the dump, to ensure your custom # additions are kept, but the distributed one might contain modification # so you should backup your entries, drop the table and source the new one. # If you did make additions we assume you know how to backup them before # upgrading the table. Replace of it with the new one is done like this: $ psql newdb newdb=> drop table spatial_ref_sys; DROP newdb=> \i spatial_ref_sys.sql Following is the "old" procedure description. IT SHOULD BE AVOIDED if possible, as it will leave in the database many spurious functions. It is kept in this document as a "backup" in case postgis_restore.pl won't work for you: pg_dump -t "*" -f dumpfile.sql yourdatabase dropdb yourdatabase createdb yourdatabase createlang plpgsql yourdatabase psql -f lwpostgis.sql -d yourdatabase psql -f dumpfile.sql -d yourdatabase vacuumdb -z yourdatabase 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.