More documentation update for GRANT ... WITH SET OPTION.

Update the reference pages for various ALTER commands that
mentioned that you must be a member of role that will be the
new owner to instead say that you must be able to SET ROLE
to the new owner. Update ddl.sgml's generate statement on this
topic along similar lines.

Likewise, update CREATE SCHEMA and CREATE DATABASE, which
have options to specify who will own the new objects, to say
that you must be able to SET ROLE to the role that will own
them.

Finally, update the documentation for the GRANT statement
itself with some general principles about how the SET option
works and how it can be used.

Patch by me, reviewed (but not fully endorsed) by Noah Misch.

Discussion: http://postgr.es/m/CA+TgmoZk6VB3DQ83+DO5P_HP=M9PQAh1yj-KgeV30uKefVaWDg@mail.gmail.com

doc/src/sgml/ddl.sgml

@@ -1741,8 +1741,8 @@ ALTER TABLE products RENAME TO items;
 ALTER TABLE <replaceable>table_name</replaceable> OWNER TO <replaceable>new_owner</replaceable>;
 </programlisting>
    Superusers can always do this; ordinary roles can only do it if they are
-   both the current owner of the object (or a member of the owning role) and
-   a member of the new owning role.
+   both the current owner of the object (or inherit the privileges of the
+   owning role) and able to <literal>SET ROLE</literal> to the new owning role.
   </para>
 
   <para>

doc/src/sgml/ref/alter_aggregate.sgml

@@ -46,9 +46,10 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu
    You must own the aggregate function to use <command>ALTER AGGREGATE</command>.
    To change the schema of an aggregate function, you must also have
    <literal>CREATE</literal> privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the aggregate function's schema.  (These restrictions enforce that altering
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the aggregate function's schema.
+   (These restrictions enforce that altering
    the owner doesn't do anything you couldn't do by dropping and recreating
    the aggregate function.  However, a superuser can alter ownership of any
    aggregate function anyway.)

doc/src/sgml/ref/alter_collation.sgml

@@ -39,9 +39,10 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche
 
   <para>
    You must own the collation to use <command>ALTER COLLATION</command>.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the collation's schema.  (These restrictions enforce that altering the
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the collation's schema.
+   (These restrictions enforce that altering the
    owner doesn't do anything you couldn't do by dropping and recreating the
    collation. However, a superuser can alter ownership of any collation
    anyway.)

doc/src/sgml/ref/alter_conversion.sgml

@@ -37,9 +37,10 @@ ALTER CONVERSION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sch
 
   <para>
    You must own the conversion to use <command>ALTER CONVERSION</command>.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the conversion's schema.  (These restrictions enforce that altering the
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the conversion's schema.
+   (These restrictions enforce that altering the
    owner doesn't do anything you couldn't do by dropping and recreating the
    conversion. However, a superuser can alter ownership of any conversion
    anyway.)

doc/src/sgml/ref/alter_database.sgml

@@ -68,8 +68,8 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL
 
   <para>
    The third form changes the owner of the database.
-   To alter the owner, you must own the database and also be a direct or
-   indirect member of the new owning role, and you must have the
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and you must have the
    <literal>CREATEDB</literal> privilege.
    (Note that superusers have all these privileges automatically.)
   </para>

doc/src/sgml/ref/alter_domain.sgml

@@ -157,9 +157,9 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable>
    You must own the domain to use <command>ALTER DOMAIN</command>.
    To change the schema of a domain, you must also have
    <literal>CREATE</literal> privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the domain's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal> privilege
+   on the domain's schema.  (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the domain.
    However, a superuser can alter ownership of any domain anyway.)
   </para>

doc/src/sgml/ref/alter_foreign_table.sgml

@@ -320,9 +320,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab
    You must own the table to use <command>ALTER FOREIGN TABLE</command>.
    To change the schema of a foreign table, you must also have
    <literal>CREATE</literal> privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the table's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal> privilege
+   on the table's schema.  (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the table.
    However, a superuser can alter ownership of any table anyway.)
    To add a column or alter a column type, you must also

doc/src/sgml/ref/alter_function.sgml

@@ -60,9 +60,9 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param
   <para>
    You must own the function to use <command>ALTER FUNCTION</command>.
    To change a function's schema, you must also have <literal>CREATE</literal>
-   privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
+   privilege on the new schema.  To alter the owner, you must be able to
+   <literal>SET ROLE</literal> to the new owning role, and that role must
+   have <literal>CREATE</literal> privilege on
    the function's schema.  (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the function.
    However, a superuser can alter ownership of any function anyway.)

doc/src/sgml/ref/alter_large_object.sgml

@@ -35,8 +35,9 @@ ALTER LARGE OBJECT <replaceable class="parameter">large_object_oid</replaceable>
 
   <para>
    You must own the large object to use <command>ALTER LARGE OBJECT</command>.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role.  (However, a superuser can alter any large object anyway.)
