Doc: clarify locking requirements for ALTER TABLE ADD FOREIGN KEY.

The docs explained that a SHARE ROW EXCLUSIVE lock is needed on the
referenced table, but failed to say the same about the table being
altered.  Since the page says that ACCESS EXCLUSIVE lock is taken
unless otherwise stated, this left readers with the wrong conclusion.

Discussion: https://postgr.es/m/834603375.3470346.1586482852542@mail.yahoo.com

diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index e4861964774210fc4f3b36faf309f795ccae9a3b..7595e609b5b4be059ecca59c8344a2f05188c508 100644 (file)
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -142,9 +142,9 @@ WITH ( MODULUS numeric_literal, REM
   
    ALTER TABLE changes the definition of an existing table.
    There are several subforms described below. Note that the lock level required
-   may differ for each subform. An ACCESS EXCLUSIVE lock is held
-   unless explicitly noted. When multiple subcommands are listed, the lock
-   held will be the strictest one required from any subcommand.
+   may differ for each subform. An ACCESS EXCLUSIVE lock is
+   acquired unless explicitly noted. When multiple subcommands are given, the
+   lock acquired will be the strictest one required by any subcommand.
 
   
    
@@ -387,8 +387,8 @@ WITH ( MODULUS numeric_literal, REM
     ADD table_constraint [ NOT VALID ]
     
      
-      This form adds a new constraint to a table using the same syntax as
-      , plus the option NOT
+      This form adds a new constraint to a table using the same constraint
+      syntax as , plus the option NOT
       VALID, which is currently only allowed for foreign key
       and CHECK constraints.
      
@@ -411,9 +411,14 @@ WITH ( MODULUS numeric_literal, REM
      
 
      
-      Addition of a foreign key constraint requires a
-      SHARE ROW EXCLUSIVE lock on the referenced table,
-      in addition to the lock on the table receiving the constraint.
+      Although most forms of ADD
+      table_constraint
+      require an ACCESS EXCLUSIVE lock, ADD
+      FOREIGN KEY requires only a SHARE ROW
+      EXCLUSIVE lock.  Note that ADD FOREIGN KEY
+      also acquires a SHARE ROW EXCLUSIVE lock on the
+      referenced table, in addition to the lock on the table on which the
+      constraint is declared.