docs - add information on upgrading to PostGIS 2.5.4 (#10550)

* docs - add information on upgrading to PostGIS 2.5.4

Upgrade instructions 2.1.5 to different versions of 2.5.4

* docs - upgrade to PostGIS 2.5.4 review comments

* docs - more review comment updates.
reorder upgrade sections.
clarify removing PostGIS package, is for removing the gppkg

* docs - minor edit

* docs - review updates - more emphasis on removing PostGIS from a database deleting objects.
-Create separate paragraph in Upgrading section.
-Add warning in Removing PostGIS section

* docs - minor review comment update

* small edits
Co-authored-by: NDavid Yozie <dyozie@pivotal.io>

gpdb-doc/dita/analytics/analytics.ditamap

@@ -5,28 +5,33 @@
         navtitle="Pivotal Greenplum® 7.0 Beta Documentation" format="html" otherprops="op-help"/>
     <topicref href="overview.xml" linking="none"/>
     <topicref href="madlib.xml" navtitle="Machine Learning and Deep Learning" linking="none">
-      <topicref href="madlib.xml#topic3" navtitle="Installing MADlib" linking="none"/>
-      <topicref href="madlib.xml#topic_eqm_klx_hw" navtitle="Upgrading MADlib" linking="none"/>
-      <topicref href="madlib.xml#topic6" navtitle="Uninstalling MADlib" linking="none"/>
-      <topicref href="madlib.xml#topic9" navtitle="Examples" linking="none"/>
-      <topicref href="madlib.xml#topic10" navtitle="References" linking="none"/>
-      </topicref>
-    <topicref href="graph.xml" navtitle="Graph Analytics" linking="none"/>    
-    <topicref href="postGIS.xml" navtitle="Geospatial Analytics" otherprops="pivotal" linking="none"/>
-    <topicref href="text.xml" navtitle="Text Analytics and Search" otherprops="pivotal" linking="none"/>
+        <topicref href="madlib.xml#topic3" navtitle="Installing MADlib" linking="none"/>
+        <topicref href="madlib.xml#topic_eqm_klx_hw" navtitle="Upgrading MADlib" linking="none"/>
+        <topicref href="madlib.xml#topic6" navtitle="Uninstalling MADlib" linking="none"/>
+        <topicref href="madlib.xml#topic9" navtitle="Examples" linking="none"/>
+        <topicref href="madlib.xml#topic10" navtitle="References" linking="none"/>
+    </topicref>
+    <topicref href="graph.xml" navtitle="Graph Analytics" linking="none"/>
+    <topicref href="postGIS.xml" navtitle="Geospatial Analytics" otherprops="pivotal" linking="none">
+        <topicref href="postgis-upgrade.xml" otherprops="pivotal" linking="none"/>
+    </topicref>
+    <topicref href="text.xml" navtitle="Text Analytics and Search" otherprops="pivotal"
+        linking="none"/>
+    <topicref href="text.xml" navtitle="Text Analytics and Search" otherprops="pivotal"
+        linking="none"/>
     <topicref href="intro.xml" navtitle="Procedural Languages" linking="none">
-    <topicref href="pl_container.xml" navtitle="PL/Container" linking="none">
-          <topicref href="pl_container.xml#about_pl_container"  linking="none"/>
-          <topicref href="pl_container.xml#topic3"  linking="none"/>
-          <topicref href="pl_container.xml#upgrade_plcontainer"  linking="none"/>
-          <topicref href="pl_container.xml#uninstall_plcontainer"  linking="none"/>
-          <topicref href="pl_container_using.xml"  linking="none"/>
-          </topicref>
-      <topicref href="pl_java.xml" linking="none"/>
-      <topicref href="pl_perl.xml" linking="none"/>
-      <topicref href="pl_sql.xml" linking="none"/>
-      <topicref href="pl_python.xml" linking="none"/>
-      <topicref href="pl_r.xml" linking="none"/>
+        <topicref href="pl_container.xml" navtitle="PL/Container" linking="none">
+            <topicref href="pl_container.xml#about_pl_container" linking="none"/>
+            <topicref href="pl_container.xml#topic3" linking="none"/>
+            <topicref href="pl_container.xml#upgrade_plcontainer" linking="none"/>
+            <topicref href="pl_container.xml#uninstall_plcontainer" linking="none"/>
+            <topicref href="pl_container_using.xml" linking="none"/>
+        </topicref>
+        <topicref href="pl_java.xml" linking="none"/>
+        <topicref href="pl_perl.xml" linking="none"/>
+        <topicref href="pl_sql.xml" linking="none"/>
+        <topicref href="pl_python.xml" linking="none"/>
+        <topicref href="pl_r.xml" linking="none"/>
     </topicref>
     <topicref href="greenplum_r_client.xml" linking="none"/>
 </map>

gpdb-doc/dita/analytics/postGIS.xml

@@ -21,6 +21,8 @@
         <xref href="#postgis_support" format="dita"/>
       </li>
     </ul>
+    <p>For information about upgrading PostGIS on Greenplum Database 6 systems, see <xref
+        href="postgis-upgrade.xml"/></p>
   </body>
   <topic id="topic2" xml:lang="en">
     <title id="ij166739">About PostGIS</title>
@@ -146,6 +148,8 @@
           <li><xref href="#topic_fx2_fpx_llb" format="dita"/></li>
           <li><xref href="#topic_bgz_vcl_r1b" format="dita"/></li>
         </ul></p>
+      <p>For information about upgrading PostGIS on Greenplum Database 6 systems, see <xref
+          href="postgis-upgrade.xml"/></p>
     </body>
     <topic id="topic_ln5_xcl_r1b">
       <title>Enabling PostGIS Support</title>
@@ -262,6 +266,10 @@ CREATE EXTENSION address_standardizer_data_us ;</codeblock></li>
             <codeph>POSTGIS_ENABLE_OUTDB_RASTERS</codeph>,
             <codeph>POSTGIS_GDAL_ENABLED_DRIVERS</codeph>. The environment variables are removed
           when you uninstall the PostGIS extension package.</p>
+        <note type="warning">Removing PostGIS support from a database drops PostGIS database objects
+          from the database without warning. Users accessing PostGIS objects might interfere with
+          the dropping of PostGIS objects. See <xref href="#topic_bgz_vcl_r1b/postgis_note"
+            format="dita">Notes</xref>.</note>
         <section id="drop_postgis_cmd">
           <title>Using the DROP EXTENSION Command</title>
           <p>Depending on the extensions you enabled for PostGIS, drop support for the extensions in
@@ -297,6 +305,31 @@ export POSTGIS_GDAL_ENABLED_DRIVERS=DISABLE_ALL</codeblock>
             command restarts Greenplum Database.</p>
           <codeblock>gpstop -ra</codeblock>
         </section>
+        <section id="postgis_note">
+          <title>Notes</title>
+          <p>Removing PostGIS support from a database drops PostGIS objects from the database.
+            Dropping the PostGIS objects cascades to objects that reference the PostGIS objects.
+            Before removing PostGIS support, ensure that no users are accessing the database. Users
+            accessing PostGIS objects might interfere with dropping PostGIS objects.</p>
+          <p>For example, this <codeph>CREATE TABLE</codeph> command creates a table with column
+              <codeph>b</codeph> that is defined with the PostGIS <codeph>geometry</codeph> data
+            type.<codeblock># CREATE TABLE test(a int, b geometry) DISTRIBUTED RANDOMLY;</codeblock></p>
+          <p>This is the table definition in a database with PostGIS
+            enabled.<codeblock># \d test
+ Table "public.test"
+ Column |   Type   | Modifiers
+--------+----------+-----------
+ a      | integer  |
+ b      | geometry |
+Distributed randomly</codeblock></p>
+          <p>This is the table definition in a database after PostGIS support has been
+            removed.<codeblock># \d test
+  Table "public.test"
+ Column |  Type   | Modifiers
+--------+---------+-----------
+ a      | integer |
+Distributed randomly</codeblock></p>
+        </section>
       </body>
     </topic>
   </topic>

gpdb-doc/dita/analytics/postgis-upgrade.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
+<topic id="topic_khf_ltc_vbb">
+  <title>Upgrading PostGIS 2.1.5 or 2.5.4</title>
+  <body>
+    <p>For Greenplum Database 6, you can upgrade from PostGIS 2.1.5 to 2.5.4, or from a PostGIS
+      2.5.4 package to a newer PostGIS 2.5.4 package.</p>
+    <ul id="ul_eyk_db3_kmb">
+      <li><xref href="#topic_zgw_v5x_3mb" format="dita"/></li>
+      <li><xref href="#topic_k4x_dp3_kmb" format="dita"/></li>
+      <li><xref href="#topic_yzz_l3h_kmb" format="dita"/></li>
+    </ul>
+    <note>For Greenplum Database 6, you can upgrade from PostGIS 2.1.5 to 2.5.4, or from a PostGIS
+      2.5.4 package to a newer PostGIS 2.5.4 package using the <codeph>postgis_manager.sh</codeph>
+      script described in the upgrade instructions. <p>Upgrading PostGIS using the
+          <codeph>postgis_manager.sh</codeph> script does not require you to remove PostGIS support
+        and re-enable it. </p><p>Removing PostGIS support from a database drops PostGIS database
+        objects from the database without warning. Users accessing PostGIS objects might interfere
+        with the dropping of PostGIS objects. See the Notes section in <xref
+          href="postGIS.xml#topic_bgz_vcl_r1b"/>.</p></note>
+  </body>
+  <topic id="topic_zgw_v5x_3mb">
+    <title>Upgrading from PostGIS 2.1.5 to the PostGIS 2.5.4 pivotal.3 Package</title>
+    <body>
+      <p>A PostGIS 2.5.4 <codeph>pivotal.3</codeph> package contains PostGIS 2.5.4. Also, the
+        PostGIS 2.5.4 <codeph>pivotal.3</codeph> package supports using the <codeph>CREATE
+          EXTENSION</codeph> command and the <codeph>DROP EXTENSION</codeph> command to enable and
+        remove PostGIS support in a database. See <xref href="#topic_hm5_3zk_jmb" format="dita"
+        />.</p>
+      <p>After upgrading the Greenplum PostGIS package, you can remove the PostGIS 2.1.5 package
+          (<codeph>gppkg</codeph>) from the Greenplum system. See <xref href="#topic_unj_v5n_kmb"
+          format="dita"/>.</p>
+      <ol id="ol_mnr_r1k_nmb">
+        <li>Confirm you have a PostGIS 2.1.5 package such as
+            <codeph>postgis-2.1.5+pivotal.1</codeph> installed in a Greenplum Database system. See
+            <xref href="#topic_yzz_l3h_kmb" format="dita"/>.</li>
+        <li dir="ltr">Install the PostGIS 2.5.4 package into the Greenplum Database system with the
+            <codeph>gppkg</codeph>
+            utility.<codeblock dir="ltr">gppkg -i postgis-2.5.4+pivotal.3.build.1-gp6-rhel7-x86_64.gppkg</codeblock><p>Run
+            the <codeph>gppkg -q --all</codeph> command to verify the updated package version is
+            installed in the Greenplum Database system. </p></li>
+        <li dir="ltr">For all databases with PostGIS enabled, run the PostGIS 2.5.4
+            <codeph>postgis_manager.sh</codeph> script in the directory
+            <codeph>$GPHOME/share/postgresql/contrib/postgis-2.5</codeph> to upgrade PostGIS in that
+          database. This command upgrades PostGIS that is enabled in the database
+            <codeph>mytest</codeph> in the Greenplum Database
+          system.<codeblock>$GPHOME/share/postgresql/contrib/postgis-2.5/postgis_manager.sh mytest upgrade</codeblock></li>
+        <li>After running the script, you can verify that PostGIS 2.5.4 is installed and enabled as
+          an extension in a database with this
+          query.<codeblock># SELECT * FROM pg_available_extensions WHERE name = 'postgis' ;</codeblock></li>
+        <li dir="ltr">You can validate that PostGIS 2.5 is enabled in the database with the
+            <codeph>postgis_version()</codeph> function.</li>
+      </ol>
+      <p>After you have completed the upgrade to PostGIS 2.5.4 <codeph>pivotal.3</codeph> for the
+        Greenplum system and all the databases with PostGIS enabled, you enable PostGIS in a new
+        database with the <codeph>CREATE EXTENSION postgis</codeph> command. To remove PostGIS
+        support, use the <codeph>DROP EXTENSION postgis CASCADE</codeph> command.</p>
+    </body>
+    <topic id="topic_unj_v5n_kmb">
+      <title>Removing the PostGIS 2.1.5 package</title>
+      <body>
+        <p>After upgrading the databases in the Greenplum Database system, you can remove the
+          PostGIS 2.1.5 package from the system. This command removes the
+            <codeph>postgis-2.1.5+pivotal.2</codeph> package from a Greenplum Database
+          system.<codeblock dir="ltr">gppkg -r postgis-2.1.5+pivotal.2</codeblock></p>
+        <p>Run the <codeph>gppkg -q --all</codeph> command to list the installed Greenplum
+          packages.</p>
+      </body>
+    </topic>
+  </topic>
+  <topic id="topic_k4x_dp3_kmb">
+    <title>Upgrade a PostGIS 2.5.4 Package from pivotal.1 or pivotal.2 to pivotal.3</title>
+    <body>
+      <p>You an upgade the installed PostGIS 2.5.4 package from <codeph>pivotal.1</codeph> or
+          <codeph>pivotal.2</codeph> to <codeph>pivotal.3</codeph> (a minor release upgrade). The
+        upgrade updates the PostGIS 2.5.4 package to the minor release (<codeph>pivotal.3</codeph>)
+        that uses the same PostGIS version (2.5.4).</p>
+      <p>The <codeph>pivotal.3</codeph> minor release supports using the <codeph>CREATE
+          EXTENSION</codeph> command and the <codeph>DROP EXTENSION</codeph> command to enable and
+        remove PostGIS support in a database. See <xref href="#topic_hm5_3zk_jmb" format="dita"
+        />.</p>
+      <ol id="ol_kd3_dck_nmb">
+        <li>Confirm you have a PostGIS 2.5.4 package <codeph>postgis-2.5.4+<b>pivotal.1</b></codeph>
+          or <codeph>postgis-2.5.4+<b>pivotal.2</b></codeph> installed in a Greenplum Database
+          system. See <xref href="#topic_yzz_l3h_kmb" format="dita"/>.</li>
+        <li>Upgrade the PostGIS package in the Greenplum Database system using the
+            <codeph>gppkg</codeph> option <codeph>-u</codeph>. The command updates the package to
+          the <codeph>postgis-2.5.4+pivotal.3.build.1</codeph>
+          package.<codeblock dir="ltr">gppkg -u postgis-2.5.4+pivotal.3.build.1-gp6-rhel7-x86_64.gppkg</codeblock></li>
+        <li>Run the <codeph>gppkg -q --all</codeph> command to verify the updated package version is
+          installed in the Greenplum Database system. </li>
+        <li dir="ltr">For all databases with PostGIS enabled, upgrade PostGIS with the PostGIS 2.5.4
+            <codeph>postgis_manager.sh</codeph> script that is in the directory
+            <codeph>$GPHOME/share/postgresql/contrib/postgis-2.5</codeph> to upgrade PostGIS in that
+          database. This command upgrades PostGIS that is enabled in the database
+            <codeph>mytest</codeph> in the Greenplum Database
+          system.<codeblock>$GPHOME/share/postgresql/contrib/postgis-2.5/postgis_manager.sh mytest upgrade</codeblock></li>
+      </ol>
+      <p>After you have completed the upgrade to PostGIS 2.5.4 <codeph>pivotal.3</codeph> for the
+        Greenplum system and all the databases with PostGIS enabled, you enable PostGIS in a new
+        database with the <codeph>CREATE EXTENSION postgis</codeph> command. To remove PostGIS
+        support, use the <codeph>DROP EXTENSION postgis CASCADE</codeph> command.</p>
+    </body>
+  </topic>
+  <topic id="topic_yzz_l3h_kmb">
+    <title>Checking the PostGIS Version</title>
+    <body>
+      <p>When upgrading PostGIS you must check the version of the Greenplum PostGIS package
+        installed on the Greenplum Database system and the version of PostGIS enabled in the
+        database. <ul id="ul_s1t_x54_kmb">
+          <li>Check the installed PostGIS package version with the <codeph>gppkg</codeph> utility.
+            This command lists all installed Greenplum
+            packages.<codeblock>gppkg -q --all</codeblock></li>
+          <li>Check the enabled PostGIS version in a database with the
+              <codeph>postgis_version()</codeph> function. This <codeph>psql</codeph> command
+            displays the version PostGIS that is enabled for the database <codeph>testdb</codeph>.
+              <codeblock>psql -d testdb -c 'select postgis_version();'</codeblock><p>If PostGIS is
+              not enabled for the database, Greenplum returns a <codeph>function does not
+                exist</codeph> error.</p></li>
+          <li>For the Geenplum PostGIS package <codeph>postgis-2.5.4+pivotal.2</codeph> and later,
+            you can display the PostGIS extension version and state in a database with this query.
+              <codeblock># SELECT * FROM pg_available_extensions WHERE name = 'postgis' ;</codeblock><p>The
+              query displays the version whether the extension is installed and enabled in a
+              database. If the PostGIS package is not installed, no rows are returned.</p></li>
+        </ul></p>
+    </body>
+  </topic>
+  <topic id="topic_hm5_3zk_jmb">
+    <title>Notes</title>
+    <body>
+      <p>Starting with the Greenplum <codeph>postgis-2.5.4+pivotal.2</codeph> package, you enable
+        support for PostGIS in a database with the <codeph>CREATE EXTENSION</codeph> command. For
+        previous PostGIS 2.5.4 packages and all PostGIS 2.1.5 packages, you use an SQL script.</p>
+    </body>
+  </topic>
+</topic>