[postgis-tickets] [SCM] PostGIS branch master updated. 97ef9ac9d523b4b96328f78f5d9d51189f9476a4
git at osgeo.org
git at osgeo.org
Thu Jan 16 09:50:29 PST 2020
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 97ef9ac9d523b4b96328f78f5d9d51189f9476a4 (commit)
from 3b40c5343e0759c82aa37911597ba675ff3fd95b (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 97ef9ac9d523b4b96328f78f5d9d51189f9476a4
Author: Sandro Santilli <strk at kbt.io>
Date: Thu Jan 16 18:50:02 2020 +0100
Reorganize all "usage" docs under a single chapter
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 1794b63..39ac9b4 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -119,6 +119,7 @@ XML_SOURCES = \
faq.xml \
installation.xml \
administration.xml \
+ usage.xml \
introduction.xml \
performance_tips.xml \
postgis.xml \
diff --git a/doc/administration.xml b/doc/administration.xml
index 856851c..eb7c081 100644
--- a/doc/administration.xml
+++ b/doc/administration.xml
@@ -2,6 +2,8 @@
<chapter id="postgis_administration">
<title>PostGIS Administration</title>
+ &database_tuning;
+
<sect1 id="raster_configuration">
<title>Configuring raster support</title>
diff --git a/doc/database_tuning.xml b/doc/database_tuning.xml
new file mode 100644
index 0000000..9428b5d
--- /dev/null
+++ b/doc/database_tuning.xml
@@ -0,0 +1,177 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<sect1 id="database_tuning_configuration">
+ <title>Tuning your configuration for performance</title>
+
+ <para>Tuning for PostGIS is much like tuning for any PostgreSQL workload. The only additional note to keep in mind is that
+ geometries and rasters are heavy so memory related optimizations generally have more of an impact on PostGIS than other types of PostgreSQL queries.</para>
+
+ <para>For general details about optimizing PostgreSQL, refer to <ulink url="https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server">Tuning your PostgreSQL Server</ulink>.</para>
+
+ <para>For PostgreSQL 9.4+ all these can be set at the server level without touching postgresql.conf or postgresql.auto.conf
+ by using the <code>ALTER SYSTEM..</code> command.</para>
+ <programlisting>ALTER SYSTEM SET work_mem = '256MB';
+-- this will force, non-startup configs to take effect for new connections
+SELECT pg_reload_conf();
+-- show current setting value
+-- use SHOW ALL to see all settings
+SHOW work_mem;</programlisting>
+
+<para>In addition to these settings, PostGIS also has some custom settings which you can find listed in <xref linkend="PostGIS_GUC" />.</para>
+
+ <sect2>
+ <title>Startup</title>
+
+ <para>
+ These settings are configured in postgresql.conf:
+ </para>
+
+ <para>
+ <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-query.html#GUC-CONSTRAINT-EXCLUSION">constraint_exclusion</ulink>
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Default: partition
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ This is generally used for table partitioning. The default for this is set to "partition" which is ideal for PostgreSQL 8.4 and above since
+ it will force the planner to only analyze tables for constraint consideration if they are in an inherited hierarchy
+ and not pay the planner penalty otherwise.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</ulink>
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Default: ~128MB in PostgreSQL 9.6
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set to about 25% to 40% of available RAM. On windows you may not be able to set as high.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+
+ <para>
+ <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</ulink>
+ This setting is only available for PostgreSQL 9.4+. For PostgreSQL 9.6+ this setting has additional importance in that it controls the
+ max number of processes you can have for parallel queries.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Default: 8
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Sets the maximum number of background processes that
+ the system can support. This parameter can only be set at
+ server start.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Runtime</title>
+
+ <para>
+ <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-WORK-MEM">work_mem</ulink> (the memory used for sort operations and complex queries)
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Default: 1-4MB
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjust up for large dbs, complex queries, lots of RAM
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Adjust down for many concurrent users or low RAM.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you have lots of RAM and few developers:
+ <programlisting>SET work_mem TO '256MB';</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</ulink> (used for VACUUM, CREATE INDEX, etc.)
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Default: 16-64MB
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Generally too low - ties up I/O, locks objects while swapping memory
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Recommend 32MB to 1GB on production servers w/lots of RAM, but depends
+ on the # of concurrent users. If you have lots of RAM and few developers:
+ <programlisting>SET maintenance_work_mem TO '1GB';</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</ulink>
+ </para>
+ <para>
+ This setting is only available for PostgreSQL 9.6+ and will only affect PostGIS 2.3+, since only PostGIS 2.3+ supports parallel queries.
+ If set to higher than 0, then some queries such as those involving relation functions like <code>ST_Intersects</code> can use multiple processes and can run
+ more than twice as fast when doing so. If you have a lot of processors to spare, you should change the value of this to as many processors as you have.
+ Also make sure to bump up <code>max_worker_processes</code> to at least as high as this number.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Default: 0
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Sets the maximum number of workers that can be started
+ by a single <varname>Gather</varname> node.
+ Parallel workers are taken from the pool of processes
+ established by <varname>max_worker_processes</varname>.
+ Note that the requested number of workers may not
+ actually be available at run time. If this occurs, the
+ plan will run with fewer workers than expected, which may
+ be inefficient. Setting this value to 0, which is the
+ default, disables parallel query execution.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </sect2>
+
+</sect1>
+
diff --git a/doc/extras.xml b/doc/extras.xml
index f54a3d5..3104fc9 100644
--- a/doc/extras.xml
+++ b/doc/extras.xml
@@ -1,9 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="Extras">
+<sect1 id="Extras">
<title>PostGIS Extras</title>
- <para>This chapter documents features found in the extras folder of the PostGIS source tarballs and source repository. These
+ <para>This sect1 documents features found in the extras folder of the PostGIS source tarballs and source repository. These
are not always packaged with PostGIS binary releases, but are usually plpgsql based or standard shell scripts that can be run as is.</para>
&extras_tigergeocoder;
-</chapter>
+</sect1>
diff --git a/doc/extras_address_standardizer.xml b/doc/extras_address_standardizer.xml
index b144a97..8ca5985 100644
--- a/doc/extras_address_standardizer.xml
+++ b/doc/extras_address_standardizer.xml
@@ -1,12 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="Address_Standardizer">
+<sect1 id="Address_Standardizer">
<title>Address Standardizer</title>
<para>This is a fork of the <ulink url="http://www.pagcgeo.org/docs/html/pagc-11.html">PAGC standardizer</ulink> (original code for this portion was <ulink url="http://sourceforge.net/p/pagc/code/360/tree/branches/sew-refactor/postgresql">PAGC PostgreSQL Address Standardizer</ulink>). </para>
<para>The address standardizer is a single line address parser that takes an input address and normalizes it based on a set of rules stored in a table and helper lex and gaz tables.</para>
<para>The code is built into a single postgresql extension library called <code>address_standardizer</code> which can be installed with <code>CREATE EXTENSION address_standardizer;</code>. In addition to the address_standardizer extension, a sample data extension called <code>address_standardizer_data_us</code> extensions is built, which contains gaz, lex, and rules tables for US data. This extensions can be installed via: <code>CREATE EXTENSION address_standardizer_data_us;</code></para>
<para>The code for this extension can be found in the PostGIS <filename>extensions/address_standardizer</filename> and is currently self-contained.</para>
<para>For installation instructions refer to: <xref linkend="installing_pagc_address_standardizer" />.</para>
- <sect1 id="Address_Standardizer_Basics"><title>How the Parser Works</title>
+ <sect2 id="Address_Standardizer_Basics"><title>How the Parser Works</title>
<para>The parser works from right to left looking first at the macro elements
for postcode, state/province, city, and then looks micro elements to determine
if we are dealing with a house number street or intersection or landmark.
@@ -30,15 +30,15 @@ These regexs are currently in the parseaddress-api.c but could get moved
into includes in the future for easier maintenance.</para></listitem>
</varlistentry>
</variablelist>
- </sect1>
- <sect1 id="Address_Standardizer_Types">
- <sect1info>
+ </sect2>
+ <sect2 id="Address_Standardizer_Types">
+ <sect2info>
<abstract>
<para>This section lists the PostgreSQL data types installed by Address Standardizer extension. Note we describe the casting behavior of these which is very
important especially when designing your own functions.
</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Address Standardizer Types</title>
<refentry id="stdaddr">
<refnamediv>
@@ -133,16 +133,16 @@ into includes in the future for easier maintenance.</para></listitem>
</variablelist>
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Address_Standardizer_Tables">
- <sect1info>
+ <sect2 id="Address_Standardizer_Tables">
+ <sect2info>
<abstract>
<para>This section lists the PostgreSQL table formats used by the address_standardizer for normalizing addresses. Note that these tables do not need to be named the same as what is referenced here. You can have different lex, gaz, rules tables for each country for example or for your custom geocoder. The names of these tables get passed into the address standardizer functions.
</para>
<para>The packaged extension <varname>address_standardizer_data_us</varname> contains data for standardizing US addresses.</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Address Standardizer Tables</title>
<refentry id="rulestab">
<refnamediv>
@@ -562,9 +562,9 @@ into includes in the future for easier maintenance.</para></listitem>
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Address_Standardizer_Functions"><title>Address Standardizer Functions</title>
+ <sect2 id="Address_Standardizer_Functions"><title>Address Standardizer Functions</title>
<refentry id="parse_address">
<refnamediv>
<refname>parse_address</refname>
@@ -757,5 +757,5 @@ FROM (SELECT addid, parse_address(address) As a
</refsection>
</refentry>
- </sect1>
-</chapter>
+ </sect2>
+</sect1>
diff --git a/doc/extras_tigergeocoder.xml b/doc/extras_tigergeocoder.xml
index e117e0f..d4a2a7f 100644
--- a/doc/extras_tigergeocoder.xml
+++ b/doc/extras_tigergeocoder.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
- <sect1 id="Tiger_Geocoder">
- <sect1info>
+ <sect2 id="Tiger_Geocoder">
+ <sect2info>
<abstract>
<para>A plpgsql based geocoder written to work with the <ulink url="http://www.census.gov/geo/www/tiger/">TIGER (Topologically Integrated Geographic Encoding and Referencing system ) / Line and Master Address database export</ulink> released by the US Census Bureau. </para>
<para>There are four components to the geocoder: the data loader functions, the address normalizer, the address geocoder, and the reverse geocoder. </para>
@@ -42,7 +42,7 @@ you can upgrade the scripts using the accompanying upgrade_geocoder.bat
<note><para>The <varname>tiger</varname> schema must be added to the database search path for the functions to work properly.</para></note>
</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Tiger Geocoder</title>
<para>There are a couple other open source geocoders for PostGIS, that unlike tiger geocoder have the advantage of multi-country geocoding support</para>
@@ -1451,4 +1451,4 @@ true</programlisting>
<para><xref linkend="Get_Geocode_Setting" /></para>
</refsection>
</refentry>
- </sect1>
+ </sect2>
diff --git a/doc/extras_topology.xml b/doc/extras_topology.xml
index db2013b..8a3fe0a 100644
--- a/doc/extras_topology.xml
+++ b/doc/extras_topology.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="Topology">
+<sect1 id="Topology">
<title>Topology</title>
<para>The PostGIS Topology types and functions are used to manage topological objects such as faces, edges and nodes. </para>
<para>Sandro Santilli's presentation at PostGIS Day Paris 2011 conference gives a good synopsis of PostGIS Topology and where it is headed <ulink url="http://strk.kbt.io/projects/postgis/Paris2011_TopologyWithPostGIS_2_0.pdf">Topology with PostGIS 2.0 slide deck</ulink>.</para>
@@ -12,14 +12,14 @@
<para>Functions that are defined in SQL/MM standard are prefixed with ST_ and functions specific to PostGIS are not prefixed.</para>
<para>Topology support is build by default starting with PostGIS 2.0, and can be disabled specifying --without-topology configure option at build time as described in <xref linkend="postgis_installation"/></para>
- <sect1 id="Topology_Types">
- <sect1info>
+ <sect2 id="Topology_Types">
+ <sect2info>
<abstract>
<para>This section lists the PostgreSQL data types installed by PostGIS Topology. Note we describe the casting behavior of these which is very
important especially when designing your own functions.
</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Topology Types</title>
<refentry id="getfaceedges_returntype">
@@ -118,16 +118,16 @@
<para><xref linkend="ValidateTopology"/></para>
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Topology_Domains">
- <sect1info>
+ <sect2 id="Topology_Domains">
+ <sect2info>
<abstract>
<para>This section lists the PostgreSQL domains installed by PostGIS Topology. Domains can be used like object types as return objects of functions or table columns. The distinction between
a domain and a type is that a domain is an existing type with a check constraint bound to it.
</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Topology Domains</title>
<refentry id="topoelement">
@@ -236,14 +236,14 @@ ERROR: value for domain topology.topoelementarray violates check constraint "di
</para>
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Topology_ManagementFunctions">
- <sect1info>
+ <sect2 id="Topology_ManagementFunctions">
+ <sect2info>
<abstract>
<para>This section lists the Topology functions for building new Topology schemas, validating topologies, and managing TopoGeometry Columns</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Topology and TopoGeometry Management</title>
<refentry id="AddTopoGeometryColumn">
<refnamediv>
@@ -641,14 +641,14 @@ face without edges | 0 |
<para><xref linkend="validatetopology_returntype"/>, <xref linkend="Topology_Load_Tiger" /></para>
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Topology_Constructors">
- <sect1info>
+ <sect2 id="Topology_Constructors">
+ <sect2info>
<abstract>
<para>This section covers the topology functions for creating new topologies.</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Topology Constructors</title>
<refentry id="CreateTopology">
@@ -1021,14 +1021,14 @@ Existing edges and faces may be split by the boundary of the new polygon.
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Topology_Editing">
- <sect1info>
+ <sect2 id="Topology_Editing">
+ <sect2info>
<abstract>
<para>This section covers topology functions for adding, moving, deleting, and splitting edges, faces, and nodes. All of these functions are defined by ISO SQL/MM.</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Topology Editors</title>
<refentry id="ST_AddIsoNode">
@@ -1831,10 +1831,10 @@ SELECT topology.ST_RemoveIsoNode('ma_topo', 7 ) As result;
<para><xref linkend="ST_AddIsoNode"/></para>
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Topology_Accessors">
+ <sect2 id="Topology_Accessors">
<title>Topology Accessors</title>
<refentry id="GetEdgeByPoint">
<refnamediv>
@@ -2390,15 +2390,15 @@ and is thus usable to build edge ring linking.
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="Topology_Processing">
- <sect1info>
+ <sect2 id="Topology_Processing">
+ <sect2info>
<abstract>
<para>This section covers the functions for processing topologies in non-standard ways.</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Topology Processing</title>
<refentry id="TopologyPolygonize">
<refnamediv>
@@ -2707,14 +2707,14 @@ faceid
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="TopoGeometry_Constructors">
- <sect1info>
+ <sect2 id="TopoGeometry_Constructors">
+ <sect2info>
<abstract>
<para>This section covers the topology functions for creating new topogeometries.</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>TopoGeometry Constructors</title>
<refentry id="CreateTopoGeom">
<refnamediv>
@@ -2996,14 +2996,14 @@ SELECT ST_GetFaceGeometry('topo_boston_test', f.face_id)
<para><xref linkend="topoelement"/>, <xref linkend="topoelementarray"/></para>
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="TopoGeometry_Editors">
- <sect1info>
+ <sect2 id="TopoGeometry_Editors">
+ <sect2info>
<abstract>
<para>This section covers the topology functions for editing existing topogeometries.</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>TopoGeometry Editors</title>
<refentry id="clearTopoGeom">
@@ -3157,9 +3157,9 @@ Refer to <xref linkend="toTopoGeom" />.
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="TopoGeom_Accessors">
+ <sect2 id="TopoGeom_Accessors">
<title>TopoGeometry Accessors</title>
<refentry id="GetTopoGeomElementArray">
@@ -3263,10 +3263,10 @@ Refer to <xref linkend="toTopoGeom" />.
</refsection>
</refentry>
- </sect1>
+ </sect2>
- <sect1 id="TopoGeometry_Outputs">
+ <sect2 id="TopoGeometry_Outputs">
<title>TopoGeometry Outputs</title>
<refentry id="AsGML">
<refnamediv>
@@ -3549,14 +3549,14 @@ UNION ALL SELECT ']}'::text as t;
</programlisting>
</refsection>
</refentry>
-</sect1>
+</sect2>
-<sect1 id="Topology_Relationships">
- <sect1info>
+<sect2 id="Topology_Relationships">
+ <sect2info>
<abstract>
<para>This section lists the Topology functions used to check relationships between topogeometries and topology primitives</para>
</abstract>
- </sect1info>
+ </sect2info>
<title>Topology Spatial Relationships</title>
<refentry id="TG_Equals">
<refnamediv>
@@ -3659,5 +3659,5 @@ two topogeometries intersect.
<para><xref linkend="ST_Intersects" /></para>
</refsection>
</refentry>
+</sect2>
</sect1>
-</chapter>
diff --git a/doc/performance_tips.xml b/doc/performance_tips.xml
index 31643ac..e567f5a 100644
--- a/doc/performance_tips.xml
+++ b/doc/performance_tips.xml
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="performance_tips">
+<sect1 id="performance_tips">
<title>Performance tips</title>
- <sect1 id="small_tables_large_objects">
+ <sect2 id="small_tables_large_objects">
<title>Small tables of large geometries</title>
- <sect2>
+ <sect3>
<title>Problem description</title>
<para>Current PostgreSQL versions (including 9.6) suffer from a query
@@ -39,9 +39,9 @@
<ulink url="http://archives.postgresql.org/pgsql-performance/2005-02/msg00030.php">http://archives.postgresql.org/pgsql-performance/2005-02/msg00030.php</ulink></para>
<para>and newer thread on PostGIS <ulink url="https://lists.osgeo.org/pipermail/postgis-devel/2017-June/026209.html">https://lists.osgeo.org/pipermail/postgis-devel/2017-June/026209.html</ulink></para>
- </sect2>
+ </sect3>
- <sect2>
+ <sect3>
<title>Workarounds</title>
<para>The PostgreSQL people are trying to solve this issue by making the
@@ -75,10 +75,10 @@ WHERE bbox && ST_SetSRID('BOX3D(0 0,1 1)'::box3d,4326);</programlisting>
triggers, but you also can modify your application to keep the bbox
column current or run the UPDATE query above after every
modification.</para>
- </sect2>
- </sect1>
+ </sect3>
+ </sect2>
- <sect1 id="database_clustering">
+ <sect2 id="database_clustering">
<title>CLUSTERing on geometry indices</title>
<para>For tables that are mostly read-only, and where a single index is
@@ -109,9 +109,9 @@ ALTER TABLE</programlisting>
your geometry column. Additionally, you must use the above method to add
the constraint, using a CHECK constraint like "ALTER TABLE blubb ADD CHECK
(geometry is not null);" will not work.</para>
- </sect1>
+ </sect2>
- <sect1 id="avoiding_dimension_conversion">
+ <sect2 id="avoiding_dimension_conversion">
<title>Avoiding dimension conversion</title>
<para>Sometimes, you happen to have 3D or 4D data in your table, but
@@ -139,180 +139,6 @@ VACUUM FULL ANALYZE mytable;</programlisting>
dimension(the_geom)>2" skips re-writing of geometries that already are
in 2D.</para>
- </sect1>
+ </sect2>
- <sect1 id="database_tuning_configuration">
- <title>Tuning your configuration</title>
-
- <para>Tuning for PostGIS is much like tuning for any PostgreSQL workload. The only additional note to keep in mind is that
- geometries and rasters are heavy so memory related optimizations generally have more of an impact on PostGIS than other types of PostgreSQL queries.</para>
-
- <para>For general details about optimizing PostgreSQL, refer to <ulink url="https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server">Tuning your PostgreSQL Server</ulink>.</para>
-
- <para>For PostgreSQL 9.4+ all these can be set at the server level without touching postgresql.conf or postgresql.auto.conf
- by using the <code>ALTER SYSTEM..</code> command.</para>
- <programlisting>ALTER SYSTEM SET work_mem = '256MB';
--- this will force, non-startup configs to take effect for new connections
-SELECT pg_reload_conf();
--- show current setting value
--- use SHOW ALL to see all settings
-SHOW work_mem;</programlisting>
-
- <para>In addition to these settings, PostGIS also has some custom settings which you can find listed in <xref linkend="PostGIS_GUC" />.</para>
-
- <sect2>
- <title>Startup</title>
-
- <para>
- These settings are configured in postgresql.conf:
- </para>
-
- <para>
- <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-query.html#GUC-CONSTRAINT-EXCLUSION">constraint_exclusion</ulink>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Default: partition
- </para>
- </listitem>
- <listitem>
- <para>
- This is generally used for table partitioning. The default for this is set to "partition" which is ideal for PostgreSQL 8.4 and above since
- it will force the planner to only analyze tables for constraint consideration if they are in an inherited hierarchy
- and not pay the planner penalty otherwise.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-SHARED-BUFFERS">shared_buffers</ulink>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Default: ~128MB in PostgreSQL 9.6
- </para>
- </listitem>
- <listitem>
- <para>
- Set to about 25% to 40% of available RAM. On windows you may not be able to set as high.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</ulink>
- This setting is only available for PostgreSQL 9.4+. For PostgreSQL 9.6+ this setting has additional importance in that it controls the
- max number of processes you can have for parallel queries.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Default: 8
- </para>
- </listitem>
- <listitem>
- <para>
- Sets the maximum number of background processes that
- the system can support. This parameter can only be set at
- server start.
- </para>
- </listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Runtime</title>
-
- <para>
- <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-WORK-MEM">work_mem</ulink> (the memory used for sort operations and complex queries)
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Default: 1-4MB
- </para>
- </listitem>
- <listitem>
- <para>
- Adjust up for large dbs, complex queries, lots of RAM
- </para>
- </listitem>
- <listitem>
- <para>
- Adjust down for many concurrent users or low RAM.
- </para>
- </listitem>
- <listitem>
- <para>
- If you have lots of RAM and few developers:
- <programlisting>SET work_mem TO '256MB';</programlisting>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <ulink url="http://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-MAINTENANCE-WORK-MEM">maintenance_work_mem</ulink> (used for VACUUM, CREATE INDEX, etc.)
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Default: 16-64MB
- </para>
- </listitem>
- <listitem>
- <para>
- Generally too low - ties up I/O, locks objects while swapping memory
- </para>
- </listitem>
- <listitem>
- <para>
- Recommend 32MB to 1GB on production servers w/lots of RAM, but depends
- on the # of concurrent users. If you have lots of RAM and few developers:
- <programlisting>SET maintenance_work_mem TO '1GB';</programlisting>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <ulink url="https://www.postgresql.org/docs/current/static/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</ulink>
- </para>
- <para>
- This setting is only available for PostgreSQL 9.6+ and will only affect PostGIS 2.3+, since only PostGIS 2.3+ supports parallel queries.
- If set to higher than 0, then some queries such as those involving relation functions like <code>ST_Intersects</code> can use multiple processes and can run
- more than twice as fast when doing so. If you have a lot of processors to spare, you should change the value of this to as many processors as you have.
- Also make sure to bump up <code>max_worker_processes</code> to at least as high as this number.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Default: 0
- </para>
- </listitem>
- <listitem>
- <para>
- Sets the maximum number of workers that can be started
- by a single <varname>Gather</varname> node.
- Parallel workers are taken from the pool of processes
- established by <varname>max_worker_processes</varname>.
- Note that the requested number of workers may not
- actually be available at run time. If this occurs, the
- plan will run with fewer workers than expected, which may
- be inefficient. Setting this value to 0, which is the
- default, disables parallel query execution.
- </para>
- </listitem>
- </itemizedlist>
-
- </sect2>
-
- </sect1>
-</chapter>
+</sect1>
diff --git a/doc/postgis.xml b/doc/postgis.xml
index b9577d2..273e024 100644
--- a/doc/postgis.xml
+++ b/doc/postgis.xml
@@ -18,11 +18,13 @@
<!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY installation SYSTEM "installation.xml">
<!ENTITY administration SYSTEM "administration.xml">
-<!ENTITY faq SYSTEM "faq.xml">
+<!ENTITY usage SYSTEM "usage.xml">
<!ENTITY using_postgis_dataman SYSTEM "using_postgis_dataman.xml">
<!ENTITY using_raster_dataman SYSTEM "using_raster_dataman.xml">
<!ENTITY using_postgis_app SYSTEM "using_postgis_app.xml">
<!ENTITY performance_tips SYSTEM "performance_tips.xml">
+<!ENTITY database_tuning SYSTEM "database_tuning.xml">
+<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY reference SYSTEM "reference.xml">
<!ENTITY postgis_aggs_mm SYSTEM "postgis_aggs_mm.xml">
<!ENTITY reporting SYSTEM "reporting.xml">
@@ -177,17 +179,11 @@
&introduction;
&installation;
&administration;
- &faq;
- &using_postgis_dataman;
- &using_raster_dataman;
- &using_postgis_app;
- &performance_tips;
+ &usage;
&reference;
&reference_raster;
+ &faq;
&faq_raster;
- &extras_topology;
- &extras_address_standardizer;
- &extras;
&postgis_aggs_mm;
&reporting;
&release_notes;
diff --git a/doc/usage.xml b/doc/usage.xml
new file mode 100644
index 0000000..1df9965
--- /dev/null
+++ b/doc/usage.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="postgis_usage">
+ <title>PostGIS Usage</title>
+
+ &using_postgis_dataman;
+ &using_postgis_app;
+ &using_raster_dataman;
+ &extras_topology;
+ &extras_address_standardizer;
+ &extras;
+ &performance_tips;
+
+ <!-- &extras_historytable; why not here/disabled ? -->
+ <!-- &extras_tigergeocoder; is in extras.xml -->
+
+</chapter>
diff --git a/doc/using_postgis_app.xml b/doc/using_postgis_app.xml
index 889cb0a..ee38056 100644
--- a/doc/using_postgis_app.xml
+++ b/doc/using_postgis_app.xml
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter>
+<sect1>
<title id="using_postgis_applications">Using PostGIS Geometry: Building Applications</title>
- <sect1 id="Using_MapServer">
+ <sect2 id="Using_MapServer">
<title>Using MapServer</title>
<para>The Minnesota MapServer is an internet web-mapping server which
@@ -19,7 +19,7 @@
</listitem>
</itemizedlist>
- <sect2>
+ <sect3>
<title>Basic Usage</title>
<para>To use PostGIS with MapServer, you will need to know about how to
@@ -168,9 +168,9 @@ END</programlisting>
identifiers. Using the table primary key is the best practice.</para>
</listitem>
</orderedlist>
- </sect2>
+ </sect3>
- <sect2>
+ <sect3>
<title>Frequently Asked Questions</title>
<qandaset>
@@ -266,9 +266,9 @@ postgis# VACUUM ANALYZE;</programlisting>
</qandaset>
- </sect2>
+ </sect3>
- <sect2>
+ <sect3>
<title>Advanced Usage</title>
<para>The <varname>USING</varname> pseudo-SQL clause is used to add some
@@ -330,9 +330,9 @@ postgis# VACUUM ANALYZE;</programlisting>
</varlistentry>
</variablelist>
- </sect2>
+ </sect3>
- <sect2>
+ <sect3>
<title>Examples</title>
<para>Lets start with a simple example and work our way up. Consider the
@@ -435,10 +435,10 @@ END</programlisting>
<para>This annotation layer adds green labels to all the roads when the
scale gets down to 1:20000 or less. It also demonstrates how to use an
SQL join in a <varname>DATA</varname> definition.</para>
- </sect2>
- </sect1>
+ </sect3>
+ </sect2>
- <sect1>
+ <sect2>
<title>Java Clients (JDBC)</title>
<para>Java clients can access PostGIS "geometry" objects in the PostgreSQL
@@ -517,23 +517,23 @@ if( geom.getType() == Geometry.POLYGON ) {
<para>The JavaDoc for the extension objects provides a reference for the
various data accessor functions in the geometric objects.</para>
- </sect1>
+ </sect2>
- <sect1>
+ <sect2>
<title>C Clients (libpq)</title>
<para>...</para>
- <sect2>
+ <sect3>
<title>Text Cursors</title>
<para>...</para>
- </sect2>
+ </sect3>
- <sect2>
+ <sect3>
<title>Binary Cursors</title>
<para>...</para>
- </sect2>
- </sect1>
-</chapter>
+ </sect3>
+ </sect2>
+</sect1>
diff --git a/doc/using_postgis_dataman.xml b/doc/using_postgis_dataman.xml
index 3e56367..07ad721 100644
--- a/doc/using_postgis_dataman.xml
+++ b/doc/using_postgis_dataman.xml
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="using_postgis_dbmanagement">
+<sect1 id="using_postgis_dbmanagement">
<title>Using PostGIS: Data Management and Queries</title>
- <sect1 id="RefObject">
+ <sect2 id="RefObject">
<title>GIS Objects</title>
<para>The GIS objects supported by PostGIS are a superset of the "Simple
@@ -12,7 +12,7 @@
<para>PostGIS extends the standard with support for embedded SRID information.</para>
- <sect2 id="OpenGISWKBWKT">
+ <sect3 id="OpenGISWKBWKT">
<title>OpenGIS WKB and WKT</title>
<para>The OpenGIS specification defines two standard ways of expressing
@@ -84,9 +84,9 @@ geometry = ST_GeometryFromText(text WKT, SRID);</programlisting>
<programlisting>INSERT INTO geotable ( the_geom, the_name )
VALUES ( ST_GeomFromText('POINT(-126.4 45.32)', 312), 'A Place');</programlisting>
- </sect2>
+ </sect3>
- <sect2 id="EWKB_EWKT">
+ <sect3 id="EWKB_EWKT">
<title>PostGIS EWKB, EWKT and Canonical Forms</title>
<para>First OpenGIS specifications (prior to 1.2.0) only support 2D geometries,
@@ -234,8 +234,8 @@ geometry
----------------------------------------------------
01010000200400000000000000000000000000000000000000
(1 row)</programlisting>
- </sect2>
- <sect2 id="SQL_MM_Part3">
+ </sect3>
+ <sect3 id="SQL_MM_Part3">
<title>SQL-MM Part 3</title>
<para>The SQL Multimedia Applications Spatial specification extends the
@@ -306,9 +306,9 @@ geometry
<para>All floating point comparisons within the SQL-MM implementation
are performed to a specified tolerance, currently 1E-8.</para>
</note>
- </sect2>
- </sect1>
- <sect1 id="PostGIS_Geography">
+ </sect3>
+ </sect2>
+ <sect2 id="PostGIS_Geography">
<title>PostGIS Geography Type</title>
<para>The geography type provides native support for spatial features represented on "geographic" coordinates (sometimes called "geodetic" coordinates, or "lat/lon", or "lon/lat"). Geographic coordinates are spherical coordinates expressed in angular units (degrees). </para>
@@ -331,7 +331,7 @@ geometry
<para>The geography type uses the PostgreSQL typmod definition format so that a table with a geography field
can be added in a single step. All the standard OGC formats except for curves are supported.</para>
- <sect2 id="Geography_Basics">
+ <sect3 id="Geography_Basics">
<title>Geography Basics</title>
<para>The geography type does not support curves, TINS, or POLYHEDRALSURFACEs, but other geometry types are supported. Standard geometry type data will autocast to geography if it is of SRID 4326. You can also use the EWKT and EWKB
conventions to insert data.</para>
@@ -448,8 +448,8 @@ LINE 1: SELECT 'SRID=26910;POINT(-123 34)'::geography;</programlisting></para>
<para> <ulink url="http://gc.kls2.com/cgi-bin/gc?PATH=SEA-LHR">Great Circle mapper</ulink>
The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik and the straight line path from Seattle to London plotted on a flat map of the world. The nominal units of the result might be called "degrees", but the result doesn't correspond to any true angular difference between the points, so even calling them "degrees" is inaccurate.</para>
- </sect2>
- <sect2 id="PostGIS_GeographyVSGeometry">
+ </sect3>
+ <sect3 id="PostGIS_GeographyVSGeometry">
<title>When to use Geography Data type over Geometry data type</title>
<para>The geography type allows you to store data in longitude/latitude coordinates, but at a cost: there are fewer functions defined on GEOGRAPHY than there are on GEOMETRY; those functions that are defined take more CPU time to execute.</para>
<para>The type you choose should be conditioned on the expected working area of the application you are building. Will your data span the globe or a large continental area, or is it local to a state, county or municipality? </para>
@@ -464,8 +464,8 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
what is supported for Geography vs. Geometry. For a brief listing and description of Geography functions, refer to
<xref linkend="PostGIS_GeographyFunctions" />
</para>
- </sect2>
- <sect2 id="PostGIS_Geography_AdvancedFAQ">
+ </sect3>
+ <sect3 id="PostGIS_Geography_AdvancedFAQ">
<title>Geography Advanced FAQ</title>
<qandaset>
<qandaentry>
@@ -520,10 +520,10 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
</answer>
</qandaentry>
</qandaset>
- </sect2>
-</sect1>
+ </sect3>
+</sect2>
- <sect1>
+ <sect2>
<title>Using OpenGIS Standards</title>
<para>The OpenGIS "Simple Features Specification for SQL" defines standard
@@ -538,7 +538,7 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
<varname>SPATIAL_REF_SYS</varname> table holds the numeric IDs and textual
descriptions of coordinate systems used in the spatial database.</para>
- <sect2 id="spatial_ref_sys">
+ <sect3 id="spatial_ref_sys">
<title>The SPATIAL_REF_SYS Table and Spatial Reference Systems</title>
<para>The spatial_ref_sys table is a PostGIS included and OGC compliant database table that lists over 3000
@@ -662,9 +662,9 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
</listitem>
</varlistentry>
</variablelist>
- </sect2>
+ </sect3>
- <sect2 id="geometry_columns">
+ <sect3 id="geometry_columns">
<title>The GEOMETRY_COLUMNS VIEW</title>
<para><varname>GEOMETRY_COLUMNS</varname> is a view reading from database system catalogs.
@@ -744,9 +744,9 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
</listitem>
</varlistentry>
</variablelist>
- </sect2>
+ </sect3>
- <sect2 id="Create_Spatial_Table">
+ <sect3 id="Create_Spatial_Table">
<title>Creating a Spatial Table</title>
<para>Creating a table with spatial data, can be done in one step. As shown in the following example
@@ -755,9 +755,9 @@ The GEOMETRY type calculates a meaningless cartesian distance between Reykjavik
<para>We can add additional columns using standard ALTER TABLE command as we do in this next example where we add a 3-D linestring.</para>
<programlisting>ALTER TABLE roads ADD COLUMN geom2 geometry(LINESTRINGZ,4326);</programlisting>
- </sect2>
+ </sect3>
- <sect2 id="Manual_Register_Spatial_Column">
+ <sect3 id="Manual_Register_Spatial_Column">
<title>Manually Registering Geometry Columns in geometry_columns</title>
<para>Two of the cases where you may need this are the case of SQL Views and bulk inserts. For bulk insert case, you can correct the registration in the geometry_columns table
@@ -872,9 +872,9 @@ SELECT f_table_name, f_geometry_column, srid, type
------------------+-------------------+------+-------
vw_pois_ny_parks | geom | 4326 | POINT
vw_pois_ny_parks | geom_2160 | 2160 | POINT</screen>
- </sect2>
+ </sect3>
- <sect2 id="OGC_Validity">
+ <sect3 id="OGC_Validity">
<title>Ensuring OpenGIS compliancy of geometries</title>
<para>PostGIS is compliant with the Open Geospatial Consortium’s (OGC)
@@ -1208,9 +1208,9 @@ gisdb=# SELECT
constraint checking geometry dimensions, so it is enough to specify 2
there.</para>
</note>
- </sect2>
+ </sect3>
- <sect2 id="DE-9IM">
+ <sect3 id="DE-9IM">
<title>Dimensionally Extended 9 Intersection Model (DE-9IM)</title>
<para>It is sometimes the case that the typical spatial predicates
@@ -1293,7 +1293,7 @@ gisdb=# SELECT
<para>So enters the Dimensionally Extended 9 Intersection Model, or
DE-9IM for short.</para>
- <sect3>
+ <sect4>
<title>Theory</title>
<para>According to the <ulink
@@ -1582,12 +1582,12 @@ AND ST_Relate(a.geom, b.geom, '102101FF2');</programlisting>
</listitem>
</itemizedlist>
- </sect3>
- </sect2>
+ </sect4>
+ </sect3>
- </sect1>
+ </sect2>
- <sect1 id="loading_geometry_data">
+ <sect2 id="loading_geometry_data">
<title>Loading GIS (Vector) Data</title>
<para>Once you have created a spatial table, you are ready to upload GIS
@@ -1595,7 +1595,7 @@ AND ST_Relate(a.geom, b.geom, '102101FF2');</programlisting>
PostGIS/PostgreSQL database: using formatted SQL statements or using the
Shape file loader/dumper.</para>
- <sect2>
+ <sect3>
<title>Loading Data Using SQL</title>
<para>If you can convert your data to a text representation, then using
@@ -1626,9 +1626,9 @@ COMMIT;</programlisting>
"psql" SQL terminal monitor:</para>
<programlisting>psql -d [database] -f roads.sql</programlisting>
- </sect2>
+ </sect3>
-<sect2 id="shp2pgsql_usage">
+<sect3 id="shp2pgsql_usage">
<title>shp2pgsql: Using the ESRI Shapefile Loader</title>
<para>
@@ -1888,10 +1888,10 @@ AVERYLONGCOLUMNNAME DBFFIELD2</programlisting>
</para>
<programlisting># shp2pgsql shaperoads.shp myschema.roadstable | psql -d roadsdb</programlisting>
-</sect2>
- </sect1>
+</sect3>
+ </sect2>
- <sect1 id="retrieving_vector-data">
+ <sect2 id="retrieving_vector-data">
<title>Retrieving GIS Data</title>
<para>Data can be extracted from the database using either SQL or the
@@ -1899,7 +1899,7 @@ AVERYLONGCOLUMNNAME DBFFIELD2</programlisting>
the operators available to do comparisons and queries on spatial
tables.</para>
- <sect2>
+ <sect3>
<title>Using SQL to Retrieve Data</title>
<para>The most straightforward means of pulling data out of the
@@ -1986,9 +1986,9 @@ WHERE
<para>Note the use of the SRID 312, to specify the projection of the envelope.</para>
- </sect2>
+ </sect3>
- <sect2>
+ <sect3>
<title>Using the Dumper</title>
<para>The <filename>pgsql2shp</filename> table dumper connects directly
@@ -2082,10 +2082,10 @@ WHERE
</listitem>
</varlistentry>
</variablelist>
- </sect2>
- </sect1>
+ </sect3>
+ </sect2>
- <sect1>
+ <sect2>
<title>Building Indexes</title>
<para>Indexes are what make using a spatial database for large data sets
@@ -2112,7 +2112,7 @@ WHERE
</listitem>
</itemizedlist>
- <sect2 id="gist_indexes">
+ <sect3 id="gist_indexes">
<title>GiST Indexes</title>
<para>GiST stands for "Generalized Search Tree" and is a generic form of
@@ -2142,9 +2142,9 @@ WHERE
<para><programlisting>VACUUM ANALYZE [table_name] [(column_name)];</programlisting></para>
- </sect2>
+ </sect3>
- <sect2 id="brin_indexes">
+ <sect3 id="brin_indexes">
<title>BRIN Indexes</title>
<para>BRIN stands for "Block Range Index" and is a generic form of
@@ -2213,9 +2213,9 @@ WHERE
"geometry" and for "geography"), and just the <varname>&&&</varname>
operator can be used for the 3D geometries. There is no support
for kNN searches at the moment.</para>
- </sect2>
+ </sect3>
- <sect2 id="spgist_indexes">
+ <sect3 id="spgist_indexes">
<title>SP-GiST Indexes</title>
<para>SP-GiST stands for "Space-Partitioned Generalized Search Tree" and is
@@ -2261,8 +2261,8 @@ WHERE
<listitem><para> &/&, ~==, @>>, and <<@, for 3-dimensional indexes.</para></listitem>
</itemizedlist>
<para>There is no support for kNN searches at the moment.</para>
- </sect2>
- <sect2>
+ </sect3>
+ <sect3>
<title>Using Indexes</title>
<para>Ordinarily, indexes invisibly speed up data access: once the index
@@ -2324,10 +2324,10 @@ WHERE
</listitem>
</itemizedlist>
- </sect2>
- </sect1>
+ </sect3>
+ </sect2>
- <sect1>
+ <sect2>
<title>Complex Queries</title>
<para>The <emphasis>raison d'etre</emphasis> of spatial database
@@ -2347,7 +2347,7 @@ and you want to map out the Mars planet for rehabitation, you can use a non-ear
make one up and insert it in the <varname>spatial_ref_sys</varname> table. Though this Mars coordinate system is a non-planar one (it's in degrees spheroidal),
you can use it with the geography type to have your length and proximity measurements in meters instead of degrees.</para>
- <sect2>
+ <sect3>
<title>Taking Advantage of Indexes</title>
<para>When constructing a query it is important to remember that only
@@ -2386,9 +2386,9 @@ WHERE ST_DWithin(the_geom, 'SRID=312;POINT(100000 200000)', 100)
Assuming that our query box is much smaller than the extents of the
entire geometry table, this will drastically reduce the number of
distance calculations that need to be done.</para>
- </sect2>
+ </sect3>
- <sect2 id="examples_spatial_sql">
+ <sect3 id="examples_spatial_sql">
<title>Examples of Spatial SQL</title>
<para>The examples in this section will make use of two tables, a table
@@ -2598,6 +2598,6 @@ gid | name | area
</answer>
</qandaentry>
</qandaset>
- </sect2>
- </sect1>
-</chapter>
+ </sect3>
+ </sect2>
+</sect1>
diff --git a/doc/using_raster_dataman.xml b/doc/using_raster_dataman.xml
index 85a5c02..fed8e01 100644
--- a/doc/using_raster_dataman.xml
+++ b/doc/using_raster_dataman.xml
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="using_raster_dataman">
+<sect1 id="using_raster_dataman">
<title>Raster Data Management, Queries, and Applications</title>
- <sect1 id="RT_Loading_Rasters">
+ <sect2 id="RT_Loading_Rasters">
<title>Loading and Creating Rasters</title>
<para>For most use cases, you will create PostGIS rasters by loading existing raster files using the packaged <varname>raster2pgsql</varname> raster loader.</para>
- <sect2 id="RT_Raster_Loader">
+ <sect3 id="RT_Raster_Loader">
<title>Using raster2pgsql to load rasters</title>
<para>
The <varname>raster2pgsql</varname> is a raster loader executable that loads GDAL supported raster formats into sql suitable for loading into a PostGIS raster table.
@@ -427,8 +427,8 @@ Available GDAL raster formats:
Arc/Info Export E00 GRID
ZMap Plus Grid
NOAA NGS Geoid Height Grids</screen>
- </sect2>
- <sect2 id="RT_Creating_Rasters">
+ </sect3>
+ <sect3 id="RT_Creating_Rasters">
<title>Creating rasters using PostGIS raster functions</title>
<para>On many occasions, you'll want to create rasters and raster tables right in the database. There are a plethora of functions to do that. The general steps to follow.</para>
<orderedlist>
@@ -448,9 +448,9 @@ Available GDAL raster formats:
<note><para>Pre-2.0 versions of PostGIS raster were based on the envelop rather than the convex hull. For the spatial indexes to work properly you'll need to drop those and replace with convex hull based index.</para></note></listitem>
<listitem><para>Apply raster constraints using <xref linkend="RT_AddRasterConstraints" /></para></listitem>
</orderedlist>
- </sect2>
- </sect1>
- <sect1 id="RT_Raster_Catalog">
+ </sect3>
+ </sect2>
+ <sect2 id="RT_Raster_Catalog">
<title>Raster Catalogs</title>
<para>There are two raster catalog views that come packaged with PostGIS. Both views utilize information embedded in the constraints of the raster tables. As a result
the catalog views are always consistent with the raster data in the tables since the constraints are enforced. </para>
@@ -462,7 +462,7 @@ Available GDAL raster formats:
<para><varname>raster_overviews</varname> this view catalogs all the raster table columns in your database that serve as overviews for a finer grained table. Tables of this type are generated when you use the <varname>-l</varname> switch during load.</para>
</listitem>
</orderedlist>
- <sect2 id="RT_Raster_Columns">
+ <sect3 id="RT_Raster_Columns">
<title>Raster Columns Catalog</title>
<para>The <varname>raster_columns</varname> is a catalog of all raster table columns in your database that are of type raster. It is a view utilizing the constraints on the tables
so the information is always consistent even if you restore one raster table from a backup of another database. The following columns exist in the <varname>raster_columns</varname> catalog.</para>
@@ -522,8 +522,8 @@ Available GDAL raster formats:
<para><varname>spatial_index</varname> A boolean that is true if raster column has a spatial index.</para>
</listitem>
</itemizedlist>
- </sect2>
- <sect2 id="RT_Raster_Overviews">
+ </sect3>
+ <sect3 id="RT_Raster_Overviews">
<title>Raster Overviews</title>
<para><varname>raster_overviews</varname> catalogs information about raster table columns used for overviews and additional information about them that is useful to know when utilizing overviews. Overview tables are cataloged in both <varname>raster_columns</varname> and <varname>raster_overviews</varname> because they are rasters in their own right but also serve an additional special purpose of being a lower resolution caricature of a higher resolution table. These are generated along-side the main raster table when you use the <varname>-l</varname> switch in raster loading or can be generated manually using <xref linkend="RT_AddOverviewConstraints" />.</para>
<para>Overview tables contain the same constraints as other raster tables as well as additional informational only constraints specific to overviews.</para>
@@ -571,13 +571,13 @@ Available GDAL raster formats:
</listitem>
</itemizedlist>
- </sect2>
- </sect1>
- <sect1 id="RT_Raster_Applications">
+ </sect3>
+ </sect2>
+ <sect2 id="RT_Raster_Applications">
<title>Building Custom Applications with PostGIS Raster</title>
<para>The fact that PostGIS raster provides you with SQL functions to render rasters in known image formats gives you a lot of optoins for rendering them.
For example you can use OpenOffice / LibreOffice for rendering as demonstrated in <ulink url="http://www.postgresonline.com/journal/archives/244-Rendering-PostGIS-Raster-graphics-with-LibreOffice-Base-Reports.html">Rendering PostGIS Raster graphics with LibreOffice Base Reports</ulink>. In addition you can use a wide variety of languages as demonstrated in this section.</para>
- <sect2 id="RT_PHP_Output">
+ <sect3 id="RT_PHP_Output">
<title>PHP Example Outputting using ST_AsPNG in concert with other raster functions</title>
<para>In this section, we'll demonstrate how to use the PHP PostgreSQL driver and the <xref linkend="RT_ST_AsGDALRaster" /> family of functions to
output band 1,2,3 of a raster to a PHP request stream that can then be embedded in an img src html tag.</para>
@@ -611,8 +611,8 @@ pg_free_result($result);
if ($row === false) return;
echo pg_unescape_bytea($row[0]);
?>]]></programlisting>
- </sect2>
- <sect2 id="RT_Net_Output_CS">
+ </sect3>
+ <sect3 id="RT_Net_Output_CS">
<title>ASP.NET C# Example Outputting using ST_AsPNG in concert with other raster functions</title>
<para>In this section, we'll demonstrate how to use Npgsql PostgreSQL .NET driver and the <xref linkend="RT_ST_AsGDALRaster" /> family of functions to
output band 1,2,3 of a raster to a PHP request stream that can then be embedded in an img src html tag.</para>
@@ -689,8 +689,8 @@ public class TestRaster : IHttpHandler
return result;
}
}]]></programlisting>
- </sect2>
- <sect2 id="RT_Java_Console_App">
+ </sect3>
+ <sect3 id="RT_Java_Console_App">
<title>Java console app that outputs raster query as Image file</title>
<para>This is a simple java console app that takes a query that returns one image and outputs to specified file.</para>
<para>You can download the latest PostgreSQL JDBC drivers from <ulink url="http://jdbc.postgresql.org/download.html">http://jdbc.postgresql.org/download.html</ulink> </para>
@@ -760,9 +760,9 @@ public class SaveQueryImage {
}
}
}]]></programlisting>
- </sect2>
+ </sect3>
- <sect2 id="RT_PLPython">
+ <sect3 id="RT_PLPython">
<title>Use PLPython to dump out images via SQL</title>
<para>This is a plpython stored function that creates a file in the server directory for each record.
Requires you have plpython installed. Should work fine with both plpythonu and plpython3u.</para>
@@ -789,8 +789,8 @@ $$ LANGUAGE plpythonu;]]></programlisting>
C:/temp/slices4.png
C:/temp/slices5.png
</programlisting>
- </sect2>
- <sect2 id="RasterOutput_PSQL">
+ </sect3>
+ <sect3 id="RasterOutput_PSQL">
<title>Outputting Rasters with PSQL</title>
<para>Sadly PSQL doesn't have easy to use built-in functionality for outputting binaries. This is a bit of a hack that piggy backs on PostgreSQL somewhat legacy large object support. To use first launch your psql commandline connected to your database.
</para>
@@ -812,6 +812,6 @@ $$ LANGUAGE plpythonu;]]></programlisting>
-- this deletes the file from large object storage on db
SELECT lo_unlink(2630819);
</screen>
- </sect2>
- </sect1>
-</chapter>
+ </sect3>
+ </sect2>
+</sect1>
-----------------------------------------------------------------------
Summary of changes:
doc/Makefile.in | 1 +
doc/administration.xml | 2 +
doc/database_tuning.xml | 177 ++++++++++++++++++++++++++++++++
doc/extras.xml | 6 +-
doc/extras_address_standardizer.xml | 28 ++---
doc/extras_tigergeocoder.xml | 8 +-
doc/extras_topology.xml | 86 ++++++++--------
doc/performance_tips.xml | 198 +++---------------------------------
doc/postgis.xml | 14 +--
doc/usage.xml | 16 +++
doc/using_postgis_app.xml | 40 ++++----
doc/using_postgis_dataman.xml | 124 +++++++++++-----------
doc/using_raster_dataman.xml | 52 +++++-----
13 files changed, 385 insertions(+), 367 deletions(-)
create mode 100644 doc/database_tuning.xml
create mode 100644 doc/usage.xml
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list