464 lines
18 KiB
XML
464 lines
18 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter id="postgis_administration">
|
|
<title>PostGIS Administration</title>
|
|
|
|
&database_tuning;
|
|
|
|
<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, you are advised to switch your install to extensions because the script way is no longer supported. </para>
|
|
|
|
<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>
|
|
<para>If you are running PostGIS 3 or above, then you should use the <xref linkend="PostGIS_Extensions_Upgrade" /> function to upgrade to the latest version you have installed.</para>
|
|
<programlisting>SELECT postgis_extensions_upgrade();</programlisting>
|
|
|
|
<para>If you are running PostGIS 2.5 or lower, then do the following:</para>
|
|
<programlisting>ALTER EXTENSION postgis UPDATE;
|
|
SELECT postgis_extensions_upgrade();
|
|
-- This second call is needed to rebundle postgis_raster extension
|
|
SELECT postgis_extensions_upgrade();
|
|
</programlisting>
|
|
|
|
<para>If you have multiple versions of PostGIS installed, and you don't want to upgrade to the latest, you can explicitly specify the version as follows:</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 on top 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 will have a new extension <emphasis>postgis_raster</emphasis>
|
|
which you can safely drop, if you don't need raster support. You can drop as follows:</para>
|
|
<programlisting>DROP EXTENSION postgis_raster;</programlisting>
|
|
</note>
|
|
|
|
</sect3>
|
|
|
|
<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>
|
|
|
|
<para>You are advised to switch to an extension based install by running</para>
|
|
<programlisting>psql -c "SELECT postgis_extensions_upgrade();"</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>
|
|
|
|
</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>
|