Re: CREATE ROLE inheritance details

Поиск
Список
Период
Сортировка
От David G. Johnston
Тема Re: CREATE ROLE inheritance details
Дата
Msg-id CAKFQuwYf6jJvS2DBa0=6ysm2hircXGDYvJ87pt+O2dvcXrb6fQ@mail.gmail.com
обсуждение исходный текст
Ответ на Re: CREATE ROLE inheritance details  (Bruce Momjian <bruce@momjian.us>)
Ответы Re: CREATE ROLE inheritance details  (Bruce Momjian <bruce@momjian.us>)
Re: CREATE ROLE inheritance details  (Noah Misch <noah@leadboat.com>)
Список pgsql-docs
Дерево обсуждения
Almost there I think.  The comment regarding seeing GRANT really applies to IN ROLE, ROLE, and ADMIN.  Repeating it seemed a poor choice and upon thinking further it really makes sense to consider how this command and GRANT work together part of the description of create role.  So I moved that commentary to a new description paragraph.

diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml
index d0d3d7ed64..f3b89e7239 100644
--- a/doc/src/sgml/ref/create_role.sgml
+++ b/doc/src/sgml/ref/create_role.sgml
@@ -66,6 +66,17 @@ in sync when changing the above synopsis!
    Note that roles are defined at the database cluster
    level, and so are valid in all databases in the cluster.
   </para>
+
+  <para>
+   During role creation it is possible to immediately assign the newly created
+   role to be a member of an existing role, and also assign existing roles
+   to be members of the newly created role.  The rules for which initial
+   role membership options are enabled are described below in the
+   <literal>IN ROLE</literal>, <literal>ROLE</literal>, and
+   <literal>ADMIN</literal> clauses.  Alternatively, the <xref linkend="sql-grant"/>
+   command has fine-grained option control during membership creation,
+   and also the ability to modify these options after the new role is created.
+  </para>
  </refsect1>

  <refsect1>
@@ -285,10 +296,7 @@ in sync when changing the above synopsis!
         roles. The new membership will have the <literal>SET</literal>
         option enabled and the <literal>ADMIN</literal> option disabled.
         The <literal>INHERIT</literal> option will be enabled unless the
-        <literal>NOINHERIT</literal> option is specified.  See the <xref
-        linkend="sql-grant"/> command, which has additional option
-        control during membership creation and to modify these options
-        after the new role is created.
+        <literal>NOINHERIT</literal> option is specified.
        </para>
       </listitem>
      </varlistentry>

And then fixed up one last instance of attribute/option specification.  I left the term "  membership inheritance status" alone in the attribute description since that really does refer to the concept and neither the specific attribute here nor the membership option.  All of the other references seemed better of being specific to the feature and not the behavior.


@@ -301,9 +309,9 @@ in sync when changing the above synopsis!
         existing roles to be automatically added as members, with the
         <literal>SET</literal> option enabled. This in effect makes the
         new role a <quote>group</quote>.  Roles named in this clause
-        with role-level <literal>INHERIT</literal> options will have
-        <literal>INHERIT</literal> enabled in the new membership.  New
-        memberships will have the <literal>ADMIN</literal> option disabled.
+        with role-level the <literal>INHERIT</literal> attribute will have
+        the <literal>INHERIT</literal> option enabled in the new membership.
+        New memberships will have the <literal>ADMIN</literal> option disabled.
        </para>
       </listitem>
      </varlistentry>

The omission of an option during membership modification results in no change, not applying the default, applies to all three, not just inherit.  Again, instead of documenting all three with this it seemed preferable to add it once somewhere - in this case the paragraph that talks about the option mode values seems appropriate.

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index ee53871713..9d27b7fcde 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -266,7 +266,9 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
    <literal>TRUE</literal> or <literal>FALSE</literal>. The keyword
    <literal>OPTION</literal> is accepted as a synonym for
    <literal>TRUE</literal>, so that <literal>WITH ADMIN OPTION</literal>
-   is a synonym for <literal>WITH ADMIN TRUE</literal>.
+   is a synonym for <literal>WITH ADMIN TRUE</literal>.  When altering
+   an existing membership the omission of an option results in the current
+   value being retained.
   </para>

   <para>

And some final touch-ups; including removing the now redundant omission sentence for inherit.

@@ -280,14 +282,13 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
   </para>

   <para>
-   The <literal>INHERIT</literal> attribute controls the inheritance status
+   The <literal>INHERIT</literal> option controls the inheritance status
    of the new membership;  see <xref linkend="role-membership"/> for
    details on inheritance.  If it is set to <literal>TRUE</literal>,
    it causes the new member to inherit from the granted role. If
    set to <literal>FALSE</literal>, the new member does not inherit.
-   If unspecified, new role membership defaults to the inheritance status
-   of the role being added.  If an existing membership, the inheritance
-   option is unchanged.
+   If unspecified when creating a new role membership this defaults to
+   the inheritance attribute of the role being added.
   </para>

   <para>


I've attached a revised role.diff patch as well as just the changes from the original.

David J.


Вложения

В списке pgsql-docs по дате отправления:

Предыдущее
От: PG Doc comments form
Дата:
Сообщение: SET ROLE versus SET SESSION AUTHORIZATION
Следующее
От: Peter Eisentraut
Дата:
Сообщение: Re: create table explicitly mention that unique|primary key constraint will create an