[postgis-tickets] r16757 - Update installation docs to reflect raster extension split
Sandro Santilli
strk at kbt.io
Tue Sep 11 02:50:26 PDT 2018
Author: strk
Date: 2018-09-11 02:50:26 -0700 (Tue, 11 Sep 2018)
New Revision: 16757
Modified:
trunk/doc/installation.xml
Log:
Update installation docs to reflect raster extension split
Modified: trunk/doc/installation.xml
===================================================================
--- trunk/doc/installation.xml 2018-09-11 09:20:48 UTC (rev 16756)
+++ trunk/doc/installation.xml 2018-09-11 09:50:26 UTC (rev 16757)
@@ -15,10 +15,17 @@
make
make install</programlisting>
<para>Once postgis is installed, it needs to be enabled in each individual database you want to use it in.</para>
- <note><para>The raster support is currently optional, but installed by default. For enabling using the PostgreSQL 9.1+ extensions model raster is required. Using the extension enable process is preferred and more user-friendly. To spatially enable your database:</para></note>
- <programlisting>psql -d yourdatabase -c "CREATE EXTENSION postgis;"
+ <note><para>Using the extension enable process is preferred and more user-friendly. To spatially enable your database:</para></note>
+ <programlisting>
+psql -d yourdatabase -c "CREATE EXTENSION postgis;"
+
+-- if you built with raster support and want to install it --
+psql -d yourdatabase -c "CREATE EXTENSION postgis_raster;"
+
+-- if you want to install topology support --
psql -d yourdatabase -c "CREATE EXTENSION postgis_topology;"
--- if you built with sfcgal support --
+
+-- if you built with sfcgal support and want to install it --
psql -d yourdatabase -c "CREATE EXTENSION postgis_sfcgal;"
-- if you want to install tiger geocoder --
@@ -33,7 +40,8 @@
<para>Please refer to <xref linkend="make_install_postgis_extensions" /> for more details about querying installed/available extensions and upgrading extensions, or switching from a non-extension install to an extension install.</para>
- <para>For those running who decided for some reason not to compile with raster support, or just are old-fashioned, here are longer more painful instructions for you:</para>
+ <para>For those who decided for some reason to use a non-extension
+based install, here are longer more painful instructions for you:</para>
<para>All the .sql files once installed will be installed in share/contrib/postgis-&last_minor_version; folder
of your PostgreSQL install</para>
@@ -42,21 +50,27 @@
psql -d yourdatabase -f postgis.sql
psql -d yourdatabase -f postgis_comments.sql
psql -d yourdatabase -f spatial_ref_sys.sql
+
+-- if you want to enable topology
psql -d yourdatabase -f topology.sql
psql -d yourdatabase -f topology_comments.sql
--- only if you compiled with raster (GDAL)
+-- if you want to enable raster
+-- and only if you compiled with raster (GDAL)
psql -d yourdatabase -f rtpostgis.sql
psql -d yourdatabase -f raster_comments.sql
---if you built with sfcgal support --
+-- if you want to enable sfcgal backend
+-- and only if you built with sfcgal support --
psql -d yourdatabase -f sfcgal.sql
psql -d yourdatabase -f sfcgal_comments.sql
</programlisting>
+ <sect2 id="install_short_version_raster_configuration">
+
<para>
- The rest of this chapter goes into detail each of the above installation
- steps.
+ 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
@@ -78,6 +92,9 @@
<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>
+
+ </sect2>
+
</sect1>
<sect1 id="install_requirements">
@@ -163,7 +180,10 @@
<listitem>
<para>
- GDAL, version 1.8 or higher (1.9 or higher is strongly recommended since some things will not work well or behavior differently with lower versions). This is required for raster support and to be able to install with <code>CREATE EXTENSION postgis</code> so highly recommended for those running 9.1+.
+ GDAL, version 1.8 or higher (1.9 or higher is strongly
+ recommended since some things will not work well or behavior
+ differently with lower versions). This is required for raster
+ support.
<ulink url="http://trac.osgeo.org/gdal/wiki/DownloadSource">http://trac.osgeo.org/gdal/wiki/DownloadSource</ulink>.
</para>
</listitem>
@@ -176,10 +196,11 @@
<itemizedlist>
<listitem>
<para>
- GDAL (pseudo optional) only if you don't want raster and don't care about installing with <code>CREATE EXTENSION postgis</code> can you leave it out.
- Keep in mind other extensions may have a requires postgis extension which will prevent you from installing them unless you install postgis as an extension. So it is highly recommended you compile with GDAL support.
- </para>
- <para>Also make sure to enable the drivers you want to use as described in <xref linkend="install_short_version" />.</para>
+ GDAL (pseudo optional) only if you don't want raster
+ you can leave it out. Also make sure to enable
+ the drivers you want to use as described in <xref
+ linkend="install_short_version_raster_configuration"/>.
+ </para>
</listitem>
<listitem>
<para>
@@ -517,12 +538,11 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><command>--with-raster</command></term>
+ <term><command>--without-raster</command></term>
<listitem>
<para>
- Compile with raster support. This will build rtpostgis-&last_release_version; library and rtpostgis.sql file. This may not
- be required in final release as plan is to build in raster support by default.
- </para>
+ Compile without raster support.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
@@ -724,19 +744,21 @@
<screen>List of installed extensions
-[ RECORD 1 ]-------------------------------------------------
--
Name | postgis
Version | &last_release_version;
Schema | public
Description | PostGIS geometry, geography, and raster spat..
-[ RECORD 2 ]-------------------------------------------------
--
+Name | postgis_raster
+Version | 3.0.0dev
+Schema | public
+Description | PostGIS raster types and functions
+-[ RECORD 3 ]-------------------------------------------------
Name | postgis_tiger_geocoder
Version | &last_release_version;
Schema | tiger
Description | PostGIS tiger geocoder and reverse geocoder
--[ RECORD 3 ]-------------------------------------------------
--
+-[ RECORD 4 ]-------------------------------------------------
Name | postgis_topology
Version | &last_release_version;
Schema | topology
@@ -747,12 +769,16 @@
As of PostGIS 2.0.1, only srid records not packaged with PostGIS are backed up when the database is backed up so don't go around changing srids we package and expect your changes to be there. Put in a ticket if you find an issue. The structures of extension tables are never backed up since they are created with <code>CREATE EXTENSION</code>
and assumed to be the same for a given version of an extension. These behaviors are built into the current PostgreSQL extension model, so nothing we can do about it.</para></warning>
-<para>If you installed &last_release_version;, without using our wonderful extension system, you can change it to be extension based by first upgrading to the latest micro version running the upgrade scripts: <filename>postgis_upgrade_22_minor.sql</filename>,<filename>raster_upgrade_22_minor.sql</filename>,<filename>topology_upgrade_22_minor.sql</filename>.</para>
-<para>If you installed postgis without raster support, you'll need to install raster support first (using the full <filename>rtpostgis.sql</filename></para>
-<para>Then you can run the below commands to package the functions in their respective extension.</para>
-<programlisting>CREATE EXTENSION postgis FROM unpackaged;
+<para>If you installed &last_release_version;, without using our
+wonderful extension system, you can change it to be extension based by
+running the below commands to package the functions in their respective extension.
+</para>
+<programlisting>
+CREATE EXTENSION postgis FROM unpackaged;
+CREATE EXTENSION postgis_raster FROM unpackaged;
CREATE EXTENSION postgis_topology FROM unpackaged;
-CREATE EXTENSION postgis_tiger_geocoder FROM unpackaged;</programlisting>
+CREATE EXTENSION postgis_tiger_geocoder FROM unpackaged;
+</programlisting>
</sect2>
@@ -1382,7 +1408,7 @@
</para>
<para>
- The core postgis extension installs PostGIS geometry, geography, raster, spatial_ref_sys and all the functions and comments with a simple:
+ The core postgis extension installs PostGIS geometry, geography, spatial_ref_sys and all the functions and comments with a simple:
<programlisting>CREATE EXTENSION postgis;</programlisting> command.
</para>
@@ -1391,6 +1417,14 @@
</para>
<para>
+ Raster is packaged as a separate extension and installable with command:
+ </para>
+
+ <para>
+ <command>psql -d [yourdatabase] -c "CREATE EXTENSION postgis_raster;"</command>
+ </para>
+
+ <para>
Topology is packaged as a separate extension and installable with command:
</para>
@@ -1409,7 +1443,10 @@
<sect1 id="create_new_db">
<title>Create a spatially-enabled database without using extensions</title>
- <note><para>This is generally only needed if you built-PostGIS without raster support. Since raster functions are part of the postgis extension, extension support is not enabled if PostGIS is built without raster.</para></note>
+ <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> The first step in creating a PostGIS database is to create a simple
PostgreSQL database.
</para>
@@ -1813,30 +1850,61 @@
<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>
+ <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 <filename>postgis_upgrade.sql</filename> and <filename>rtpostgis_upgrade.sql</filename> in the installation folders. For example <filename>/usr/share/postgresql/9.3/contrib/postgis_upgrade.sql</filename>. Install the <filename>postgis_upgrade.sql</filename>. If you have raster functionality installed, you will also need to install the <filename>/usr/share/postgresql/9.3/contrib/postgis_upgrade.sql</filename>. If you are moving from PostGIS 1.* to PostGIS 2.* or from PostGIS 2.* prior to r7409, you need to do a HARD UPGRADE.
+ 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>psql -f postgis_upgrade.sql -d your_spatial_database</programlisting>
+ <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 and
- topology extensions, with upgrade files named
- <filename>rtpostgis_upgrade*.sql</filename> and
- <filename>topology_upgrade*.sql</filename> respectively.
+ 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 HARD UPGRADE.
+ 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>
More information about the postgis-tickets
mailing list