[postgis-tickets] [SCM] PostGIS branch master updated. 9d4597b77a416e119f468c51b4da9d616dc5483b
git at osgeo.org
git at osgeo.org
Thu Jan 16 08:23:18 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 9d4597b77a416e119f468c51b4da9d616dc5483b (commit)
from 69865c307e1de61a5ab9332e78d708e8a4169b5d (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 9d4597b77a416e119f468c51b4da9d616dc5483b
Author: Sandro Santilli <strk at kbt.io>
Date: Thu Jan 16 17:22:59 2020 +0100
Split an "administration" section out of "installation"
diff --git a/doc/administration.xml b/doc/administration.xml
new file mode 100644
index 0000000..856851c
--- /dev/null
+++ b/doc/administration.xml
@@ -0,0 +1,457 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="postgis_administration">
+ <title>PostGIS Administration</title>
+
+ <sect1 id="raster_configuration">
+
+ <title>Configuring raster support</title>
+
+ <para>
+ If you enabled raster support you may want to read
+ below how to properly configure it.
+ </para>
+
+ <para>As of PostGIS 2.1.3, out-of-db rasters and all raster drivers are disabled by default. In order to re-enable these, you need to set the following environment variables
+ <varname>POSTGIS_GDAL_ENABLED_DRIVERS</varname> and <varname>POSTGIS_ENABLE_OUTDB_RASTERS</varname> in the server environment. For PostGIS 2.2, you can use the more cross-platform approach of setting the corresponding <xref linkend="PostGIS_GUC" />.</para>
+
+ <para>If you want to enable offline raster:</para>
+ <programlisting>POSTGIS_ENABLE_OUTDB_RASTERS=1</programlisting>
+ <para>Any other setting or no setting at all will disable out of db rasters.</para>
+ <para>In order to enable all GDAL drivers available in your GDAL install, set this environment variable as follows</para>
+ <programlisting>POSTGIS_GDAL_ENABLED_DRIVERS=ENABLE_ALL</programlisting>
+ <para>If you want to only enable specific drivers, set your environment variable as follows:</para>
+ <programlisting>POSTGIS_GDAL_ENABLED_DRIVERS="GTiff PNG JPEG GIF XYZ"</programlisting>
+
+ <note><para>If you are on windows, do not quote the driver list</para></note>
+
+ <para>Setting environment variables varies depending on OS. For PostgreSQL installed on Ubuntu or Debian via apt-postgresql, the preferred way is to
+ edit <filename>/etc/postgresql/<replaceable>10</replaceable>/<replaceable>main</replaceable>/environment</filename> where 10 refers to version of PostgreSQL and main refers to the cluster.</para>
+
+ <para>On windows, if you are running as a service, you can set via System variables which for Windows 7 you can get to by right-clicking on Computer->Properties Advanced System Settings or in explorer navigating to <varname>Control Panel\All Control Panel Items\System</varname>.
+ Then clicking <emphasis>Advanced System Settings ->Advanced->Environment Variables</emphasis> and adding new system variables.</para>
+ <para>After you set the environment variables, you'll need to restart your PostgreSQL service for the changes to take effect.</para>
+
+ </sect1>
+
+ <sect1 id="create_spatial_db">
+ <title>Creating spatial databases</title>
+
+ <sect2 id="create_new_db_extensions">
+ <title>Spatially enable database using EXTENSION</title>
+
+ <para>
+ If you are using PostgreSQL 9.1+ and have compiled and installed the extensions/postgis modules, you
+ can turn a database into a spatial one using the EXTENSION mechanism.
+ </para>
+
+ <para>
+ Core postgis extension includes geometry, geography,
+ spatial_ref_sys and all the functions and comments.
+ Raster and topology are packaged as a separate extension.
+ </para>
+
+ <para>
+ Run the following SQL snippet in the database you want to enable spatially:
+<programlisting>
+ CREATE EXTENSION IF NOT EXISTS plpgsql;
+ CREATE EXTENSION postgis;
+ CREATE EXTENSION postgis_raster; -- OPTIONAL
+ CREATE EXTENSION postgis_topology; -- OPTIONAL
+</programlisting>
+ </para>
+
+ </sect2>
+
+ <sect2 id="create_new_db">
+ <title>Spatially enable database without using EXTENSION (discouraged)</title>
+
+ <note><para>This is generally only needed if you cannot or don't
+want to get PostGIS installed in the PostgreSQL extension directory
+(for example during testing, development or in a restricted
+environment).</para></note>
+
+ <para>
+ Adding PostGIS objects and function definitions into your
+ database is done by loading the various sql files located in
+ <filename>[prefix]/share/contrib</filename> as specified during
+ the build phase.
+ </para>
+
+ <para>
+ The core PostGIS objects (geometry and geography types, and their
+ support functions) are in the <filename>postgis.sql</filename>
+ script.
+ Raster objects are in the <filename>rtpostgis.sql</filename> script.
+ Topology objects are in the <filename>topology.sql</filename> script.
+ </para>
+
+ <para>
+ For a complete set of EPSG coordinate system definition identifiers, you
+ can also load the <filename>spatial_ref_sys.sql</filename> definitions
+ file and populate the <varname>spatial_ref_sys</varname> table. This will
+ permit you to perform ST_Transform() operations on geometries.
+ </para>
+
+ <para>
+ If you wish to add comments to the PostGIS functions, you can find
+ them in the <filename>postgis_comments.sql</filename> script.
+ Comments can be viewed by simply typing <command>\dd
+ [function_name]</command> from a <command>psql</command> terminal window.
+ </para>
+
+ <para>
+ Run the following Shell commands in your terminal:
+<programlisting>
+ DB=[yourdatabase]
+ SCRIPTSDIR=`pg_config --sharedir`/contrib/postgis-&last_minor_version;/
+
+ # Core objects
+ psql -d ${DB} -f ${SCRIPTSDIR}/postgis.sql
+ psql -d ${DB} -f ${SCRIPTSDIR}/spatial_ref_sys.sql
+ psql -d ${DB} -f ${SCRIPTSDIR}/postgis_comments.sql # OPTIONAL
+
+ # Raster support (OPTIONAL)
+ psql -d ${DB} -f ${SCRIPTSDIR}/rtpostgis.sql
+ psql -d ${DB} -f ${SCRIPTSDIR}/raster_comments.sql # OPTIONAL
+
+ # Topology support (OPTIONAL)
+ psql -d ${DB} -f ${SCRIPTSDIR}/topology.sql
+ psql -d ${DB} -f ${SCRIPTSDIR}/topology_comments.sql # OPTIONAL
+</programlisting>
+ </para>
+
+ </sect2>
+
+ <sect2 id="templatepostgis">
+ <title>Create a spatially-enabled database from a template</title>
+
+ <para>
+ Some packaged distributions of PostGIS (in particular the Win32 installers
+ for PostGIS >= 1.1.5) load the PostGIS functions into a template
+ database called <varname>template_postgis</varname>. If the
+ <varname>template_postgis</varname> database exists in your PostgreSQL
+ installation then it is possible for users and/or applications to create
+ spatially-enabled databases using a single command. Note that in both
+ cases, the database user must have been granted the privilege to create
+ new databases.
+ </para>
+
+ <para>
+ From the shell:
+ </para>
+
+ <programlisting># createdb -T template_postgis my_spatial_db</programlisting>
+
+ <para>
+ From SQL:
+ </para>
+
+ <programlisting>postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgis</programlisting>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="upgrading">
+ <title>Upgrading spatial databases</title>
+
+ <para>
+ Upgrading existing spatial databases can be tricky as it requires
+ replacement or introduction of new PostGIS object definitions.
+ </para>
+
+ <para>
+ Unfortunately not all definitions can be easily replaced in a live
+ database, so sometimes your best bet is a dump/reload process.
+ </para>
+
+ <para>
+ PostGIS provides a SOFT UPGRADE procedure for minor or bugfix releases,
+ and a HARD UPGRADE procedure for major releases.
+ </para>
+
+ <para>
+ Before attempting to upgrade PostGIS, it is always worth to backup your
+ data. If you use the -Fc flag to pg_dump you will always be able to
+ restore the dump with a HARD UPGRADE.
+ </para>
+
+ <sect2 id="soft_upgrade">
+ <title>Soft upgrade</title>
+
+ <para>If you installed your database using extensions, you'll need to upgrade using the extension model as well. If you installed using the old sql script way,
+ then you should upgrade using the sql script way. Please refer to the appropriate.</para>
+
+ <sect3 id="soft_upgrade_sql_script">
+ <title>Soft Upgrade Pre 9.1+ or without extensions</title>
+
+ <para>This section applies only to those who installed PostGIS
+ not using extensions. If you have extensions and try to
+ upgrade with this approach you'll get messages like:</para>
+
+ <programlisting>can't drop ... because postgis extension depends on it</programlisting>
+
+ <para>NOTE: if you are moving from PostGIS 1.* to PostGIS 2.* or from
+ PostGIS 2.* prior to r7409, you cannot use this procedure but
+ would rather need to do a
+ <link linkend="hard_upgrade">HARD UPGRADE</link>.
+ </para>
+
+ <para>
+ After compiling and installing (make install) you should
+ find a set of <filename>*_upgrade.sql</filename>
+ files in the installation folders. You can list
+ them all with:
+ </para>
+
+ <programlisting>ls `pg_config --sharedir`/contrib/postgis-&last_release_version;/*_upgrade.sql</programlisting>
+
+ <para>
+ Load them all in turn, starting from <filename>postgis_upgrade.sql</filename>.
+ </para>
+
+ <programlisting>psql -f postgis_upgrade.sql -d your_spatial_database</programlisting>
+
+ <para>
+ The same procedure applies to raster,
+ topology and sfcgal extensions, with upgrade files named
+ <filename>rtpostgis_upgrade.sql</filename>,
+ <filename>topology_upgrade.sql</filename> and
+ <filename>sfcgal_upgrade.sql</filename> respectively.
+ If you need them:
+ </para>
+
+ <programlisting>psql -f rtpostgis_upgrade.sql -d your_spatial_database</programlisting>
+ <programlisting>psql -f topology_upgrade.sql -d your_spatial_database</programlisting>
+ <programlisting>psql -f sfcgal_upgrade.sql -d your_spatial_database</programlisting>
+
+ <note>
+ <para>
+ If you can't find the
+ <filename>postgis_upgrade.sql</filename> specific for
+ upgrading your version you are using a version too
+ early for a soft upgrade and need to do a
+ <link linkend="hard_upgrade">HARD UPGRADE</link>.
+ </para>
+ </note>
+
+ <para>
+ The <xref linkend="PostGIS_Full_Version" /> function
+ should inform you about the need to run this kind of
+ upgrade using a "procs need upgrade" message.
+ </para>
+ </sect3>
+
+ <sect3 id="soft_upgrade_extensions"><title>Soft Upgrade 9.1+ using extensions</title>
+ <para>If you originally installed PostGIS with extensions, then you need to upgrade using extensions as well. Doing a minor upgrade with extensions, is fairly painless.</para>
+ <programlisting>ALTER EXTENSION postgis UPDATE TO "&last_release_version;";
+ALTER EXTENSION postgis_topology UPDATE TO "&last_release_version;";</programlisting>
+ <para>If you get an error notice something like:</para>
+ <programlisting>No migration path defined for ... to &last_release_version;</programlisting>
+ <para>Then you'll need to backup your database, create a fresh one as described in <xref linkend="create_new_db_extensions" /> and then restore your backup ontop of this new database.</para>
+ <para>If you get a notice message like:</para>
+ <programlisting>Version "&last_release_version;" of extension "postgis" is already installed</programlisting>
+ <para>
+Then everything is already up to date and you can safely ignore it. <emphasis role="bold">UNLESS</emphasis>
+you're attempting to upgrade from an development version to the next (which
+doesn't get a new version number); in that case you can append "next" to the version
+string, and next time you'll need to drop the "next" suffix again:
+ </para>
+ <programlisting>ALTER EXTENSION postgis UPDATE TO "&last_release_version;next";
+ALTER EXTENSION postgis_topology UPDATE TO "&last_release_version;next";</programlisting>
+ <note><para>If you installed PostGIS originally without a version specified, you can often skip the reinstallation of postgis extension before restoring since the backup just has <code>CREATE EXTENSION postgis</code> and thus
+ picks up the newest latest version during restore.</para></note>
+
+ <note>
+ <para>
+ If you are upgrading PostGIS extension from a version prior to 3.0.0
+ you'll end up with an unpackaged PostGIS Raster support. You can
+ repackage the raster support using:
+ <programlisting>
+ CREATE EXTENSION postgis_raster FROM unpackaged;
+ </programlisting>
+ And then, if you don't need it, drop it with:
+ <programlisting>
+ DROP EXTENSION postgis_raster;
+ </programlisting>
+ </para>
+ </note>
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="hard_upgrade">
+ <title>Hard upgrade</title>
+
+ <para>
+ By HARD UPGRADE we mean full dump/reload of postgis-enabled databases.
+ You need a HARD UPGRADE when PostGIS objects' internal storage changes
+ or when SOFT UPGRADE is not possible. The
+ <link linkend="release_notes">Release Notes</link>
+ appendix reports for each version whether you need a dump/reload (HARD
+ UPGRADE) to upgrade.
+ </para>
+
+ <para>
+ The dump/reload process is assisted by the postgis_restore.pl
+ script which takes care of skipping from the dump all
+ definitions which belong to PostGIS (including old ones),
+ allowing you to restore your schemas and data into a
+ database with PostGIS installed without getting duplicate
+ symbol errors or bringing forward deprecated objects.
+ </para>
+
+ <para>Supplementary instructions for windows users are available at <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiWinUpgrade">Windows Hard upgrade</ulink>.</para>
+
+
+ <para>
+ The Procedure is as follows:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+
+ <para>
+ Create a "custom-format" dump of the database you want
+ to upgrade (let's call it <varname>olddb</varname>)
+ include binary blobs (-b) and verbose (-v) output.
+ The user can be the owner of the db, need not be postgres
+ super account.
+ </para>
+
+ <programlisting>pg_dump -h localhost -p 5432 -U postgres -Fc -b -v -f "/somepath/olddb.backup" olddb</programlisting>
+
+ </listitem>
+
+ <listitem>
+
+ <para>
+ Do a fresh install of PostGIS in a new database -- we'll
+ refer to this database as <varname>newdb</varname>.
+ Please refer to <xref linkend="create_new_db" /> and <xref linkend="create_new_db_extensions" /> for
+ instructions on how to do this.
+ </para>
+
+ <para>
+ The spatial_ref_sys entries found in your dump will be
+ restored, but they will not override existing ones in
+ spatial_ref_sys. This is to ensure that fixes in the
+ official set will be properly propagated to restored
+ databases. If for any reason you really want your own
+ overrides of standard entries just don't load the
+ spatial_ref_sys.sql file when creating the new db.
+ </para>
+
+ <para>
+ If your database is really old or you know you've
+ been using long deprecated functions in your
+ views and functions, you might need to load
+ <filename>legacy.sql</filename> for all your functions
+ and views etc. to properly come back.
+ Only do this if _really_ needed. Consider upgrading your
+ views and functions before dumping instead, if possible.
+ The deprecated functions can be later removed by loading
+ <filename>uninstall_legacy.sql</filename>.
+ </para>
+
+ </listitem>
+
+ <listitem>
+
+ <para>
+ Restore your backup into your fresh
+ <varname>newdb</varname> database using
+ postgis_restore.pl.
+ Unexpected errors, if any, will be printed to the standard
+ error stream by psql. Keep a log of those.
+ </para>
+
+ <programlisting>perl utils/postgis_restore.pl "/somepath/olddb.backup" | psql -h localhost -p 5432 -U postgres newdb 2> errors.txt</programlisting>
+
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Errors may arise in the following cases:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ Some of your views or functions make use of deprecated PostGIS objects.
+ In order to fix this you may try loading <filename>legacy.sql</filename>
+ script prior to restore or you'll have to restore to a
+ version of PostGIS which still contains those objects
+ and try a migration again after porting your code.
+ If the <filename>legacy.sql</filename> way works for you, don't forget
+ to fix your code to stop using deprecated functions and drop them
+ loading <filename>uninstall_legacy.sql</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Some custom records of spatial_ref_sys in dump file have
+ an invalid SRID value. Valid SRID values are bigger than 0
+ and smaller than 999000. Values in the 999000.999999 range
+ are reserved for internal use while values > 999999 can't
+ be used at all.
+ All your custom records with invalid SRIDs will be retained,
+ with those > 999999 moved into the reserved range, but the
+ spatial_ref_sys table would lose a check constraint guarding
+ for that invariant to hold and possibly also its primary key
+ ( when multiple invalid SRIDS get converted to the same reserved
+ SRID value ).
+ </para>
+
+ <para>
+ In order to fix this you should copy your custom SRS to
+ a SRID with a valid value (maybe in the 910000..910999
+ range), convert all your tables to the new srid (see
+ <xref linkend="UpdateGeometrySRID"/>), delete the invalid
+ entry from spatial_ref_sys and re-construct the check(s) with:
+
+ <programlisting>ALTER TABLE spatial_ref_sys ADD CONSTRAINT spatial_ref_sys_srid_check check (srid > 0 AND srid < 999000 );</programlisting>
+
+ <programlisting>ALTER TABLE spatial_ref_sys ADD PRIMARY KEY(srid));</programlisting>
+
+ If you are upgrading an old database containing french <ulink url="https://en.wikipedia.org/wiki/Institut_g%C3%A9ographique_national">
+ IGN
+ </ulink> cartography, you will have probably SRIDs out
+ of range and you will see, when importing your database, issues like this :
+
+ <programlisting> WARNING: SRID 310642222 converted to 999175 (in reserved zone)</programlisting>
+
+ In this case, you can try following steps : first throw
+ out completely the IGN from the sql which is resulting
+ from postgis_restore.pl. So, after having run :
+
+ <programlisting>perl utils/postgis_restore.pl "/somepath/olddb.backup" > olddb.sql</programlisting>
+
+ run this command :
+
+ <programlisting>grep -v IGNF olddb.sql > olddb-without-IGN.sql</programlisting>
+
+ Create then your newdb, activate the required Postgis extensions,
+ and insert properly the french system IGN with :
+
+ <ulink url="https://raw.githubusercontent.com/Remi-C/IGN_spatial_ref_for_PostGIS/master/Put_IGN_SRS_into_Postgis.sql">
+ this script
+ </ulink>
+
+ After these operations, import your data :
+
+ <programlisting>psql -h localhost -p 5432 -U postgres -d newdb -f olddb-without-IGN.sql 2> errors.txt</programlisting>
+
+ </para>
+ </listitem>
+ </orderedlist>
+
+
+ </sect2>
+ </sect1>
+
+
+
+</chapter>
diff --git a/doc/installation.xml b/doc/installation.xml
index 6efa4f9..a9476ce 100644
--- a/doc/installation.xml
+++ b/doc/installation.xml
@@ -23,37 +23,6 @@ in each individual database you want to use it in.
</sect1>
- <sect1 id="raster_configuration">
-
- <title>Configuring raster</title>
-
- <para>
- If you enabled raster support you may want to read
- below how to properly configure it.
- </para>
-
- <para>As of PostGIS 2.1.3, out-of-db rasters and all raster drivers are disabled by default. In order to re-enable these, you need to set the following environment variables
- <varname>POSTGIS_GDAL_ENABLED_DRIVERS</varname> and <varname>POSTGIS_ENABLE_OUTDB_RASTERS</varname> in the server environment. For PostGIS 2.2, you can use the more cross-platform approach of setting the corresponding <xref linkend="PostGIS_GUC" />.</para>
-
- <para>If you want to enable offline raster:</para>
- <programlisting>POSTGIS_ENABLE_OUTDB_RASTERS=1</programlisting>
- <para>Any other setting or no setting at all will disable out of db rasters.</para>
- <para>In order to enable all GDAL drivers available in your GDAL install, set this environment variable as follows</para>
- <programlisting>POSTGIS_GDAL_ENABLED_DRIVERS=ENABLE_ALL</programlisting>
- <para>If you want to only enable specific drivers, set your environment variable as follows:</para>
- <programlisting>POSTGIS_GDAL_ENABLED_DRIVERS="GTiff PNG JPEG GIF XYZ"</programlisting>
-
- <note><para>If you are on windows, do not quote the driver list</para></note>
-
- <para>Setting environment variables varies depending on OS. For PostgreSQL installed on Ubuntu or Debian via apt-postgresql, the preferred way is to
- edit <filename>/etc/postgresql/<replaceable>10</replaceable>/<replaceable>main</replaceable>/environment</filename> where 10 refers to version of PostgreSQL and main refers to the cluster.</para>
-
- <para>On windows, if you are running as a service, you can set via System variables which for Windows 7 you can get to by right-clicking on Computer->Properties Advanced System Settings or in explorer navigating to <varname>Control Panel\All Control Panel Items\System</varname>.
- Then clicking <emphasis>Advanced System Settings ->Advanced->Environment Variables</emphasis> and adding new system variables.</para>
- <para>After you set the environment variables, you'll need to restart your PostgreSQL service for the changes to take effect.</para>
-
- </sect1>
-
<sect1 id="PGInstall">
<title>Compiling and Install from Source</title>
@@ -1753,426 +1722,6 @@ All 2 tests passed.
</sect2>
</sect1>
- <sect1 id="create_spatial_db">
- <title>Creating spatial databases</title>
-
- <sect2 id="create_new_db_extensions">
- <title>Spatially enable database using EXTENSION</title>
-
- <para>
- If you are using PostgreSQL 9.1+ and have compiled and installed the extensions/postgis modules, you
- can turn a database into a spatial one using the EXTENSION mechanism.
- </para>
-
- <para>
- Core postgis extension includes geometry, geography,
- spatial_ref_sys and all the functions and comments.
- Raster and topology are packaged as a separate extension.
- </para>
-
- <para>
- Run the following SQL snippet in the database you want to enable spatially:
-<programlisting>
- CREATE EXTENSION IF NOT EXISTS plpgsql;
- CREATE EXTENSION postgis;
- CREATE EXTENSION postgis_raster; -- OPTIONAL
- CREATE EXTENSION postgis_topology; -- OPTIONAL
-</programlisting>
- </para>
-
- </sect2>
-
- <sect2 id="create_new_db">
- <title>Spatially enable database without using EXTENSION (discouraged)</title>
-
- <note><para>This is generally only needed if you cannot or don't
-want to get PostGIS installed in the PostgreSQL extension directory
-(for example during testing, development or in a restricted
-environment).</para></note>
-
- <para>
- Adding PostGIS objects and function definitions into your
- database is done by loading the various sql files located in
- <filename>[prefix]/share/contrib</filename> as specified during
- the build phase.
- </para>
-
- <para>
- The core PostGIS objects (geometry and geography types, and their
- support functions) are in the <filename>postgis.sql</filename>
- script.
- Raster objects are in the <filename>rtpostgis.sql</filename> script.
- Topology objects are in the <filename>topology.sql</filename> script.
- </para>
-
- <para>
- For a complete set of EPSG coordinate system definition identifiers, you
- can also load the <filename>spatial_ref_sys.sql</filename> definitions
- file and populate the <varname>spatial_ref_sys</varname> table. This will
- permit you to perform ST_Transform() operations on geometries.
- </para>
-
- <para>
- If you wish to add comments to the PostGIS functions, you can find
- them in the <filename>postgis_comments.sql</filename> script.
- Comments can be viewed by simply typing <command>\dd
- [function_name]</command> from a <command>psql</command> terminal window.
- </para>
-
- <para>
- Run the following Shell commands in your terminal:
-<programlisting>
- DB=[yourdatabase]
- SCRIPTSDIR=`pg_config --sharedir`/contrib/postgis-&last_minor_version;/
-
- # Core objects
- psql -d ${DB} -f ${SCRIPTSDIR}/postgis.sql
- psql -d ${DB} -f ${SCRIPTSDIR}/spatial_ref_sys.sql
- psql -d ${DB} -f ${SCRIPTSDIR}/postgis_comments.sql # OPTIONAL
-
- # Raster support (OPTIONAL)
- psql -d ${DB} -f ${SCRIPTSDIR}/rtpostgis.sql
- psql -d ${DB} -f ${SCRIPTSDIR}/raster_comments.sql # OPTIONAL
-
- # Topology support (OPTIONAL)
- psql -d ${DB} -f ${SCRIPTSDIR}/topology.sql
- psql -d ${DB} -f ${SCRIPTSDIR}/topology_comments.sql # OPTIONAL
-</programlisting>
- </para>
-
- </sect2>
-
- <sect2 id="templatepostgis">
- <title>Create a spatially-enabled database from a template</title>
-
- <para>
- Some packaged distributions of PostGIS (in particular the Win32 installers
- for PostGIS >= 1.1.5) load the PostGIS functions into a template
- database called <varname>template_postgis</varname>. If the
- <varname>template_postgis</varname> database exists in your PostgreSQL
- installation then it is possible for users and/or applications to create
- spatially-enabled databases using a single command. Note that in both
- cases, the database user must have been granted the privilege to create
- new databases.
- </para>
-
- <para>
- From the shell:
- </para>
-
- <programlisting># createdb -T template_postgis my_spatial_db</programlisting>
-
- <para>
- From SQL:
- </para>
-
- <programlisting>postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgis</programlisting>
- </sect2>
-
- </sect1>
-
- <sect1 id="upgrading">
- <title>Upgrading spatial databases</title>
-
- <para>
- Upgrading existing spatial databases can be tricky as it requires
- replacement or introduction of new PostGIS object definitions.
- </para>
-
- <para>
- Unfortunately not all definitions can be easily replaced in a live
- database, so sometimes your best bet is a dump/reload process.
- </para>
-
- <para>
- PostGIS provides a SOFT UPGRADE procedure for minor or bugfix releases,
- and a HARD UPGRADE procedure for major releases.
- </para>
-
- <para>
- Before attempting to upgrade PostGIS, it is always worth to backup your
- data. If you use the -Fc flag to pg_dump you will always be able to
- restore the dump with a HARD UPGRADE.
- </para>
-
- <sect2 id="soft_upgrade">
- <title>Soft upgrade</title>
-
- <para>If you installed your database using extensions, you'll need to upgrade using the extension model as well. If you installed using the old sql script way,
- then you should upgrade using the sql script way. Please refer to the appropriate.</para>
-
- <sect3 id="soft_upgrade_sql_script">
- <title>Soft Upgrade Pre 9.1+ or without extensions</title>
-
- <para>This section applies only to those who installed PostGIS
- not using extensions. If you have extensions and try to
- upgrade with this approach you'll get messages like:</para>
-
- <programlisting>can't drop ... because postgis extension depends on it</programlisting>
-
- <para>NOTE: if you are moving from PostGIS 1.* to PostGIS 2.* or from
- PostGIS 2.* prior to r7409, you cannot use this procedure but
- would rather need to do a
- <link linkend="hard_upgrade">HARD UPGRADE</link>.
- </para>
-
- <para>
- After compiling and installing (make install) you should
- find a set of <filename>*_upgrade.sql</filename>
- files in the installation folders. You can list
- them all with:
- </para>
-
- <programlisting>ls `pg_config --sharedir`/contrib/postgis-&last_release_version;/*_upgrade.sql</programlisting>
-
- <para>
- Load them all in turn, starting from <filename>postgis_upgrade.sql</filename>.
- </para>
-
- <programlisting>psql -f postgis_upgrade.sql -d your_spatial_database</programlisting>
-
- <para>
- The same procedure applies to raster,
- topology and sfcgal extensions, with upgrade files named
- <filename>rtpostgis_upgrade.sql</filename>,
- <filename>topology_upgrade.sql</filename> and
- <filename>sfcgal_upgrade.sql</filename> respectively.
- If you need them:
- </para>
-
- <programlisting>psql -f rtpostgis_upgrade.sql -d your_spatial_database</programlisting>
- <programlisting>psql -f topology_upgrade.sql -d your_spatial_database</programlisting>
- <programlisting>psql -f sfcgal_upgrade.sql -d your_spatial_database</programlisting>
-
- <note>
- <para>
- If you can't find the
- <filename>postgis_upgrade.sql</filename> specific for
- upgrading your version you are using a version too
- early for a soft upgrade and need to do a
- <link linkend="hard_upgrade">HARD UPGRADE</link>.
- </para>
- </note>
-
- <para>
- The <xref linkend="PostGIS_Full_Version" /> function
- should inform you about the need to run this kind of
- upgrade using a "procs need upgrade" message.
- </para>
- </sect3>
-
- <sect3 id="soft_upgrade_extensions"><title>Soft Upgrade 9.1+ using extensions</title>
- <para>If you originally installed PostGIS with extensions, then you need to upgrade using extensions as well. Doing a minor upgrade with extensions, is fairly painless.</para>
- <programlisting>ALTER EXTENSION postgis UPDATE TO "&last_release_version;";
-ALTER EXTENSION postgis_topology UPDATE TO "&last_release_version;";</programlisting>
- <para>If you get an error notice something like:</para>
- <programlisting>No migration path defined for ... to &last_release_version;</programlisting>
- <para>Then you'll need to backup your database, create a fresh one as described in <xref linkend="create_new_db_extensions" /> and then restore your backup ontop of this new database.</para>
- <para>If you get a notice message like:</para>
- <programlisting>Version "&last_release_version;" of extension "postgis" is already installed</programlisting>
- <para>
-Then everything is already up to date and you can safely ignore it. <emphasis role="bold">UNLESS</emphasis>
-you're attempting to upgrade from an development version to the next (which
-doesn't get a new version number); in that case you can append "next" to the version
-string, and next time you'll need to drop the "next" suffix again:
- </para>
- <programlisting>ALTER EXTENSION postgis UPDATE TO "&last_release_version;next";
-ALTER EXTENSION postgis_topology UPDATE TO "&last_release_version;next";</programlisting>
- <note><para>If you installed PostGIS originally without a version specified, you can often skip the reinstallation of postgis extension before restoring since the backup just has <code>CREATE EXTENSION postgis</code> and thus
- picks up the newest latest version during restore.</para></note>
-
- <note>
- <para>
- If you are upgrading PostGIS extension from a version prior to 3.0.0
- you'll end up with an unpackaged PostGIS Raster support. You can
- repackage the raster support using:
- <programlisting>
- CREATE EXTENSION postgis_raster FROM unpackaged;
- </programlisting>
- And then, if you don't need it, drop it with:
- <programlisting>
- DROP EXTENSION postgis_raster;
- </programlisting>
- </para>
- </note>
-
- </sect3>
-
- </sect2>
-
- <sect2 id="hard_upgrade">
- <title>Hard upgrade</title>
-
- <para>
- By HARD UPGRADE we mean full dump/reload of postgis-enabled databases.
- You need a HARD UPGRADE when PostGIS objects' internal storage changes
- or when SOFT UPGRADE is not possible. The
- <link linkend="release_notes">Release Notes</link>
- appendix reports for each version whether you need a dump/reload (HARD
- UPGRADE) to upgrade.
- </para>
-
- <para>
- The dump/reload process is assisted by the postgis_restore.pl
- script which takes care of skipping from the dump all
- definitions which belong to PostGIS (including old ones),
- allowing you to restore your schemas and data into a
- database with PostGIS installed without getting duplicate
- symbol errors or bringing forward deprecated objects.
- </para>
-
- <para>Supplementary instructions for windows users are available at <ulink url="http://trac.osgeo.org/postgis/wiki/UsersWikiWinUpgrade">Windows Hard upgrade</ulink>.</para>
-
-
- <para>
- The Procedure is as follows:
- </para>
-
- <orderedlist>
-
- <listitem>
-
- <para>
- Create a "custom-format" dump of the database you want
- to upgrade (let's call it <varname>olddb</varname>)
- include binary blobs (-b) and verbose (-v) output.
- The user can be the owner of the db, need not be postgres
- super account.
- </para>
-
- <programlisting>pg_dump -h localhost -p 5432 -U postgres -Fc -b -v -f "/somepath/olddb.backup" olddb</programlisting>
-
- </listitem>
-
- <listitem>
-
- <para>
- Do a fresh install of PostGIS in a new database -- we'll
- refer to this database as <varname>newdb</varname>.
- Please refer to <xref linkend="create_new_db" /> and <xref linkend="create_new_db_extensions" /> for
- instructions on how to do this.
- </para>
-
- <para>
- The spatial_ref_sys entries found in your dump will be
- restored, but they will not override existing ones in
- spatial_ref_sys. This is to ensure that fixes in the
- official set will be properly propagated to restored
- databases. If for any reason you really want your own
- overrides of standard entries just don't load the
- spatial_ref_sys.sql file when creating the new db.
- </para>
-
- <para>
- If your database is really old or you know you've
- been using long deprecated functions in your
- views and functions, you might need to load
- <filename>legacy.sql</filename> for all your functions
- and views etc. to properly come back.
- Only do this if _really_ needed. Consider upgrading your
- views and functions before dumping instead, if possible.
- The deprecated functions can be later removed by loading
- <filename>uninstall_legacy.sql</filename>.
- </para>
-
- </listitem>
-
- <listitem>
-
- <para>
- Restore your backup into your fresh
- <varname>newdb</varname> database using
- postgis_restore.pl.
- Unexpected errors, if any, will be printed to the standard
- error stream by psql. Keep a log of those.
- </para>
-
- <programlisting>perl utils/postgis_restore.pl "/somepath/olddb.backup" | psql -h localhost -p 5432 -U postgres newdb 2> errors.txt</programlisting>
-
- </listitem>
-
- </orderedlist>
-
- <para>
- Errors may arise in the following cases:
- </para>
-
- <orderedlist>
- <listitem>
- <para>
- Some of your views or functions make use of deprecated PostGIS objects.
- In order to fix this you may try loading <filename>legacy.sql</filename>
- script prior to restore or you'll have to restore to a
- version of PostGIS which still contains those objects
- and try a migration again after porting your code.
- If the <filename>legacy.sql</filename> way works for you, don't forget
- to fix your code to stop using deprecated functions and drop them
- loading <filename>uninstall_legacy.sql</filename>.
- </para>
- </listitem>
- <listitem>
- <para>
- Some custom records of spatial_ref_sys in dump file have
- an invalid SRID value. Valid SRID values are bigger than 0
- and smaller than 999000. Values in the 999000.999999 range
- are reserved for internal use while values > 999999 can't
- be used at all.
- All your custom records with invalid SRIDs will be retained,
- with those > 999999 moved into the reserved range, but the
- spatial_ref_sys table would lose a check constraint guarding
- for that invariant to hold and possibly also its primary key
- ( when multiple invalid SRIDS get converted to the same reserved
- SRID value ).
- </para>
-
- <para>
- In order to fix this you should copy your custom SRS to
- a SRID with a valid value (maybe in the 910000..910999
- range), convert all your tables to the new srid (see
- <xref linkend="UpdateGeometrySRID"/>), delete the invalid
- entry from spatial_ref_sys and re-construct the check(s) with:
-
- <programlisting>ALTER TABLE spatial_ref_sys ADD CONSTRAINT spatial_ref_sys_srid_check check (srid > 0 AND srid < 999000 );</programlisting>
-
- <programlisting>ALTER TABLE spatial_ref_sys ADD PRIMARY KEY(srid));</programlisting>
-
- If you are upgrading an old database containing french <ulink url="https://en.wikipedia.org/wiki/Institut_g%C3%A9ographique_national">
- IGN
- </ulink> cartography, you will have probably SRIDs out
- of range and you will see, when importing your database, issues like this :
-
- <programlisting> WARNING: SRID 310642222 converted to 999175 (in reserved zone)</programlisting>
-
- In this case, you can try following steps : first throw
- out completely the IGN from the sql which is resulting
- from postgis_restore.pl. So, after having run :
-
- <programlisting>perl utils/postgis_restore.pl "/somepath/olddb.backup" > olddb.sql</programlisting>
-
- run this command :
-
- <programlisting>grep -v IGNF olddb.sql > olddb-without-IGN.sql</programlisting>
-
- Create then your newdb, activate the required Postgis extensions,
- and insert properly the french system IGN with :
-
- <ulink url="https://raw.githubusercontent.com/Remi-C/IGN_spatial_ref_for_PostGIS/master/Put_IGN_SRS_into_Postgis.sql">
- this script
- </ulink>
-
- After these operations, import your data :
-
- <programlisting>psql -h localhost -p 5432 -U postgres -d newdb -f olddb-without-IGN.sql 2> errors.txt</programlisting>
-
- </para>
- </listitem>
- </orderedlist>
-
-
- </sect2>
- </sect1>
-
-
<sect1 id="installing_pagc_address_standardizer"><title>Installing and Using the address standardizer</title>
<para>The <code>address_standardizer</code> extension used to be a separate package that required separate download. From PostGIS 2.2 on, it is now bundled in.
For more information about the address_standardize, what it does, and how to configure it for your needs, refer to <xref linkend="Address_Standardizer" />.</para>
diff --git a/doc/postgis.xml b/doc/postgis.xml
index 5608768..b9577d2 100644
--- a/doc/postgis.xml
+++ b/doc/postgis.xml
@@ -17,6 +17,7 @@
<!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY installation SYSTEM "installation.xml">
+<!ENTITY administration SYSTEM "administration.xml">
<!ENTITY faq SYSTEM "faq.xml">
<!ENTITY using_postgis_dataman SYSTEM "using_postgis_dataman.xml">
<!ENTITY using_raster_dataman SYSTEM "using_raster_dataman.xml">
@@ -175,6 +176,7 @@
&introduction;
&installation;
+ &administration;
&faq;
&using_postgis_dataman;
&using_raster_dataman;
-----------------------------------------------------------------------
Summary of changes:
doc/administration.xml | 457 +++++++++++++++++++++++++++++++++++++++++++++++++
doc/installation.xml | 451 ------------------------------------------------
doc/postgis.xml | 2 +
3 files changed, 459 insertions(+), 451 deletions(-)
create mode 100644 doc/administration.xml
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list