+   To alter the owner, you must also be able to <literal>SET ROLE</literal> to
+   the new owning role.
+   (However, a superuser can alter any large object anyway.)
    Currently, the only functionality is to assign a new owner, so both
    restrictions always apply.
   </para>

doc/src/sgml/ref/alter_materialized_view.sgml

@@ -63,9 +63,10 @@ ALTER MATERIALIZED VIEW ALL IN TABLESPACE <replaceable class="parameter">name</r
    You must own the materialized view to use <command>ALTER MATERIALIZED
    VIEW</command>.  To change a materialized view's schema, you must also have
    <literal>CREATE</literal> privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the materialized view's schema.  (These restrictions enforce that altering
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the materialized view's schema.
+   (These restrictions enforce that altering
    the owner doesn't do anything you couldn't do by dropping and recreating the
    materialized view.  However, a superuser can alter ownership of any view
    anyway.)

doc/src/sgml/ref/alter_opclass.sgml

@@ -42,9 +42,10 @@ ALTER OPERATOR CLASS <replaceable>name</replaceable> USING <replaceable class="p
 
   <para>
    You must own the operator class to use <command>ALTER OPERATOR CLASS</command>.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the operator class's schema.  (These restrictions enforce that altering the
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the operator class's schema.
+   (These restrictions enforce that altering the
    owner doesn't do anything you couldn't do by dropping and recreating the
    operator class.  However, a superuser can alter ownership of any operator
    class anyway.)

doc/src/sgml/ref/alter_operator.sgml

