1PostGIS - Geographic Information Systems Extensions to PostgreSQL
2=================================================================
3
4:Version: 3.2.0
5:Date: 2021-12-17
6:Website: https://postgis.net
7
8This distribution contains a module which implements GIS simple features, ties
9the features to R-tree indexing, and provides many spatial functions for
10accessing and analyzing geographic data.
11
12Directory structure::
13
14 ./ Build scripts and install directions
15 ./deps Extra dependencies
16 ./doc PostGIS Documentation
17 ./extensions Support for the PostgreSQL Extensions framework
18 ./extras Various pieces that didn't belong to mainstream
19 (package management specfiles, WFS_locks
20 , sample WKB parser, postgis_tiger_geocoder)
21 ./liblwgeom LWGEOM geometry library
22 ./libpgcommon PostGIS library to bridge LWGEOM to PostgreSQL
23 ./loader A program to convert ESRI Shape files into SQL text suitable
24 for uploading into a PostGIS/PostgreSQL database and a program
25 for converting PostGIS spatial tables into shapefiles
26 ./postgis PostGIS library source code
27 ./raster PostGIS rasters extension source code
28 ./regress Online regression tests
29 ./topology PostGIS topology extension source code
30 ./utils Utility scripts for PostGIS (upgrade, profiling, ...)
31
32
33REQUIREMENTS
34------------
35
36PostGIS is compatible with PostgreSQL 9.6 and above.
37
38You *must* have the full PostgreSQL - including server headers - installed for
39this to work.
40
41* PROJ4 (Required, Version 4.9.0 or higher):
42
43 The PROJ4 catographic projection library is required if you want to use the
44 ST_Transform() function to reproject features within the database.
45
46 https://proj.org
47
48* GEOS (Required, Version 3.6 or higher)
49 - 3/10+ for ST_MakeValid enhancements
50 - 3.9+ is needed to take advantage of
51 fixed precision enhancements in overlay functions
52 - 3.7+ is needed just for the ST_FrechetDistance function
53
54 The GEOS library provides support for exact topological tests such as
55 ST_Touches(), ST_Contains(), ST_Disjoint() and spatial operations such as
56 ST_Intersection(), ST_Union() and ST_Buffer().
57
58 http://trac.osgeo.org/geos/
59
60* XML SUPPORT (Required, Version 2.5.0 or higher):
61
62 The LibXML2 library is required to use the ST_GeomFromGML() and
63 ST_GeomFromKML() functionality.
64
65 http://xmlsoft.org/
66
67* GNU gettext
68
69 The loader, and hence PostGIS, requires GNU gettext 0.14 or higher
70 for translation support
71 (typically in libc on GNU/Linux, in which case 0.17 is required).
72
73* JSON-C (Optional, Version 0.9 or higher)
74
75 JSON-C is used to import GeoJSON via the function ST_GeomFromGeoJson().
76
77 http://github.com/json-c/json-c/wiki
78
79 You can get it installed in apt-based systems using:
80
81 apt-get install libjson0-dev
82
83* GDAL (Optional, Version 2 or higher 3+ is strongly recommended)
84
85 GDAL (http://gdal.org) is *required* if you want to compile PostGIS
86 with raster support. To compile without raster support you
87 must ``./configure --without-raster``
88
89* CGAL 4.1+ and SFCGAL 1.3.2+ (Optional) needed for advanced 3D support
90
91 https://github.com/Oslandia/SFCGAL
92
93* protobuf-c (Optional, Version 1.1.0 or higher)
94
95 The protobuf-c library and compiler is required for ST_AsMVT and
96 ST_AsGeobuf output. Also, pkg-config is required to verify the correct
97 minimum version of protobuf-c.
98
99 https://github.com/protobuf-c/protobuf-c
100
101 To get packages on apt-based systems:
102
103 apt-get install libprotobuf-c-dev protobuf-c-compiler
104
105CONFIGURATION
106-------------
107
108To configure PostGIS, run::
109
110 ./configure
111
112If the file is missing you must be using a development version
113of the code. In that case call ./autogen.sh to generate it.
114
115The results of the configuration can be easily seen within the
116``postgis_config.h`` file.
117
118If ``pg_config`` can't be found in your ``$PATH`` configure will complain
119and refuse to proceed. You can specify it using the
120``--with-pgconfig=/path/to/pg_config`` flag.
121
122If PROJ4 has been installed but cannot be found, configure will complain and
123refuse to proceed. You can specify an alternative installation directory using
124the ``--with-projdir=DIR`` option.
125
126If GEOS has been installed but cannot be found, configure will complain and
127refuse to proceed. You can specify an alternative ``geos-config`` file using
128the ``--with-geosconfig=/path/to/geos-config`` option.
129
130If GDAL cannot be found, configure will complain and refuse to proceed.
131You can either proceed without raster support using ``--without-raster``
132or use ``--with-gdalconfig=/path/to/gdal-config`` option.
133
134By default, both Topology and Raster extensions are enabled in ``./configure``.
135
136If you want to compile PostGIS *without* Raster support,
137you must provide the ``--without-raster`` option.
138
139If you want to compile PostGIS *without* Topology support,
140you must provide the ``--without-topology`` option.
141
142If you want to compile PostGIS *without* Protobuf formats support,
143you must provide the ``--without-protobuf`` option.
144
145PostGIS will be compiled with sfcgal support if it is found.
146You can explicitly state the location with --with-sfcgal=path/to/sfcgal
147
148See ``./configure --help`` for more options.
149
150
151BUILD
152-----
153
154PostGIS uses the GNU make (aka gmake) for building. To build PostGIS library
155and utilities, as postgres run::
156
157 make
158
159
160TESTING
161-------
162
163You want to run regress tests before installation. To do so, as postgres run::
164
165 make check
166
167The above will create a test database with PostGIS extensions, run tests and
168then drop the test database.
169
170Final lines of output contain a summary of test results: run, succeeded,
171failed. If you have any failure please file a bug report using the online bug
172tracker: http://trac.osgeo.org/postgis/report/3
173
174DEBUGGING
175---------
176
177The normal build and testing procedure might not be enough for development and
178debugging as that requires a debug build of PostgreSQL and other proper compilation
179flags throughout. A way to get such an environment is to use the same docker images
180as the PostGIS CI setup and that can be done on a *nix host by first running this
181in a cloned postgis repository to later get core dump log output:
182
183> sudo bash ./ci/travis/logbt --setup
184
185Then you can run the following to get a docker container up and running with the
186correct requirements already in place and the postgis repository (at `/postgis`)
187mounted into it:
188
189> docker run -it --mount type=bind,source=/postgis,target=/src/postgis \
190postgis/postgis-build-env:pg13-geos39-gdal31-proj71 /bin/bash
191
192And finally the following command inside the container will build and run all the
193postgis tests:
194
195> bash ./ci/travis/run_usan_gcc.sh
196
197You can make customized versions of `run_usan_gcc.sh` to run only specific tests
198and skip redundant steps.
199
200If you need to get debug level logging in the PostgreSQL logs you can get it by
201manipulating configuration in the container. Add these lines after the `./configure`
202step:
203
204```sh
205sed -i 's/POSTGIS_DEBUG_LEVEL [0-9]$/POSTGIS_DEBUG_LEVEL 4/' postgis_config.h
206sed -i 's/#log_min_messages = warning/log_min_messages = debug5/' \
207/var/lib/postgresql/postgresql.conf
208```
209
210Note that PostgreSQL logs are directed to `/tmp/logfile` in fx. `run_usan_gcc.sh`.
211
212INSTALLATION
213------------
214
215To install PostGIS library and utilities, as root run::
216
217 make install
218
219Installation paths will typically be derived by ``pg_config``:
220
221 - Lib in ``pg_config --pkglibdir``
222 - Binaries (loader/dumper) in ``pg_config --bindir``
223 - Important support files in ``[prefix]/share/contrib``
224 - Manual pages in ``[prefix]/man``
225 - Documentation in in ``[prefix]/share/doc``
226
227Where `[prefix]` above is extracted from ``pg_config --configure``.
228
229You can change them using ``./configure`` switches. See CONFIGURATION section.
230
231
232CREATING NEW SPATIAL DATABASES
233------------------------------
234
235PostGIS support must be enabled for each database that requires its usage.
236Enabling spatial functionality requires a PostgreSQL super-user.
237
238 CREATE EXTENSION postgis;
239
240
241UPGRADING EXISTING SPATIAL DATABASES
242------------------------------------
243
244Upgrade PostGIS using the "ALTER EXTENSION" facility.
245
246 ALTER EXTENSION postgis UPDATE TO '2.2.0';
247
248
249USAGE
250-----
251
252Try the following example SQL statements to create tables with
253geometry columns::
254
255 CREATE TABLE geom_test ( gid int4, geom geometry, name varchar(25) );
256 INSERT INTO geom_test ( gid, geom, name )
257 VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square');
258 INSERT INTO geom_test ( gid, geom, name )
259 VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' );
260 INSERT INTO geom_test ( gid, geom, name )
261 VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' );
262 SELECT * from geom_test WHERE ST_Intersects(geom, ST_MakeEnvelope(2,2,3,3));
263
264The following SQL creates proper full entries in the ``SPATIAL_REF_SYS``
265and ``GEOMETRY_COLUMNS`` tables, and ensures that all geometries are created
266with an SRID::
267
268 CREATE TABLE geotest (
269 id INT4,
270 name VARCHAR(32),
271 geopoint GEOMETRY(POINT, 4326)
272 );
273
274 INSERT INTO geotest (id, name, geopoint)
275 VALUES (1, 'Olympia', ST_GeomFromText('POINT(-122.90 46.97)', 4326));
276 INSERT INTO geotest (id, name, geopoint)
277 VALUES (2, 'Renton', ST_GeomFromText('POINT(-122.22 47.50)', 4326));
278
279 SELECT name, AsText(geopoint) FROM geotest;
280
281
282Spatial Indexes
283~~~~~~~~~~~~~~~
284
285PostgreSQL provides support for GiST spatial indexing. The GiST scheme offers
286indexing even on large objects, using a system of "lossy" indexing where a
287large object is proxied by a smaller one in the index. In the case of the
288PostGIS indexing system, all objects are proxied in the index by their
289bounding boxes.
290
291You can build a GiST index with::
292
293 CREATE INDEX <indexname>
294 ON <tablename>
295 USING GIST ( <geometryfield> );
296
297Always run the ``VACUUM ANALYZE <tablename>`` on your tables after creating an
298index. This gathers statistics which the query planner uses to optimize index
299usage.
300
301
302PostGIS Topology support
303~~~~~~~~~~~~~~~~~~~~~~~~
304
305See topology/README for more informations about topology support.
306
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}