Some small editorialization on the description of CREATE INDEX

CONCURRENTLY.  Greg Stark, some further tweaks by me.

diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index e49996a8119d2c0d101aee97dbe0c91b66ccc6e8..065b186fca292fd48d01d499680100c00e500b57 100644 (file)
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -93,8 +93,9 @@ CREATE INDEX test1_id_index ON test1 (id);
   <para>
    Creating an index on a large table can take a long time.  By default,
    <productname>PostgreSQL</productname> allows reads (selects) to occur
-   on the table in parallel with index creation, but writes (inserts,
+   on the table in parallel with creation of an index, but writes (inserts,
    updates, deletes) are blocked until the index build is finished.
+   In production environments this is often unacceptable.
    It is possible to allow writes to occur in parallel with index
    creation, but there are several caveats to be aware of &mdash;
    for more information see <xref linkend="SQL-CREATEINDEX-CONCURRENTLY"

diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 48c69bda542da7db65db138b8cafde465fb6fbae..06e25ed96821bb7b300515f9aa204ed0dddcdda1 100644 (file)
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -264,22 +264,19 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] <replaceable class="parameter">name</re
    </indexterm>
 
    <para>
-    Creating an index for a large table can be a long operation. In large data
-    warehousing applications it can easily take hours or even days to build
-    indexes. It's important to understand the impact creating indexes has on a
-    system.
-   </para>
-
-   <para>
+    Creating an index can interfere with regular operation of a database.
     Normally <productname>PostgreSQL</> locks the table to be indexed against
     writes and performs the entire index build with a single scan of the
     table. Other transactions can still read the table, but if they try to
     insert, update, or delete rows in the table they will block until the
-    index build is finished.
+    index build is finished. This could have a severe effect if the system is
+    a live production database. Large tables can take many hours to be
+    indexed, and even for smaller tables, an index build can lock out writers
+    for periods that are unacceptably long for a production system.
    </para>
 
    <para>
-    <productname>PostgreSQL</> also supports building indexes without locking
+    <productname>PostgreSQL</> supports building indexes without locking
     out writes.  This method is invoked by specifying the
     <literal>CONCURRENTLY</> option of <command>CREATE INDEX</>.
     When this option is used,