@@ -44,9 +44,10 @@ ALTER OPERATOR <replaceable>name</replaceable> ( { <replaceable>left_type</repla
 
   <para>
    You must own the operator to use <command>ALTER OPERATOR</command>.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the operator's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the operator's schema.
+   (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the operator.
    However, a superuser can alter ownership of any operator anyway.)
   </para>

doc/src/sgml/ref/alter_procedure.sgml

@@ -54,9 +54,10 @@ ALTER PROCEDURE <replaceable>name</replaceable> [ ( [ [ <replaceable class="para
    You must own the procedure to use <command>ALTER PROCEDURE</command>.
    To change a procedure's schema, you must also have <literal>CREATE</literal>
    privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the procedure's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the procedure's schema.
+   (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the procedure.
    However, a superuser can alter ownership of any procedure anyway.)
   </para>

doc/src/sgml/ref/alter_publication.sgml

@@ -75,10 +75,12 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
    Adding a table to a publication additionally requires owning that table.
    The <literal>ADD TABLES IN SCHEMA</literal> and
    <literal>SET TABLES IN SCHEMA</literal> to a publication requires the
-   invoking user to be a superuser.  To alter the owner, you must also be a
-   direct or indirect member of the new owning role. The new owner must have
-   <literal>CREATE</literal> privilege on the database.  Also, the new owner
-   of a <literal>FOR ALL TABLES</literal> or <literal>FOR TABLES IN SCHEMA</literal>
+   invoking user to be a superuser.
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the database.
+   Also, the new owner of a <literal>FOR ALL TABLES</literal> or
+   <literal>FOR TABLES IN SCHEMA</literal>
    publication must be a superuser. However, a superuser can
    change the ownership of a publication regardless of these restrictions.
   </para>

doc/src/sgml/ref/alter_schema.sgml

@@ -37,8 +37,8 @@ ALTER SCHEMA <replaceable>name</replaceable> OWNER TO { <replaceable>new_owner</
    You must own the schema to use <command>ALTER SCHEMA</command>.
    To rename a schema you must also have the
    <literal>CREATE</literal> privilege for the database.
-   To alter the owner, you must also be a direct or
-   indirect member of the new owning role, and you must have the
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have the
    <literal>CREATE</literal> privilege for the database.
    (Note that superusers have all these privileges automatically.)
   </para>

doc/src/sgml/ref/alter_sequence.sgml

@@ -51,9 +51,10 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S
    You must own the sequence to use <command>ALTER SEQUENCE</command>.
    To change a sequence's schema, you must also have <literal>CREATE</literal>
    privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the sequence's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the sequence's schema.
+   (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the sequence.
    However, a superuser can alter ownership of any sequence anyway.)
   </para>

doc/src/sgml/ref/alter_server.sgml

@@ -40,8 +40,8 @@ ALTER SERVER <replaceable class="parameter">name</replaceable> RENAME TO <replac
 
   <para>
    To alter the server you must be the owner of the server.
-   Additionally to alter the owner, you must own the server and also
-   be a direct or indirect member of the new owning role, and you must
+   Additionally to alter the owner, you must be able to
+   <literal>SET ROLE</literal> to the new owning role, and you must
    have <literal>USAGE</literal> privilege on the server's foreign-data
    wrapper.  (Note that superusers satisfy all these criteria
    automatically.)

doc/src/sgml/ref/alter_statistics.sgml

@@ -43,9 +43,10 @@ ALTER STATISTICS <replaceable class="parameter">name</replaceable> SET STATISTIC
    You must own the statistics object to use <command>ALTER STATISTICS</command>.
    To change a statistics object's schema, you must also
    have <literal>CREATE</literal> privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the statistics object's schema.  (These restrictions enforce that altering
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the statistics object's schema.
+   (These restrictions enforce that altering
    the owner doesn't do anything you couldn't do by dropping and recreating
    the statistics object.  However, a superuser can alter ownership of any
    statistics object anyway.)

doc/src/sgml/ref/alter_subscription.sgml

@@ -46,7 +46,7 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO <
 
   <para>
    You must own the subscription to use <command>ALTER SUBSCRIPTION</command>.
-   To alter the owner, you must also be a direct or indirect member of the
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
    new owning role.  The new owner has to be a superuser.
    (Currently, all subscription owners must be superusers, so the owner checks
    will be bypassed in practice.  But this might change in the future.)

doc/src/sgml/ref/alter_table.sgml

@@ -1106,9 +1106,10 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
    To add the table as a new child of a parent table, you must own the parent
    table as well.  Also, to attach a table as a new partition of the table,
    you must own the table being attached.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the table's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the table's schema.
+   (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the table.
    However, a superuser can alter ownership of any table anyway.)
    To add a column or alter a column type or use the <literal>OF</literal>

doc/src/sgml/ref/alter_tablespace.sgml

@@ -38,8 +38,8 @@ ALTER TABLESPACE <replaceable>name</replaceable> RESET ( <replaceable class="par
 
   <para>
    You must own the tablespace to change the definition of a tablespace.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role.
+   To alter the owner, you must also be able to <literal>SET ROLE</literal>
+   to the new owning role.
    (Note that superusers have these privileges automatically.)
   </para>
 

doc/src/sgml/ref/alter_type.sgml

@@ -246,9 +246,10 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> SET ( <replaceable
    You must own the type to use <command>ALTER TYPE</command>.
    To change the schema of a type, you must also have
    <literal>CREATE</literal> privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the type's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the type's schema.
+   (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the type.
    However, a superuser can alter ownership of any type anyway.)
    To add an attribute or alter an attribute type, you must also

doc/src/sgml/ref/alter_view.sgml

@@ -45,9 +45,10 @@ ALTER VIEW [ IF EXISTS ] <replaceable class="parameter">name</replaceable> RESET
    You must own the view to use <command>ALTER VIEW</command>.
    To change a view's schema, you must also have <literal>CREATE</literal>
    privilege on the new schema.
-   To alter the owner, you must also be a direct or indirect member of the new
-   owning role, and that role must have <literal>CREATE</literal> privilege on
-   the view's schema.  (These restrictions enforce that altering the owner
+   To alter the owner, you must be able to <literal>SET ROLE</literal> to the
+   new owning role, and that role must have <literal>CREATE</literal>
+   privilege on the view's schema.
+   (These restrictions enforce that altering the owner
    doesn't do anything you couldn't do by dropping and recreating the view.
    However, a superuser can alter ownership of any view anyway.)
   </para>

doc/src/sgml/ref/create_database.sgml

@@ -89,8 +89,8 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable>
         The role name of the user who will own the new database,
         or <literal>DEFAULT</literal> to use the default (namely, the
         user executing the command).  To create a database owned by another
-        role, you must be a direct or indirect member of that role,
-        or be a superuser.
+        role, you must must be able to <literal>SET ROLE</literal> to that
+        role.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/create_schema.sgml

@@ -89,8 +89,8 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp
        <para>
         The role name of the user who will own the new schema.  If omitted,
         defaults to the user executing the command.  To create a schema
-        owned by another role, you must be a direct or indirect member of
-        that role, or be a superuser.
+        owned by another role, you must must be able to
+        <literal>SET ROLE</literal> to that role.
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/grant.sgml

@@ -298,6 +298,20 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
    This option defaults to <literal>TRUE</literal>.
   </para>
 
+  <para>
+   To create an object owned by another role or give ownership of an existing
+   object to another role, you must have the ability to <literal>SET
+   ROLE</literal> to that role; otherwise, commands such as <literal>ALTER
+   ... OWNER TO</literal> or <literal>CREATE DATABASE ... OWNER</literal>
+   will fail.  However, a user who inherits the privileges of a role but does
+   not have the ability to <literal>SET ROLE</literal> to that role may be
+   able to obtain full access to the role by manipulating existing objects
+   owned by that role (e.g. they could redefine an existing function to act
+   as a Trojan horse).  Therefore, if a role's privileges are to be inherited
+   but should not be accessible via <literal>SET ROLE</literal>, it should not
+   own any SQL objects.
+  </para>
+
   <para>
    If <literal>GRANTED BY</literal> is specified, the grant is recorded as
    having been done by the specified role. A user can only attribute a grant