From b1cbd2b573edc690bdb75cf25fe31037c8126b2f Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Thu, 30 Jan 2014 12:14:24 -0500
Subject: [PATCH] docs:  add mention of index swapping

Backpatch to 9.3

Greg Smith
---
 doc/src/sgml/maintenance.sgml      | 22 ++++++++++++++++++++--
 doc/src/sgml/ref/create_index.sgml |  2 +-
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 324ed0e760..339891e8a0 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -748,8 +748,9 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
 
   <para>
    In some situations it is worthwhile to rebuild indexes periodically
-   with the <xref linkend="sql-reindex">
-   command.
+   with the <xref linkend="sql-reindex"> command or a series of individual
+   rebuilding steps.
+
   </para>
 
   <para>
@@ -775,6 +776,23 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
    (This consideration does not apply to non-B-tree indexes.)  It
    might be worthwhile to reindex periodically just to improve access speed.
   </para>
+
+  <para>
+   <xref linkend="sql-reindex"> can be used safely and easily in all cases.
+   But since the command requires an exclusive table lock, it is
+   often preferable to execute an index rebuild with a sequence of
+   creation and replacement steps.  Index types that support
+   <xref linkend="sql-createindex"> with the <literal>CONCURRENTLY</>
+   option can instead be recreated that way. If that is successful and the
+   resulting index is valid, the original index can then be replaced by
+   the newly built one using a combination of <xref linkend="sql-alterindex">
+   and <xref linkend="sql-dropindex">. When an index is used to enforce
+   uniqueness or other constraints, <xref linkend="sql-altertable"> might
+   be necessary to swap the existing constraint with one enforced by
+   the new index. Review this alternate multi-step rebuild approach
+   carefully before using it as there are limitations on which
+   indexes can be reindexed this way, and errors must be handled.
+  </para>
  </sect1>
 
 
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 01faa3afcf..9a6a683e12 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -405,7 +405,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ <replaceable class="parameter">name</
    </para>
 
    <para>
-    If a problem arises while scanning the table, such as a
+    If a problem arises while scanning the table, such as a deadlock or a
     uniqueness violation in a unique index, the <command>CREATE INDEX</>
     command will fail but leave behind an <quote>invalid</> index. This index
     will be ignored for querying purposes because it might be incomplete;
-- 
2.40.0