Hello Tom,
Thanks for this precise feedback.
Progress on this patch seems to be blocked on the question of whether
we want to keep enlarging the amount of psql-specific information
in the GRANT reference page, or move that all somewhere else.
Yep.
FWIW, I think I agree with Peter's position that moving it somewhere
else is the better option. Section 5.6 "Privileges" seems like a
reasonable choice.
Ok.
* Perhaps we could fix Peter's complaint about the "Owner" column by
relabeling it "All Privileges".
Ok.
I'd be inclined to label the last column "Default PUBLIC Privileges",
too, if we can fit that in.
Ok.
* The phrase "relation-like objects" seems way too vague, especially since
one has to read it as excluding sequences, which surely are relations for
most purposes. Is there a good reason not to just leave that entry as
"TABLE", full stop? Or maybe it could be "TABLE, VIEW, etc" or some such.
Ok.
* I don't think the use of "hardcoded" adds anything.
Hmmm. As "default privileges" can be altered, the point is to describe the
"default default privileges", but this looks absurd, hence the look for
something to add the idea that there is another one. ISTM that removing
"hardcoded" without replacing it makes the thing slightly ambiguous.
No big deal.
* Is it worth adding another table matching privilege names ("INSERT")
with their aclitem letters ("a"), rather than having the semi-formal
format currently appearing in grant.sgml?
Indeed I thought about that, because the description is not easy to read.
There's also some related material in 9.25 with the aclitem functions;
it'd be worth unifying that too maybe.
I've put a reference to it at least.
Attached v4:
- moves the table to the privileges section
- updates the table column headers
- adds a privilege/aclitem letter mapping table
- adds some appropriate links towards psql & aclitem
--
Fabien.
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index c8268222af..5fbaacc214 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1509,6 +1509,192 @@ REVOKE ALL ON accounts FROM PUBLIC;
privilege. For details see the <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/> reference pages.
</para>
+
+ <para>
+ <xref linkend="privilege-letters"/> shows how privileges are displayed
+ by <type>aclitem</type> functions described
+ in <xref linkend="functions-info"/>.
+ <xref linkend="default-privileges"/> summarizes the
+ default privileges granted to all object's types with
+ their associated <xref linkend="app-psql"/> backslash commands.
+ </para>
+
+ <table id="privilege-letters">
+ <title>Privileges' one-letter display</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry><literal>PRIVILEGE</literal></entry>
+ <entry>Letter</entry>
+ <entry>Objects</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>SELECT</literal></entry>
+ <entry><literal>r</literal> (Read)</entry>
+ <entry>
+ <literal>LARGE OBJECT</literal>,
+ <literal>TABLE</literal>, <literal>VIEW</literal>...
+ </entry>
+ </row>
+ <row>
+ <entry><literal>INSERT</literal></entry>
+ <entry><literal>a</literal> (Append)</entry>
+ <entry><literal>TABLE</literal>, <literal>VIEW</literal>...</entry>
+ </row>
+ <row>
+ <entry><literal>UPDATE</literal></entry>
+ <entry><literal>w</literal> (Write)</entry>
+ <entry>
+ <literal>LARGE OBJECT</literal>,
+ <literal>TABLE</literal>, <literal>VIEW</literal>...
+ </entry>
+ </row>
+ <row>
+ <entry><literal>DELETE</literal></entry>
+ <entry><literal>d</literal></entry>
+ <entry><literal>TABLE</literal>, <literal>VIEW</literal>...</entry>
+ </row>
+ <row>
+ <entry><literal>TRUNCATE</literal></entry>
+ <entry><literal>D</literal> (Delete)</entry>
+ <entry><literal>TABLE</literal>, <literal>VIEW</literal>...</entry>
+ </row>
+ <row>
+ <entry><literal>REFERENCES</literal></entry>
+ <entry><literal>x</literal></entry>
+ <entry><literal>TABLE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>TRIGGER</literal></entry>
+ <entry><literal>t</literal></entry>
+ <entry><literal>TABLE</literal>, <literal>VIEW</literal>...</entry>
+ </row>
+ <row>
+ <entry><literal>CREATE</literal></entry>
+ <entry><literal>C</literal></entry>
+ <entry>
+ <literal>DATABASE</literal>, <literal>SCHEMA</literal>,
+ <literal>TABLESPACE</literal>
+ </entry>
+ </row>
+ <row>
+ <entry><literal>CONNECT</literal></entry>
+ <entry><literal>c</literal></entry>
+ <entry><literal>DATABASE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>TEMPORARY</literal></entry>
+ <entry><literal>T</literal></entry>
+ <entry><literal>DATABASE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>EXECUTE</literal></entry>
+ <entry><literal>X</literal> (eXecute)</entry>
+ <entry><literal>FUNCTION</literal>, <literal>PROCEDURE</literal></entry>
+ </row>
+ <row>
+ <entry><literal>USAGE</literal></entry>
+ <entry><literal>U</literal></entry>
+ <entry>
+ <literal>DOMAIN</literal>, <literal>FOREIGN ...</literal>,
+ <literal>LANGUAGE</literal>, <literal>SCHEMA</literal>,
+ <literal>SEQUENCE</literal>, <literal>TYPE</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table id="default-privileges">
+ <title>Default access privileges per object's type, as shown by <command>psql</command></title>
+ <tgroup cols="4">
+ <thead>
+ <row>
+ <entry>Object's type</entry>
+ <entry><command>psql</command> <literal>\</literal>-command</entry>
+ <entry>All Privileges</entry>
+ <entry>Default <literal>PUBLIC</literal> Privileges</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>DATABASE</literal></entry>
+ <entry><literal>\l</literal></entry>
+ <entry><literal>CTc</literal></entry>
+ <entry><literal>Tc</literal></entry>
+ </row>
+ <row>
+ <entry><literal>DOMAIN</literal></entry>
+ <entry><literal>\dD+</literal></entry>
+ <entry><literal>U</literal></entry>
+ <entry><literal>U</literal></entry>
+ </row>
+ <row>
+ <entry><literal>FUNCTION</literal> or <literal>PROCEDURE</literal></entry>
+ <entry><literal>\df+</literal></entry>
+ <entry><literal>X</literal></entry>
+ <entry><literal>X</literal></entry>
+ </row>
+ <row>
+ <entry><literal>FOREIGN DATA WRAPPER</literal></entry>
+ <entry><literal>\dew+</literal></entry>
+ <entry><literal>U</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>FOREIGN SERVER</literal></entry>
+ <entry><literal>\des+</literal></entry>
+ <entry><literal>U</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>LANGUAGE</literal></entry>
+ <entry><literal>\dL+</literal></entry>
+ <entry><literal>U</literal></entry>
+ <entry><literal>U</literal></entry>
+ </row>
+ <row>
+ <entry><literal>LARGE OBJECT</literal></entry>
+ <entry></entry>
+ <entry><literal>rw</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>SCHEMA</literal></entry>
+ <entry><literal>\dn+</literal></entry>
+ <entry><literal>UC</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>SEQUENCE</literal></entry>
+ <entry><literal>\dp</literal></entry>
+ <entry><literal>rwU</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>TABLE</literal>, <literal>VIEW</literal>...</entry>
+ <entry><literal>\dp</literal></entry>
+ <entry><literal>arwdDxt</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>TABLESPACE</literal></entry>
+ <entry><literal>\db+</literal></entry>
+ <entry><literal>C</literal></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry><literal>TYPE</literal></entry>
+ <entry><literal>\dT+</literal></entry>
+ <entry><literal>U</literal></entry>
+ <entry><literal>U</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
</sect1>
<sect1 id="ddl-rowsecurity">
diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index ff64c7a3ba..bf643bfe92 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -533,7 +533,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
: admin=arw/miriam
(1 row)
</programlisting>
- The entries shown by <command>\dp</command> are interpreted thus:
+ The entries shown by <application>psql</application> backslash-commands,
+ like <command>\dp</command>, are interpreted thus:
<literallayout class="monospaced">
rolename=xxxx -- privileges granted to a role
=xxxx -- privileges granted to PUBLIC
