forked from postgis/postgis
/
README.postgis
288 lines (206 loc) · 9.26 KB
/
README.postgis
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
PostGIS - Geographic Information Systems Extensions to PostgreSQL
~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
VERSION: 1.1.2 (2006/03/30)
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.
BUILD
-----
To build PostGIS library and utilities, as root run:
make
TESTING
-------
You want to run regress tests before installation.
To do so, as postgres run:
make check
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.
INSTALLATION
------------
To install PostGIS library and utilities, as root run:
make install
Installation paths will tipically 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`.
You can change them using ./configure switches.
See CONFIGURARION section.
CREATING NEW SPATIAL DATABASES
------------------------------
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 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 lwpostgis_upgrade.sql
script in your spatial database:
psql -f lwpostgis_upgrade.sql -d your_spatial_database
If a soft upgrade is not possible the script will abort and
you will be warned about HARD UPGRADE being required,
so do not hesitate to try a soft upgrade first.
--- 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 olddb olddb.dump
# Restore the dump while upgrading postgis into
# a new database.
# Note: The new database does NOT 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 < 8.0 to >= 8.0 you will 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 HARM !!!!
$ 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"
# The spatial_ref_sys table is restored 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 it with the new like this:
$ psql newdb
newdb=> drop table spatial_ref_sys;
DROP
newdb=> \i spatial_ref_sys.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', 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.