Skip to content

P
Postgres FD Implementation
Commit afc4a78a authored by Tom Lane's avatar Tom Lane
Browse files
Options

Refactor documentation about privileges to centralize the info. 

Expand section 5.6 "Privileges" to include the full definition of
each privilege type, and an explanation of aclitem privilege displays,
along with some helpful summary tables.  Most of this material came
out of the GRANT reference page, although some of it is new.
Adjust a bunch of links that were pointing to GRANT to point to 5.6.

Fabien Coelho and Tom Lane, reviewed by Bradley DeJong

Discussion: https://postgr.es/m/alpine.DEB.2.21.1807311735200.20743@lancre
parent ee2b37ae
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 589 additions and 390 deletions
doc/src/sgml/catalogs.sgml
View file @ afc4a78a
......@@ -1973,10 +1973,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
......@@ -2679,10 +2676,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
</tbody>
......@@ -3491,10 +3485,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
......@@ -3587,10 +3578,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
......@@ -4052,9 +4040,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry></entry>
<entry>
The initial access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
<xref linkend="ddl-priv"/> for details
</entry>
</row>
......@@ -4179,10 +4165,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
</tbody>
......@@ -4319,10 +4302,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
......@@ -4386,10 +4366,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
</tbody>
......@@ -5396,10 +5373,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
</tbody>
......@@ -6810,10 +6784,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
......@@ -7923,10 +7894,7 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
<entry><type>aclitem[]</type></entry>
<entry></entry>
<entry>
Access privileges; see
<xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
for details
Access privileges; see <xref linkend="ddl-priv"/> for details
</entry>
</row>
</tbody>
......
doc/src/sgml/ddl.sgml
View file @ afc4a78a
This diff is collapsed.
doc/src/sgml/func.sgml
View file @ afc4a78a
......@@ -16932,21 +16932,11 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para>
<xref linkend="functions-aclitem-fn-table"/> shows the operators
available for the <type>aclitem</type> type, which is the internal
representation of access privileges. An <type>aclitem</type> entry
describes the permissions of a grantee, whether they are grantable
or not, and which grantor granted them. For instance,
<literal>calvin=r*w/hobbes</literal> specifies that the role
<literal>calvin</literal> has the grantable privilege
<literal>SELECT</literal> (<literal>r*</literal>) and the non-grantable
privilege <literal>UPDATE</literal> (<literal>w</literal>), granted by
the role <literal>hobbes</literal>. An empty grantee stands for
<literal>PUBLIC</literal>.
available for the <type>aclitem</type> type, which is the catalog
representation of access privileges. See <xref linkend="ddl-priv"/>
for information about how to read access privilege values.
</para>
<indexterm>
<primary>aclitem</primary>
</indexterm>
<indexterm>
<primary>acldefault</primary>
</indexterm>
......@@ -17015,9 +17005,9 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<tbody>
<row>
<entry><literal><function>acldefault</function>(<parameter>type</parameter>,
<parameter>ownerId</parameter>)</literal></entry>
<parameter>ownerId</parameter>)</literal></entry>
<entry><type>aclitem[]</type></entry>
<entry>get the hardcoded default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
<entry>get the default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
</row>
<row>
<entry><literal><function>aclexplode</function>(<parameter>aclitem[]</parameter>)</literal></entry>
......@@ -17034,16 +17024,14 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
</table>
<para>
<function>acldefault</function> returns the hardcoded default access privileges
for an object of <parameter>type</parameter> belonging to role <parameter>ownerId</parameter>.
Notice that these are used in the absence of any pg_default_acl
(<xref linkend="catalog-pg-default-acl"/>) entry. Default access privileges are described in
<xref linkend="sql-grant"/> and can be overwritten with
<xref linkend="sql-alterdefaultprivileges"/>. In other words, this function will return
results which may be misleading when the defaults have been overridden.
Type is a <type>CHAR</type>, use
<function>acldefault</function> returns the built-in default access
privileges for an object of type <parameter>type</parameter> belonging to
role <parameter>ownerId</parameter>. These represent the access
privileges that will be assumed when an object's ACL entry is null.
(The default access privileges are described in <xref linkend="ddl-priv"/>.)
The <parameter>type</parameter> parameter is a <type>CHAR</type>: write
'c' for <literal>COLUMN</literal>,
'r' for relation-like objects such as <literal>TABLE</literal> or <literal>VIEW</literal>,
'r' for <literal>TABLE</literal> and table-like objects,
's' for <literal>SEQUENCE</literal>,
'd' for <literal>DATABASE</literal>,
'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
......@@ -17053,15 +17041,16 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
't' for <literal>TABLESPACE</literal>,
'F' for <literal>FOREIGN DATA WRAPPER</literal>,
'S' for <literal>FOREIGN SERVER</literal>,
or
'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
</para>
<para>
<function>aclexplode</function> returns an <type>aclitem</type> array
as a set rows. Output columns are grantor <type>oid</type>,
as a set of rows. Output columns are grantor <type>oid</type>,
grantee <type>oid</type> (<literal>0</literal> for <literal>PUBLIC</literal>),
granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
and whether the prilivege is grantable as <type>boolean</type>.
and whether the privilege is grantable as <type>boolean</type>.
<function>makeaclitem</function> performs the inverse operation.
</para>
......
doc/src/sgml/ref/alter_default_privileges.sgml
View file @ afc4a78a
......@@ -112,7 +112,7 @@ REVOKE [ GRANT OPTION FOR ]
</para>
<para>
As explained under <xref linkend="sql-grant"/>,
As explained in <xref linkend="ddl-priv"/>,
the default privileges for any object type normally grant all grantable
permissions to the object owner, and may grant some privileges to
<literal>PUBLIC</literal> as well. However, this behavior can be changed by
......@@ -173,9 +173,8 @@ REVOKE [ GRANT OPTION FOR ]
<para>
Use <xref linkend="app-psql"/>'s <command>\ddp</command> command
to obtain information about existing assignments of default privileges.
The meaning of the privilege values is the same as explained for
<command>\dp</command> under
<xref linkend="sql-grant"/>.
The meaning of the privilege display is the same as explained for
<command>\dp</command> in <xref linkend="ddl-priv"/>.
</para>
<para>
......
doc/src/sgml/ref/create_function.sgml
View file @ afc4a78a
......@@ -761,7 +761,7 @@ $$ LANGUAGE plpgsql
<para>
Another point to keep in mind is that by default, execute privilege
is granted to <literal>PUBLIC</literal> for newly created functions
(see <xref linkend="sql-grant"/> for more
(see <xref linkend="ddl-priv"/> for more
information). Frequently you will wish to restrict use of a security
definer function to only some users. To do that, you must revoke
the default <literal>PUBLIC</literal> privileges and then grant execute
......
doc/src/sgml/ref/grant.sgml
View file @ afc4a78a
This diff is collapsed.
doc/src/sgml/ref/psql-ref.sgml
View file @ afc4a78a
......@@ -1324,8 +1324,8 @@ testdb=&gt;
<para>
The <xref linkend="sql-alterdefaultprivileges"/> command is used to set
default access privileges. The meaning of the
privilege display is explained under
<xref linkend="sql-grant"/>.
privilege display is explained in
<xref linkend="ddl-priv"/>.
</para>
</listitem>
</varlistentry>
......@@ -1372,7 +1372,7 @@ testdb=&gt;
specified, only those servers whose name matches the pattern
are listed. If the form <literal>\des+</literal> is used, a
full description of each server is shown, including the
server's ACL, type, version, options, and description.
server's access privileges, type, version, options, and description.
</para>
</listitem>
</varlistentry>
......@@ -1425,8 +1425,8 @@ testdb=&gt;
If <replaceable class="parameter">pattern</replaceable> is
specified, only those foreign-data wrappers whose name matches
the pattern are listed. If the form <literal>\dew+</literal>
is used, the ACL, options, and description of the foreign-data
wrapper are also shown.
is used, the access privileges, options, and description of the
foreign-data wrapper are also shown.
</para>
</listitem>
</varlistentry>
......@@ -1639,8 +1639,8 @@ testdb=&gt;
The <xref linkend="sql-grant"/> and
<xref linkend="sql-revoke"/>
commands are used to set access privileges. The meaning of the
privilege display is explained under
<xref linkend="sql-grant"/>.
privilege display is explained in
<xref linkend="ddl-priv"/>.
</para>
</listitem>
</varlistentry>
......
doc/src/sgml/ref/revoke.sgml
View file @ afc4a78a
......@@ -177,14 +177,6 @@ REVOKE [ ADMIN OPTION FOR ]
<refsect1 id="sql-revoke-notes">
<title>Notes</title>
<para>
Use <xref linkend="app-psql"/>'s <command>\dp</command> command to
display the privileges granted on existing tables and columns. See <xref
linkend="sql-grant"/> for information about the
format. For non-table objects there are other <command>\d</command> commands
that can display their privileges.
</para>
<para>
A user can only revoke privileges that were granted directly by
that user. If, for example, user A has granted a privilege with
......@@ -244,6 +236,11 @@ REVOKE [ ADMIN OPTION FOR ]
lead to revoking privileges other than the ones you intended, or not
revoking anything at all.
</para>
<para>
See <xref linkend="ddl-priv"/> for more information about specific
privilege types, as well as how to inspect objects' privileges.
</para>
</refsect1>
<refsect1 id="sql-revoke-examples">
......@@ -293,9 +290,10 @@ REVOKE admins FROM joe;
<refsect1>
<title>See Also</title>
<simpara>
<xref linkend="sql-grant"/>
</simpara>
<simplelist type="inline">
<member><xref linkend="sql-grant"/></member>
<member><xref linkend="sql-alterdefaultprivileges"/></member>
</simplelist>
</refsect1>
</refentry>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment