Lines 1-214
Link Here
|
1 |
PostGIS - Geographic Information Systems Extensions to PostgreSQL |
|
|
2 |
~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
3 |
|
4 |
VERSION: 1.0.0 (2005/01/13) |
5 |
|
6 |
MORE INFORMATION: http://postgis.refractions.net |
7 |
|
8 |
INTRODUCTION: |
9 |
This distribution contains a module which implements GIS simple |
10 |
features, ties the features to rtree indexing, and provides some |
11 |
spatial functions for accessing and analyzing geographic data. |
12 |
|
13 |
Directory structure: |
14 |
|
15 |
./ Build scripts and install directions. |
16 |
./lwgeom Library source code. |
17 |
./jdbc Extensions to the PostgreSQL JDBC drivers to support |
18 |
the GIS objects. |
19 |
./doc Documentation on the code, objects and functions |
20 |
provided. |
21 |
./loader A program to convert ESRI Shape files into SQL text |
22 |
suitable for uploading into a PostGIS/PostgreSQL database |
23 |
and a program for converting PostGIS spatial tables into |
24 |
Shape files.. |
25 |
./examples Small programs which demonstrate ways of accessing |
26 |
GIS data. |
27 |
|
28 |
|
29 |
INSTALLATION: |
30 |
|
31 |
PostGIS is compatible with PostgreSQL 7.2 and above. |
32 |
|
33 |
To install the module, move this directory to the "contrib" directory of your |
34 |
PostgreSQL source installation. Alternately, point PGSQL_SRC at your |
35 |
PostgreSQL source tree either in an environment variable or editing |
36 |
Makefile.config. |
37 |
|
38 |
You *must* have a PostgreSQL source tree, and you *must* have succesfully |
39 |
built and installed it for this to work. |
40 |
|
41 |
SEE THE NOTE ON GEOS SUPPORT BELOW FOR SPECIAL COMPILATION INSTRUCTIONS |
42 |
|
43 |
|
44 |
* PROJ4 SUPPORT (Recommended): |
45 |
The Proj4 reprojection library is required if you want to use the |
46 |
transform() function to reproject features within the database. |
47 |
|
48 |
http://www.remotesensing.org/proj |
49 |
|
50 |
Install Proj4 in the default location. |
51 |
Edit the postgis Makefile.config and change the USE_PROJ variable to 1 |
52 |
and ensure that the PROJ_DIR variable points to your Proj4 |
53 |
installation location (/usr/local is the default). |
54 |
|
55 |
* SPATIAL PREDICATE / GEOS SUPPORT (Recommended): |
56 |
The GEOS library provides support for exact topological tests |
57 |
such as Touches(), Contains(), Disjoint() and spatial operations |
58 |
such as Intersection(), Union() and Buffer(). |
59 |
|
60 |
http://geos.refractions.net |
61 |
|
62 |
In order to use the GEOS support, you *may* need to specially compile |
63 |
your version of PostgreSQL to link the C++ runtime library. |
64 |
To do this, invoke the PgSQL configuration script this way: |
65 |
|
66 |
LDFLAGS=-lstdc++ ./configure --your-options-go-here |
67 |
|
68 |
The initial LDFLAGS variable is passed through to the Makefile and |
69 |
adds the C++ library to the linking stage. |
70 |
Once you have compiled PgSQL with C++ support, you can enable GEOS |
71 |
support in PostGIS by setting the USE_GEOS variable in the PostGIS |
72 |
Makefile.config to 1, and ensure that the GEOS_DIR variable points |
73 |
to your GEOS installation location (/usr/local is the default). |
74 |
|
75 |
|
76 |
To compile PostGIS, as root run: |
77 |
|
78 |
make |
79 |
make install |
80 |
|
81 |
PostGIS now requires the PL/pgSQL procedural language in order to operate |
82 |
correctly. To install PL/pgSQL use the 'createlang' program from the PostgreSQL |
83 |
installation. (The PostgreSQL Programmer's Guide has details if you want |
84 |
to this manually for some reason.) |
85 |
|
86 |
As postgres run: |
87 |
|
88 |
createlang plpgsql yourdatabase |
89 |
psql -f lwpostgis.sql -d yourdatabase |
90 |
|
91 |
Installation should now be complete. |
92 |
|
93 |
|
94 |
UPGRADING: |
95 |
|
96 |
Upgrading PostGIS can be tricky, because the underlying C libraries which |
97 |
support the object types and geometries may have changed between versions. |
98 |
|
99 |
For this purpose PostGIS provides an utility script to restore a dump |
100 |
produced with the pg_dump -Fc command. It is experimental so redirecting |
101 |
its output to a file will help in case of problems. The procedure is |
102 |
as follow: |
103 |
|
104 |
# Create a "custom-format" dump of the database you want |
105 |
# to upgrade (let's call it "olddb") |
106 |
$ pg_dump -Fc olddb olddb.dump |
107 |
|
108 |
# Restore the dump contextually upgrading postgis into |
109 |
# a new database. The new database doesn't have to exist. |
110 |
# Let's call it "newdb" |
111 |
$ sh utils/postgis_restore.pl lwpostgis.sql newdb olddb.dump > restore.log |
112 |
|
113 |
# Check that all restored dump objects really had to be restored from dump |
114 |
# and do not conflict with the ones defined in lwpostgis.sql |
115 |
$ grep ^KEEPING restore.log | less |
116 |
|
117 |
# If upgrading from PostgreSQL < 7.5 to >= 7.5 you might want to |
118 |
# drop the attrelid, varattnum and stats columns in the geometry_columns |
119 |
# table, which are no-more needed. Keeping them won't hurt. |
120 |
# !!! DROPPING THEM WHEN REALLY NEEDED WILL DO HURT !!!! |
121 |
$ psql newdb -c "ALTER TABLE geometry_columns DROP attrelid" |
122 |
$ psql newdb -c "ALTER TABLE geometry_columns DROP varattnum" |
123 |
$ psql newdb -c "ALTER TABLE geometry_columns DROP stats" |
124 |
|
125 |
# spatial_ref_sys table is restore from the dump, to ensure your custom |
126 |
# additions are kept, but the distributed one might contain modification |
127 |
# so you should backup your entries, drop the table and source the new one. |
128 |
# If you did make additions we assume you know how to backup them before |
129 |
# upgrading the table. Replace of it with the new one is done like this: |
130 |
$ psql newdb |
131 |
newdb=> drop table spatial_ref_sys; |
132 |
DROP |
133 |
newdb=> \i spatial_ref_sys.sql |
134 |
|
135 |
Following is the "old" procedure description. IT SHOULD BE AVOIDED if possible, |
136 |
as it will leave in the database many spurious functions. It is kept in this document |
137 |
as a "backup" in case postgis_restore.pl won't work for you: |
138 |
|
139 |
pg_dump -t "*" -f dumpfile.sql yourdatabase |
140 |
dropdb yourdatabase |
141 |
createdb yourdatabase |
142 |
createlang plpgsql yourdatabase |
143 |
psql -f lwpostgis.sql -d yourdatabase |
144 |
psql -f dumpfile.sql -d yourdatabase |
145 |
vacuumdb -z yourdatabase |
146 |
|
147 |
|
148 |
USAGE: |
149 |
|
150 |
Try the following example SQL statements to create non-OpenGIS tables and |
151 |
geometries: |
152 |
|
153 |
CREATE TABLE geom_test ( gid int4, geom geometry,name varchar(25) ); |
154 |
INSERT INTO geom_test ( gid, geom, name ) |
155 |
VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square'); |
156 |
INSERT INTO geom_test ( gid, geom, name ) |
157 |
VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' ); |
158 |
INSERT INTO geom_test ( gid, geom, name ) |
159 |
VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' ); |
160 |
SELECT * from geom_test WHERE geom && 'BOX3D(2 2 0,3 3 0)'::box3d; |
161 |
|
162 |
The following SQL creates proper OpenGIS entries in the SPATIAL_REF_SYS |
163 |
and GEOMETRY_COLUMNS tables, and ensures that all geometries are created |
164 |
with an SRID. |
165 |
|
166 |
INSERT INTO SPATIAL_REF_SYS |
167 |
( SRID, AUTH_NAME, AUTH_SRID, SRTEXT ) VALUES |
168 |
( 1, 'EPSG', 4269, |
169 |
'GEOGCS["NAD83", |
170 |
DATUM[ |
171 |
"North_American_Datum_1983", |
172 |
SPHEROID[ |
173 |
"GRS 1980", |
174 |
6378137, |
175 |
298.257222101 |
176 |
] |
177 |
], |
178 |
PRIMEM["Greenwich",0], |
179 |
UNIT["degree",0.0174532925199433]]' |
180 |
); |
181 |
|
182 |
CREATE TABLE geotest ( |
183 |
id INT4, |
184 |
name VARCHAR(32) |
185 |
); |
186 |
|
187 |
SELECT AddGeometryColumn('db','geotest','geopoint',1,'POINT',2); |
188 |
|
189 |
INSERT INTO geotest (id, name, geopoint) |
190 |
VALUES (1, 'Olympia', GeometryFromText('POINT(-122.90 46.97)',1)); |
191 |
INSERT INTO geotest (id, name, geopoint) |
192 |
VALUES (2, 'Renton', GeometryFromText('POINT(-122.22 47.50)',1)); |
193 |
|
194 |
SELECT name,AsText(geopoint) FROM geotest; |
195 |
|
196 |
|
197 |
Spatial Indexes: |
198 |
|
199 |
PostgreSQL provides support for GiST spatial indexing. The GiST scheme offers |
200 |
indexing even on large objects, using a system of "lossy" indexing where |
201 |
a large object is proxied by a smaller one in the index. In the case |
202 |
of the PostGIS indexing system, all objects are proxied in the index by |
203 |
their bounding boxes. |
204 |
|
205 |
You can build a GiST index with: |
206 |
|
207 |
CREATE INDEX <indexname> |
208 |
ON <tablename> |
209 |
USING GIST ( <geometryfield> ); |
210 |
|
211 |
Always run the "VACUUM ANALYZE <tablename>" on your tables after |
212 |
creating an index. This gathers statistics which the query planner |
213 |
uses to optimize index usage. |
214 |
|