From 8b0d5949a81e1ffe456355b471c0a491fce52879 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Wed, 28 May 2008 00:46:12 +0000
Subject: [PATCH] Improve GRANT documentation to point out that UPDATE and
 DELETE typically require SELECT privilege as well, since you normally need to
 read existing column values within such commands.  This behavior is according
 to spec, but we'd never documented it before.  Per gripe from Volkan Yazici.

---
 doc/src/sgml/ref/grant.sgml | 42 ++++++++++++++++++++++++-------------
 1 file changed, 28 insertions(+), 14 deletions(-)

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index a43de6356d9..5aa40cb933d 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.37 2003/10/31 20:00:48 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/grant.sgml,v 1.37.2.1 2008/05/28 00:46:12 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -104,10 +104,15 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>SELECT</term>
      <listitem>
       <para>
-       Allows <xref linkend="sql-select" endterm="sql-select-title"> from any column of the
-       specified table, view, or sequence.  Also allows the use of
-       <xref linkend="sql-copy" endterm="sql-copy-title"> TO.  For sequences, this
-       privilege also allows the use of the <function>currval</function> function.
+       Allows <xref linkend="sql-select" endterm="sql-select-title"> from
+       any column of the specified table, view, or sequence.
+       Also allows the use of
+       <xref linkend="sql-copy" endterm="sql-copy-title"> TO.
+       This privilege is also needed to reference existing column values in
+       <xref linkend="sql-update" endterm="sql-update-title"> or
+       <xref linkend="sql-delete" endterm="sql-delete-title">.
+       For sequences, this privilege also allows the use of the
+       <function>currval</function> function.
       </para>
      </listitem>
     </varlistentry>
@@ -116,8 +121,9 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>INSERT</term>
      <listitem>
       <para>
-       Allows <xref linkend="sql-insert" endterm="sql-insert-title"> of a new row into the
-       specified table.  Also allows <xref linkend="sql-copy" endterm="sql-copy-title"> FROM.
+       Allows <xref linkend="sql-insert" endterm="sql-insert-title"> of a new
+       row into the specified table.
+       Also allows <xref linkend="sql-copy" endterm="sql-copy-title"> FROM.
       </para>
      </listitem>
     </varlistentry>
@@ -126,10 +132,15 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>UPDATE</term>
      <listitem>
       <para>
-       Allows <xref linkend="sql-update" endterm="sql-update-title"> of any column of the
-       specified table.  <literal>SELECT ... FOR UPDATE</literal>
-       also requires this privilege (besides the
-       <literal>SELECT</literal> privilege).  For sequences, this
+       Allows <xref linkend="sql-update" endterm="sql-update-title"> of any
+       column of the specified table.
+       (In practice, any nontrivial <command>UPDATE</> command will require
+       <literal>SELECT</> privilege as well, since it must reference table
+       columns to determine which rows to update, and/or to compute new
+       values for columns.)
+       <literal>SELECT ... FOR UPDATE</literal>
+       also requires this privilege, in addition to the
+       <literal>SELECT</literal> privilege.  For sequences, this
        privilege allows the use of the <function>nextval</function> and
        <function>setval</function> functions.
       </para>
@@ -140,8 +151,11 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>DELETE</term>
      <listitem>
       <para>
-       Allows <xref linkend="sql-delete" endterm="sql-delete-title"> of a row from the
-       specified table.
+       Allows <xref linkend="sql-delete" endterm="sql-delete-title"> of a row
+       from the specified table.
+       (In practice, any nontrivial <command>DELETE</> command will require
+       <literal>SELECT</> privilege as well, since it must reference table
+       columns to determine which rows to delete.)
       </para>
      </listitem>
     </varlistentry>
@@ -196,7 +210,7 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
      <term>TEMP</term>
      <listitem>
       <para>
-       Allows temporary tables to be created while using the database.
+       Allows temporary tables to be created while using the specified database.
       </para>
      </listitem>
     </varlistentry>