From b9d40a6cd6e198e635d177a6e47db5c62cbccdc9 Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Wed, 11 Jan 2023 14:57:30 -0500
Subject: [PATCH v2] 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.
---
 doc/src/sgml/ddl.sgml                         |  4 ++--
 doc/src/sgml/ref/alter_aggregate.sgml         |  7 ++++---
 doc/src/sgml/ref/alter_collation.sgml         |  7 ++++---
 doc/src/sgml/ref/alter_conversion.sgml        |  7 ++++---
 doc/src/sgml/ref/alter_database.sgml          |  4 ++--
 doc/src/sgml/ref/alter_domain.sgml            |  6 +++---
 doc/src/sgml/ref/alter_foreign_table.sgml     |  6 +++---
 doc/src/sgml/ref/alter_function.sgml          |  6 +++---
 doc/src/sgml/ref/alter_large_object.sgml      |  5 +++--
 doc/src/sgml/ref/alter_materialized_view.sgml |  7 ++++---
 doc/src/sgml/ref/alter_opclass.sgml           |  7 ++++---
 doc/src/sgml/ref/alter_operator.sgml          |  7 ++++---
 doc/src/sgml/ref/alter_procedure.sgml         |  7 ++++---
 doc/src/sgml/ref/alter_publication.sgml       | 10 ++++++----
 doc/src/sgml/ref/alter_schema.sgml            |  4 ++--
 doc/src/sgml/ref/alter_sequence.sgml          |  7 ++++---
 doc/src/sgml/ref/alter_server.sgml            |  4 ++--
 doc/src/sgml/ref/alter_statistics.sgml        |  7 ++++---
 doc/src/sgml/ref/alter_subscription.sgml      |  4 ++--
 doc/src/sgml/ref/alter_table.sgml             |  7 ++++---
 doc/src/sgml/ref/alter_tablespace.sgml        |  4 ++--
 doc/src/sgml/ref/alter_type.sgml              |  7 ++++---
 doc/src/sgml/ref/alter_view.sgml              |  7 ++++---
 doc/src/sgml/ref/create_database.sgml         |  4 ++--
 doc/src/sgml/ref/create_schema.sgml           |  4 ++--
 doc/src/sgml/ref/grant.sgml                   | 14 ++++++++++++++
 26 files changed, 96 insertions(+), 67 deletions(-)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 4b219435d4..0213db103a 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1714,8 +1714,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>
diff --git a/doc/src/sgml/ref/alter_aggregate.sgml b/doc/src/sgml/ref/alter_aggregate.sgml
index aee10a5ca2..d0a39ba7b5 100644
--- a/doc/src/sgml/ref/alter_aggregate.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml
index a8c831d728..a40a31442a 100644
--- a/doc/src/sgml/ref/alter_collation.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_conversion.sgml b/doc/src/sgml/ref/alter_conversion.sgml
index a128f20f3e..5c7cc978ee 100644
--- a/doc/src/sgml/ref/alter_conversion.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml
index 0962f32e13..5144e1f4ea 100644
--- a/doc/src/sgml/ref/alter_database.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_domain.sgml b/doc/src/sgml/ref/alter_domain.sgml
index 2db5372513..f6704d7557 100644
--- a/doc/src/sgml/ref/alter_domain.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml
index d056dc1bb1..0f4191713a 100644
--- a/doc/src/sgml/ref/alter_foreign_table.sgml
+++ b/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
diff --git a/doc/src/sgml/ref/alter_function.sgml b/doc/src/sgml/ref/alter_function.sgml
index 2e8e1162d8..8193b17f25 100644
--- a/doc/src/sgml/ref/alter_function.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_large_object.sgml b/doc/src/sgml/ref/alter_large_object.sgml
index 17ea1491ba..f427006f80 100644
--- a/doc/src/sgml/ref/alter_large_object.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_materialized_view.sgml b/doc/src/sgml/ref/alter_materialized_view.sgml
index 040ae53f98..da7ed04597 100644
--- a/doc/src/sgml/ref/alter_materialized_view.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_opclass.sgml b/doc/src/sgml/ref/alter_opclass.sgml
index b1db459b11..231597d629 100644
--- a/doc/src/sgml/ref/alter_opclass.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_operator.sgml b/doc/src/sgml/ref/alter_operator.sgml
index ad90c137f1..a4a1af564f 100644
--- a/doc/src/sgml/ref/alter_operator.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_procedure.sgml b/doc/src/sgml/ref/alter_procedure.sgml
index 20a623885f..a4737a3439 100644
--- a/doc/src/sgml/ref/alter_procedure.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index c84b11f47a..cd20868bca 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_schema.sgml b/doc/src/sgml/ref/alter_schema.sgml
index 04624c5a5e..b8ace0561f 100644
--- a/doc/src/sgml/ref/alter_schema.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml
index 148085d4f2..7be36cf466 100644
--- a/doc/src/sgml/ref/alter_sequence.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_server.sgml b/doc/src/sgml/ref/alter_server.sgml
index 186f38b5f8..467bf85589 100644
--- a/doc/src/sgml/ref/alter_server.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_statistics.sgml b/doc/src/sgml/ref/alter_statistics.sgml
index ce6cdf2bb1..73cc9e830d 100644
--- a/doc/src/sgml/ref/alter_statistics.sgml
+++ b/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.)
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index 1e8d72062b..ad93553a1d 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -46,8 +46,8 @@ 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
-   new owning role. The new owner has to be a superuser.
+   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.)
   </para>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 794e886f96..9aaa32a782 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/alter_tablespace.sgml b/doc/src/sgml/ref/alter_tablespace.sgml
index 6de80746d5..6ec863400d 100644
--- a/doc/src/sgml/ref/alter_tablespace.sgml
+++ b/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>
 
diff --git a/doc/src/sgml/ref/alter_type.sgml b/doc/src/sgml/ref/alter_type.sgml
index 146065144f..025a3ee48f 100644
--- a/doc/src/sgml/ref/alter_type.sgml
+++ b/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
diff --git a/doc/src/sgml/ref/alter_view.sgml b/doc/src/sgml/ref/alter_view.sgml
index 8bdc90a5a1..afbb3d02c7 100644
--- a/doc/src/sgml/ref/alter_view.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 2f034e2859..f3df2def86 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/create_schema.sgml b/doc/src/sgml/ref/create_schema.sgml
index 3c2dddb163..04b0c28731 100644
--- a/doc/src/sgml/ref/create_schema.sgml
+++ b/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>
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 85f5f42ea6..35bf0332c8 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/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
-- 
2.37.1 (Apple Git-137.1)

