Commit c1d74cf1 authored by Fabio Tranchitella's avatar Fabio Tranchitella

Merged trunk with upstream (postgis-1.1.3).

parent 33970f0a
Makefile.config
libpostgis.so.0.8
postgis.sql
postgis_undef.sql
postgis_old.sql
lwpostgis.sql
lwpostgis_upgrade.sql
.classpath
.project
config.log
config.status
configure
autom4te.cache
config.h
eclipsebin
PostGIS 1.1.3
2006/06/30
- NEW Long Transactions support.
- Can run the regress tests with 'make check' now.
- New regress test support for loader/dumper.
- BUGFIX in pgsql2shp successful return code.
- BUGFIX in shp2pgsql handling of MultiLine WKT.
- BUGFIX in affine() failing to update bounding box.
- WKT parser: forbidden construction of multigeometries with
EMPTY elements (still supported for GEOMETRYCOLLECTION).
- Added --with-proj-libdir and --with-geos-libdir configure
switches.
- JDBC:
- Improved regression tests: MultiPoint and scientific ordinates
- Fixed some minor bugs in jdbc code
- Added proper accessor functions for all fields in preparation of
making those fields private later
- Support for build Tru64 build.
- Use Jade for generating documentation.
- NEW DumpRings() function.
- BUGFIX in distance(poly,poly) giving wrong results.
- NEW AsHEXEWKB(geom, XDR|NDR) function.
- Don't link pgsql2shp to more libs then required.
- Initial support for PostgreSQL 8.2.
PostGIS 1.1.2
2006/03/30
......
......@@ -29,7 +29,7 @@ maintainer-clean: Makefile.config
$(MAKE) distclean
rm -f configure
test:
test check:
$(MAKE) -C regress test
test-clean:
......
How to release
~~~~~~~~~~~~~~
Date: 2005-12-15
Versioning Scheme
-----------------
Release version is composed by REL_MAJOR_VERSION, REL_MINOR_VERSION
and REL_MICRO_VERSION components.
By default only [REL_MICRO_VERSION] increments between releases.
[REL_MINOR_VERSION] is incremented (and MICRO set to 0) when minor
additions have been introduced (one or two functions can be considered
*micro* additions)
[REL_MAJOR_VERSION] is incremented (and MICRO and MINOR set to 0) when
a dump/reload of existing spatial databases is *REQUIRED* for things
to work or rather *HIGHLY RECOMMENDED* to get new functionalities.
Release procedure
-----------------
1) Update Version.config as specified in Versioning Scheme above.
2) Edit CHANGES: set release date and check all notable changes are
been reported.
3) Add release notes in doc/postgis.xml
4) Tag pgis_MAJ_MIN_MIC
5) Run: sh make_dist.sh MAJ.MIN.MIC
6) Publish
7) Announce
......@@ -2,7 +2,7 @@
# this file copied and adapted from PostgreSQL source
# to allow easy build on BSD systems
all install uninstall clean distclean maintainer-clean test docs docs-install docs-uninstall utils:
all install uninstall clean distclean maintainer-clean test check docs docs-install docs-uninstall utils:
@IFS=':' ; \
for dir in $$PATH; do \
for prog in gmake gnumake make; do \
......
......@@ -17,6 +17,7 @@
#
USE_PROJ=@USE_PROJ@
PROJ_DIR=@PROJ_DIR@
PROJ_LIBDIR=@PROJ_LIBDIR@
#
# Set USE_GEOS to 1 for GEOS spatial predicate and operator
......@@ -32,6 +33,7 @@ PROJ_DIR=@PROJ_DIR@
#
USE_GEOS=@USE_GEOS@
GEOS_DIR=@GEOS_DIR@
GEOS_LDFLAGS=@GEOS_LDFLAGS@
# EXPERIMENTAL! use geos C-API (only available with GEOS-2.2.x and up)
USE_GEOS_CAPI=@USE_GEOS_CAPI@
......@@ -85,6 +87,7 @@ PORTNAME=@PORTNAME@
XSLBASE=@XSLBASE@
XSLTPROC=@XSLTPROC@
PDFXMLTEX=@PDFXMLTEX@
DB2PDF=@DB2PDF@
JW=@JW@
DOC_RULE=@DOC_RULE@
......@@ -103,6 +106,7 @@ FLEX=@FLEX@
YACC=@YACC@
LN_S=@LN_S@
INSTALL=@INSTALL@ -c
PWDREGRESS=@PWDREGRESS@
INSTALL_DATA=$(INSTALL) -m 644
INSTALL_BIN=$(INSTALL) -m 755
INSTALL_LIB=$(INSTALL) -m 755
......
......@@ -99,7 +99,7 @@ TESTING
You want to run regress tests before installation.
To do so, as postgres run:
make test
make check
Final lines of output contain a summary of test results:
run, succeeded, failed. If you have any failure please
......
......@@ -8,14 +8,6 @@
support functions.
- casts between PostGIS and PostgreSQL geometry classes
======================================
2005/12/16 - PostGIS 1.1.0 closeup
======================================
- TEST TEST TEST (upgrades mainly)
- Remove type-punned warnings given by gcc-3.3 ?
======================================
2005/12/14 - other random items
======================================
......@@ -31,7 +23,7 @@
- LineMerge and Polygonize* interfaces for JTS
- More LRS functions
- More LRS functions ?
- Selectivity estimation code merge (+- pgsql-8.0.0)
......
......@@ -4,9 +4,9 @@
# shared library / release version
SO_MAJOR_VERSION=1
SO_MINOR_VERSION=1
SO_MICRO_VERSION=2
SO_MICRO_VERSION=3
# JDBC code version
JDBC_MAJOR_VERSION=1
JDBC_MINOR_VERSION=1
JDBC_MICRO_VERSION=0
JDBC_MICRO_VERSION=3
This diff is collapsed.
# This file was generated.
# It contains the lists of macros which have been traced.
# It can be safely removed.
@request = (
bless( [
'0',
1,
[
'/usr/share/autoconf'
],
[
'/usr/share/autoconf/autoconf/autoconf.m4f',
'configure.in'
],
{
'm4_pattern_forbid' => 1,
'AC_CONFIG_LIBOBJ_DIR' => 1,
'AC_TYPE_OFF_T' => 1,
'AC_C_VOLATILE' => 1,
'AC_FUNC_CLOSEDIR_VOID' => 1,
'AC_REPLACE_FNMATCH' => 1,
'AC_PROG_LIBTOOL' => 1,
'AC_FUNC_STAT' => 1,
'AC_HEADER_TIME' => 1,
'AC_FUNC_WAIT3' => 1,
'AM_AUTOMAKE_VERSION' => 1,
'AC_STRUCT_TM' => 1,
'AC_FUNC_LSTAT' => 1,
'AC_TYPE_MODE_T' => 1,
'AC_FUNC_GETMNTENT' => 1,
'AC_FUNC_STRTOD' => 1,
'AC_CHECK_HEADERS' => 1,
'AC_FUNC_STRNLEN' => 1,
'm4_sinclude' => 1,
'AC_PROG_CXX' => 1,
'AC_PATH_X' => 1,
'AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK' => 1,
'AC_PROG_AWK' => 1,
'_m4_warn' => 1,
'AC_HEADER_STDC' => 1,
'AC_HEADER_MAJOR' => 1,
'AC_FUNC_ERROR_AT_LINE' => 1,
'AC_PROG_GCC_TRADITIONAL' => 1,
'AC_LIBSOURCE' => 1,
'AC_FUNC_MBRTOWC' => 1,
'AC_STRUCT_ST_BLOCKS' => 1,
'AC_TYPE_SIGNAL' => 1,
'AC_TYPE_UID_T' => 1,
'AC_CONFIG_AUX_DIR' => 1,
'AC_PROG_MAKE_SET' => 1,
'sinclude' => 1,
'm4_pattern_allow' => 1,
'AC_DEFINE_TRACE_LITERAL' => 1,
'AC_FUNC_STRERROR_R' => 1,
'AC_PROG_CC' => 1,
'AC_FUNC_FORK' => 1,
'AC_DECL_SYS_SIGLIST' => 1,
'AC_FUNC_VPRINTF' => 1,
'AC_FUNC_STRCOLL' => 1,
'AC_PROG_YACC' => 1,
'AC_INIT' => 1,
'AC_STRUCT_TIMEZONE' => 1,
'AC_FUNC_CHOWN' => 1,
'AC_SUBST' => 1,
'AC_FUNC_ALLOCA' => 1,
'AC_CANONICAL_HOST' => 1,
'AC_FUNC_GETPGRP' => 1,
'AC_PROG_RANLIB' => 1,
'AM_INIT_AUTOMAKE' => 1,
'AC_FUNC_SETPGRP' => 1,
'AC_CONFIG_SUBDIRS' => 1,
'AC_FUNC_MMAP' => 1,
'AC_FUNC_REALLOC' => 1,
'AC_TYPE_SIZE_T' => 1,
'AC_CONFIG_LINKS' => 1,
'AC_CHECK_TYPES' => 1,
'AC_CHECK_MEMBERS' => 1,
'AM_MAINTAINER_MODE' => 1,
'AC_FUNC_UTIME_NULL' => 1,
'AC_FUNC_SELECT_ARGTYPES' => 1,
'AC_FUNC_STRFTIME' => 1,
'AC_HEADER_STAT' => 1,
'AC_C_INLINE' => 1,
'AC_PROG_CPP' => 1,
'AC_TYPE_PID_T' => 1,
'AC_C_CONST' => 1,
'AC_PROG_LEX' => 1,
'AC_CONFIG_FILES' => 1,
'include' => 1,
'AC_FUNC_SETVBUF_REVERSED' => 1,
'AC_PROG_INSTALL' => 1,
'AM_GNU_GETTEXT' => 1,
'AC_FUNC_OBSTACK' => 1,
'AC_CHECK_LIB' => 1,
'AC_FUNC_MALLOC' => 1,
'AC_FUNC_GETGROUPS' => 1,
'AC_FUNC_GETLOADAVG' => 1,
'AH_OUTPUT' => 1,
'AC_FUNC_FSEEKO' => 1,
'AM_PROG_CC_C_O' => 1,
'AM_CONDITIONAL' => 1,
'AC_CANONICAL_SYSTEM' => 1,
'AC_FUNC_MKTIME' => 1,
'AC_CONFIG_HEADERS' => 1,
'AC_HEADER_SYS_WAIT' => 1,
'AC_FUNC_MEMCMP' => 1,
'AC_PROG_LN_S' => 1,
'm4_include' => 1,
'AC_HEADER_DIRENT' => 1,
'AC_CHECK_FUNCS' => 1
}
], 'Autom4te::Request' )
);
This diff is collapsed.
This diff is collapsed.
......@@ -37,10 +37,15 @@ if test "$USE_ICONV" = 1; then
USE_ICONV=1
ICONV_LDFLAGS=-liconv
,
AC_CHECK_LIB(c, iconv_open,
AC_CHECK_LIB(iconv, libiconv_open,
USE_ICONV=1
ICONV_LDFLAGS=-liconv
,
USE_ICONV=0
AC_CHECK_LIB(c, iconv_open,
USE_ICONV=1
,
USE_ICONV=0
)
)
)
fi
......@@ -83,21 +88,40 @@ AC_SUBST(PGBIN)
AC_SUBST(PGTEMPLATE)
AC_SUBST(LPATH)
PGFEINCLUDES="-I"`${PGCONFIG} --includedir`
PGFELIBS="-L"`${PGCONFIG} --libdir`" -lpq "`${PGCONFIG} --libs 2> /dev/null`
PGFELIBS="-L"`${PGCONFIG} --libdir`" -lpq " #(1)# `${PGCONFIG} --libs 2> /dev/null`
#(1)#
# We don't really want to link to more libs then required, see:
# http://postgis.refractions.net/pipermail/postgis-devel/2006-May/002124.html
PGBELIBS="-L"`${PGCONFIG} --libdir`" -lpostgres"
PGBEINCLUDES="-I"`${PGCONFIG} --includedir-server`
PGBIN=`${PGCONFIG} --bindir`
dnl
dnl MingW requires use of pwd -W to give proper Windows (not MingW) paths
dnl for in-place regression tests
dnl
case $host_os in
*mingw*)
PWDREGRESS="pwd -W"
;;
*)
PWDREGRESS="pwd"
;;
esac
AC_SUBST(PWDREGRESS)
dnl
dnl Test for GEOS
dnl
AC_SUBST(USE_GEOS)
AC_SUBST(GEOS_DIR)
AC_SUBST(GEOS_LDFLAGS)
AC_SUBST(USE_GEOS_CAPI)
USE_GEOS=0
USE_GEOS_CAPI=0
GEOS_DIR=
GEOS_LDFLAGS=
AC_PATH_PROG([GEOSCONFIG], [geos-config])
if test -n "$GEOSCONFIG"; then
......@@ -123,6 +147,7 @@ AC_ARG_WITH(geos,
if test $USE_GEOS -gt 0; then
GEOS_DIR=`$GEOSCONFIG --prefix`
GEOS_LDFLAGS=`$GEOSCONFIG --ldflags`
GEOS_MAJOR=`$GEOSCONFIG --version | cut -d. -f1`
if test "$GEOS_MAJOR" = "@GEOS_VERSION@"; then
GEOS_MAJOR=1
......@@ -137,6 +162,20 @@ if test $USE_GEOS -gt 0; then
fi
fi
AC_ARG_WITH(geos-libdir,
[ --with-geos-libdir=PATH path to GEOS libdir
[[taken from geos-config by default]]],
[
case "$with_geos_libdir" in
no|yes)
AC_MSG_ERROR([Invalid argument to --with-geos-libdir])
;;
*)
GEOS_LDFLAGS=-L${with_geos_libdir}
;;
esac
], with_geos_libdir=no)
dnl AC_ARG_WITH(geos-capi,
dnl [ --with-geos-capi enable use of GEOS C API ],
dnl if test "$with_geos_capi" != "no"; then
......@@ -146,8 +185,10 @@ dnl )
AC_SUBST(USE_PROJ)
AC_SUBST(PROJ_DIR)
AC_SUBST(PROJ_LIBDIR)
USE_PROJ=0
PROJ_DIR=
PROJ_LIBDIR=
AC_PATH_PROG([PROJ], [proj])
if test -n "$PROJ"; then
USE_PROJ=1
......@@ -169,8 +210,22 @@ if test $USE_PROJ -gt 0; then
if test ! -f $PROJ_DIR/include/projects.h; then
AC_MSG_ERROR([Can't find proj dir.]);
fi
PROJ_LIBDIR=${PROJ_DIR}/lib
fi
AC_ARG_WITH(proj-libdir,
[ --with-proj-libdir=PATH path to PROJ4 libdir],
[
case "$with_proj_libdir" in
no|yes)
AC_MSG_ERROR([Invalid argument to --with-proj-libdir])
;;
*)
PROJ_LIBDIR=${with_proj_libdir}
;;
esac
], with_proj_libdir=no)
AC_SUBST(USE_JTS)
AC_SUBST(JTS_INCLUDES)
AC_SUBST(JTS_LIBDIR)
......@@ -216,8 +271,9 @@ AC_PATH_PROG([DLLWRAP], [dllwrap])
AC_SUBST(DLLTOOL)
AC_PATH_PROG([DLLTOOL], [dlltool])
AC_SUBST(YACC)
AC_PATH_PROG([YACC], [yacc])
dnl AC_SUBST(YACC)
dnl AC_PATH_PROG([YACC], [yacc])
AC_PROG_YACC
if test -z "$YACC"; then
AC_MSG_ERROR(Can't find 'yacc');
fi
......@@ -275,6 +331,7 @@ dnl Search for other binaries needed to build docs
dnl
AC_PATH_PROG([XSLTPROC], [xsltproc])
AC_PATH_PROG([PDFXMLTEX], [pdfxmltex])
AC_PATH_PROG([DB2PDF], [db2pdf])
AC_PATH_PROG([JW], [jw])
AC_SUBST(XSLTPROC)
AC_SUBST(PDFXMLTEX)
......@@ -535,9 +592,10 @@ if test $USE_GEOS -gt 0; then
else
AC_MSG_RESULT([ GEOS: $GEOSCONFIG])
fi
AC_MSG_RESULT([ (ldflags: $GEOS_LDFLAGS)])
fi
if test $USE_PROJ -gt 0; then
AC_MSG_RESULT([ PROJ: dir=$PROJ_DIR])
AC_MSG_RESULT([ PROJ: prefix=$PROJ_DIR libdir=$PROJ_LIBDIR])
fi
AC_MSG_RESULT([ ICONV: $USE_ICONV $ICONV_LDFLAGS])
dnl AC_MSG_RESULT([ FLEX: path=$FLEX])
......
postgis-out.xml
postgis.fo
postgis.pdf
......@@ -3,13 +3,19 @@ include ../Version.config
LAST_RELEASE_VERSION = $(SO_MAJOR_VERSION).$(SO_MINOR_VERSION).$(SO_MICRO_VERSION)
COMMONOPTS = -f docbook -b html -e no-valid
XSLTPROC_COMMONOPTS = --param section.autolabel 1 \
JW_COMMONOPTS = -f docbook -b html -e no-valid
XSLTPROC_COMMONOPTS = \
--param section.autolabel 1 \
--param section.label.includes.component.label 1 \
--param chunk.section.depth 0
XSLTPROC_HTMLOPTS = \
--stringparam html.stylesheet style.css \
HTML_DOCBOOK_XSL=$(XSLBASE)/html/docbook.xsl
CHUNK_HTML_DOCBOOK_XSL=$(XSLBASE)/html/chunk.xsl
FO_DOCBOOK_XSL=$(XSLBASE)/fo/docbook.xsl
all: $(DOC_RULE)
......@@ -22,20 +28,20 @@ requirements_not_met:
@echo " http://postgis.refractions.net/docs"
@echo
postgis-out.xml: postgis.xml ../Version.config
postgis-out.xml: postgis.xml long_xact.xml ../Version.config
cat $< | sed "s/@@LAST_RELEASE_VERSION@@/$(LAST_RELEASE_VERSION)/g" > $@
chunked-html: postgis-out.xml
$(XSLTPROC) $(XSLTPROC_COMMONOPTS) $(XSLTPROC_HTMLOPTS) \
--output html/ \
--stringparam saxon.character.representation decimal \
$(XSLBASE)/html/chunk.xsl \
$(CHUNK_HTML_DOCBOOK_XSL) \
$<
html/postgis.html: postgis-out.xml
$(XSLTPROC) $(XSLTPROC_COMMONOPTS) \
$(XSLTPROC) $(XSLTPROC_COMMONOPTS) $(XSLTPROC_HTMLOPTS) \
--output html/postgis.html \
$(XSLBASE)/html/docbook.xsl \
$(HTML_DOCBOOK_XSL) \
$<
postgis.fo: postgis-out.xml
......@@ -46,12 +52,26 @@ postgis.fo: postgis-out.xml
html: html/postgis.html
postgis.pdf: postgis.fo
$(PDFXMLTEX) $< > /dev/null ; \
$(PDFXMLTEX) $< > /dev/null
postgis.pdf: postgis-out.xml
@if test x"$(DB2PDF)" = x; then \
echo "Error: db2pdf not found, can't build posgis.pdf"; \
echo " try installing docbook-utils package"; \
false; \
else \
$(DB2PDF) $< && mv postgis-out.pdf postgis.pdf; \
fi
# this is broken
_postgis.pdf: postgis.fo
@if test x"$(PDFXMLTEX)" = x; then \
echo "Error: pdfxmltex not found, can't build posgis.pdf"; \
false; \
else \
$(PDFXMLTEX) $<; \
fi
jw: postgis-out.xml
$(JW) $(COMMONOPTS) -o html/ postgis-out.xml
$(JW) $(JW_COMMONOPTS) -o html/ postgis-out.xml
clean:
@rm -f \
......
Overview
========
Postgis documentation is written in docbook xml.
Input file is postgis.xml. From that file we can
convert to chunked html, single file html and pdf.
Rules are:
make html # output in html/postgis.html
make chuncked-html
make postgis.pdf
====================================================
WARNING
====================================================
Informations passed this point are out-of-date.
We're moving toward only requiring 'docbook-utils'
package.
====================================================
Common requirements
===================
debian packages:
- xlstproc
Requirements to build postgis.pdf
=================================
debian packages:
- passivetex
- xmltex (for pdfxmltex)
This diff is collapsed.
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter1.Introduction</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="PostGIS Manual"><link rel="up" href="index.html" title="PostGIS Manual"><link rel="previous" href="index.html" title="PostGIS Manual"><link rel="next" href="ch02.html" title="Chapter2.Installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter1.Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a></td><th width="60%" align="center"></th><td width="20%" align="right"><a accesskey="n" href="ch02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id2454821"></a>Chapter1.Introduction</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch01.html#credits">1.1. Credits</a></span></dt><dt><span class="sect1"><a href="ch01.html#id2454630">1.2. More Information</a></span></dt></dl></div><p>PostGIS is developed by Refractions Research Inc, as a spatial
database technology research project. Refractions is a GIS and database
consulting company in Victoria, British Columbia, Canada, specializing in
data integration and custom software development. We plan on supporting
and developing PostGIS to support a range of important GIS functionality,
including full OpenGIS support, advanced topological constructs
(coverages, surfaces, networks), desktop user interface tools for viewing
and editing GIS data, and web-based access tools.</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="credits"></a>1.1.Credits</h2></div></div><div></div></div><div class="variablelist"><dl><dt><span class="term">Sandro Santilli &lt;strk@refractions.net&gt;</span></dt><dd><p>Coordinates all bug fixing and maintainance effort,
integration of new GEOS functionality, and new function
enhancements.</p></dd><dt><span class="term">Chris Hodgson &lt;chodgson@refractions.net&gt;</span></dt><dd><p>Maintains new functions and the 7.2 index bindings.</p></dd><dt><span class="term">Paul Ramsey &lt;pramsey@refractions.net&gt;</span></dt><dd><p>Keeps track of the
documentation and packaging.</p></dd><dt><span class="term">Jeff Lounsbury &lt;jeffloun@refractions.net&gt;</span></dt><dd><p>Original development of the Shape file loader/dumper.</p></dd><dt><span class="term">Dave Blasby &lt;dblasby@gmail.com&gt;</span></dt><dd><p>The original developer of PostGIS. Dave wrote the server
side objects, index bindings, and many of the server side
analytical functions.</p></dd><dt><span class="term">Other contributors</span></dt><dd><p>
In alphabetical order:
Alex Bodnaru, Alex Mayrhofer, Bruce Rindahl,
Bernhard Reiter,
Bruno Wolff III, Carl Anderson, Charlie Savage,
David Skea, David Techer,
IIDA Tetsushi, Geographic Data BC, Gerald Fenoy,
Gino Lucrezi, Klaus Foerster, Kris Jurka, Mark Cave-Ayland,
Mark Sondheim, Markus Schaber, Michael Fuhr, Nikita Shulga,
Norman Vine, Olivier Courtin, Ralph Mason, Steffen Macke.
</p></dd><dt><span class="term">Important Support Libraries</span></dt><dd><p>The <a href="http://geos.refractions.net" target="_top">GEOS</a>
geometry operations library, and the algorithmic work of
Martin Davis &lt;mbdavis@vividsolutions.com&gt; of Vivid Solutions
in making it all work.</p><p>The <a href="http://proj4.maptools.org" target="_top">Proj4</a>
cartographic projection library, and the work of Gerald Evenden
and Frank Warmerdam in creating and maintaining it.</p></dd></dl></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2454630"></a>1.2.More Information</h2></div></div><div></div></div><div class="itemizedlist"><ul type="disc"><li><p>The latest software, documentation and news items are
available at the PostGIS web site, <a href="http://postgis.refractions.net" target="_top">http://postgis.refractions.net</a>.</p></li><li><p>More information about the GEOS geometry operations library is
available at<a href="http://geos.refractions.net" target="_top">
http://geos.refractions.net</a>.</p></li><li><p>More information about the Proj4 reprojection library is
available at <a href="http://www.remotesensing.org/proj" target="_top">http://www.remotesensing.org/proj</a>.</p></li><li><p>More information about the PostgreSQL database server is
available at the PostgreSQL main site <a href="http://www.postgresql.org" target="_top">http://www.postgresql.org</a>.</p></li><li><p>More information about GiST indexing is available at the
PostgreSQL GiST development site, <a href="http://www.sai.msu.su/~megera/postgres/gist" target="_top">http://www.sai.msu.su/~megera/postgres/gist</a>.</p></li><li><p>More information about Mapserver internet map server is
available at <a href="http://mapserver.gis.umn.edu/" target="_top">http://mapserver.gis.umn.edu</a>.</p></li><li><p>The "<a href="http://www.opengis.org/docs/99-049.pdf" target="_top">Simple Features
for Specification for SQL</a>" is available at the OpenGIS
Consortium web site: <a href="http://www.opengis.org" target="_top">http://www.opengis.org</a>.</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="ch02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PostGIS Manual</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">Chapter2.Installation</td></tr></table></div></body></html>
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 5. Performance tips</title><link rel="stylesheet" href="style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="PostGIS Manual"><link rel="up" href="index.html" title="PostGIS Manual"><link rel="previous" href="ch04.html" title="Chapter 4. Using PostGIS"><link rel="next" href="ch06.html" title="Chapter 6. PostGIS Reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 5. Performance tips</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch06.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id2525866"></a>Chapter 5. Performance tips</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch05.html#id2525872">5.1. Small tables of large geometries</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch05.html#id2525878">5.1.1. Problem description</a></span></dt><dt><span class="sect2"><a href="ch05.html#id2525930">5.1.2. Workarounds</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch05.html#id2525990">5.2. CLUSTERing on geometry indices</a></span></dt><dt><span class="sect1"><a href="ch05.html#id2526046">5.3. Avoiding dimension conversion</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2525872"></a>5.1. Small tables of large geometries</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2525878"></a>5.1.1. Problem description</h3></div></div><div></div></div><p>
Current PostgreSQL versions (including 8.0) suffer from a query
optimizer weakness regarding TOAST tables. TOAST tables are a kind of
"extension room" used to store large (in the sense of data size) values
that do not fit into normal data pages (like long texts, images or
complex geometries with lots of vertices), see
http://www.postgresql.org/docs/8.0/static/storage-toast.html for more
information).
</p><p>
The problem appears if you happen to have a table with rather large
geometries, but not too much rows of them (like a table containing the
boundaries of all european countries in high resolution). Then the table
itsself is small, but it uses lots of TOAST space. In our example case,
the table itsself had about 80 rows and used only 3 data pages, but the
TOAST table used 8225 pages.
</p><p>
Now issue a query where you use the geometry operator &amp;&amp; to search for a
bounding box that matches only very few of those rows. Now the query
optimizer sees that the table has only 3 pages and 80 rows. He estimates
that a sequential scan on such a small table is much faster than using
an index. And so he decides to ignore the GIST index. Usually, this
estimation is correct. But in our case, the &amp;&amp; operator has to fetch
every geometry from disk to compare the bounding boxes, thus reading all
TOAST pages, too.
</p><p>
To see whether your suffer from this bug, use the "EXPLAIN ANALYZE"
postgresql command. For more information and the technical details, you
can read the thread on the postgres performance mailing list:
http://archives.postgresql.org/pgsql-performance/2005-02/msg00030.php
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2525930"></a>5.1.2. Workarounds</h3></div></div><div></div></div><p>
The PostgreSQL people are trying to solve this issue by making the query
estimation TOAST-aware. For now, here are two workarounds:
</p><p>
The first workaround is to force the query planner to use the index.
Send "SET enable_seqscan TO off;" to the server before issuing the
query. This basically forces the query planner to avoid sequential scans
whenever possible. So it uses the GIST index as usual. But this flag has
to be set on every connection, and it causes the query planner to make
misestimations in other cases, so you should "SET enable_seqscan TO on;"
after the query.
</p><p>
The second workaround is to make the sequential scan as fast as the
query planner thinks. This can be achieved by creating an additional
column that "caches" the bbox, and matching against this. In our
example, the commands are like:
</p><pre class="programlisting">
SELECT addGeometryColumn('myschema','mytable','bbox','4326','GEOMETRY','2');
UPDATE mytable set bbox = Envelope(Force_2d(the_geom));
</pre><p>
Now change your query to use the &amp;&amp; operator against bbox instead of
geom_column, like:
</p><pre class="programlisting">
SELECT geom_column FROM mytable WHERE bbox &amp;&amp; SetSrid('BOX3D(0 0,1 1)'::box3d,4326);
</pre><p>
Of yourse, if you change or add rows to mytable, you have to keep the
bbox "in sync". The most transparent way to do this would be triggers,
but you also can modify your application to keep the bbox column current
or run the UPDATE query above after every modification.
</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2525990"></a>5.2. CLUSTERing on geometry indices</h2></div></div><div></div></div><p>
For tables that are mostly read-only, and where a single index is used for the
majority of queries, PostgreSQL offers the CLUSTER command. This command
physically reorders all the data rows in the same order as the index criteria,
yielding two performance advantages: First, for index range scans, the number of
seeks on the data table is drastically reduced. Second, if your working set
concentrates to some small intervals on the indices, you have a more efficient
caching because the data rows are spread along fewer data pages. (Feel invited
to read the CLUSTER command documentation from the PostgreSQL manual at this
point.)
</p><p>
However, currently PostgreSQL does not allow clustering on PostGIS GIST indices
because GIST indices simply ignores NULL values, you get an error message like:
</p><pre class="programlisting">
lwgeom=# CLUSTER my_geom_index ON my_table;
ERROR: cannot cluster when index access method does not handle null values