mirror of
https://github.com/postgres/postgres.git
synced 2025-09-02 04:21:28 +03:00
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
This commit is contained in:
Tom Lane
@@ -112,16 +112,6 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
|
||||
to those already granted, if any.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There is also an option to grant privileges on all objects of the same
|
||||
type within one or more schemas. This functionality is currently supported
|
||||
only for tables, sequences, functions, and procedures. <literal>ALL
|
||||
TABLES</literal> also affects views and foreign tables, just like the
|
||||
specific-object <command>GRANT</command> command. <literal>ALL
|
||||
FUNCTIONS</literal> also affects aggregate functions, but not procedures,
|
||||
again just like the specific-object <command>GRANT</command> command.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The key word <literal>PUBLIC</literal> indicates that the
|
||||
privileges are to be granted to all roles, including those that might
|
||||
@@ -156,231 +146,35 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
|
||||
options for the object, too.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
PostgreSQL grants default privileges on some types of objects to
|
||||
<literal>PUBLIC</literal>. No privileges are granted to
|
||||
<literal>PUBLIC</literal> by default on
|
||||
tables,
|
||||
table columns,
|
||||
sequences,
|
||||
foreign data wrappers,
|
||||
foreign servers,
|
||||
large objects,
|
||||
schemas,
|
||||
or tablespaces.
|
||||
For other types of objects, the default privileges
|
||||
granted to <literal>PUBLIC</literal> are as follows:
|
||||
<literal>CONNECT</literal> and <literal>TEMPORARY</literal> (create
|
||||
temporary tables) privileges for databases;
|
||||
<literal>EXECUTE</literal> privilege for functions and procedures; and
|
||||
<literal>USAGE</literal> privilege for languages and data types
|
||||
(including domains).
|
||||
The object owner can, of course, <command>REVOKE</command>
|
||||
both default and expressly granted privileges. (For maximum
|
||||
security, issue the <command>REVOKE</command> in the same transaction that
|
||||
creates the object; then there is no window in which another user
|
||||
can use the object.)
|
||||
Also, these initial default privilege settings can be changed using the
|
||||
<xref linkend="sql-alterdefaultprivileges"/>
|
||||
command.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The possible privileges are:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><literal>SELECT</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows <xref linkend="sql-select"/> from
|
||||
any column, or the specific columns listed, of the specified table,
|
||||
view, or sequence.
|
||||
Also allows the use of
|
||||
<xref linkend="sql-copy"/> TO.
|
||||
This privilege is also needed to reference existing column values in
|
||||
<xref linkend="sql-update"/> or
|
||||
<xref linkend="sql-delete"/>.
|
||||
For sequences, this privilege also allows the use of the
|
||||
<function>currval</function> function.
|
||||
For large objects, this privilege allows the object to be read.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>INSERT</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows <xref linkend="sql-insert"/> of a new
|
||||
row into the specified table. If specific columns are listed,
|
||||
only those columns may be assigned to in the <command>INSERT</command>
|
||||
command (other columns will therefore receive default values).
|
||||
Also allows <xref linkend="sql-copy"/> FROM.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>UPDATE</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows <xref linkend="sql-update"/> of any
|
||||
column, or the specific columns listed, of the specified table.
|
||||
(In practice, any nontrivial <command>UPDATE</command> command will require
|
||||
<literal>SELECT</literal> privilege as well, since it must reference table
|
||||
columns to determine which rows to update, and/or to compute new
|
||||
values for columns.)
|
||||
<literal>SELECT ... FOR UPDATE</literal>
|
||||
and <literal>SELECT ... FOR SHARE</literal>
|
||||
also require this privilege on at least one column, in addition to the
|
||||
<literal>SELECT</literal> privilege. For sequences, this
|
||||
privilege allows the use of the <function>nextval</function> and
|
||||
<function>setval</function> functions.
|
||||
For large objects, this privilege allows writing or truncating the
|
||||
object.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>DELETE</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows <xref linkend="sql-delete"/> of a row
|
||||
from the specified table.
|
||||
(In practice, any nontrivial <command>DELETE</command> command will require
|
||||
<literal>SELECT</literal> privilege as well, since it must reference table
|
||||
columns to determine which rows to delete.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>TRUNCATE</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows <xref linkend="sql-truncate"/> on
|
||||
the specified table.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>REFERENCES</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows creation of a foreign key constraint referencing the specified
|
||||
table, or specified column(s) of the table. (See the
|
||||
<xref linkend="sql-createtable"/> statement.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>TRIGGER</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows the creation of a trigger on the specified table. (See the
|
||||
<xref linkend="sql-createtrigger"/> statement.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>CREATE</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
For databases, allows new schemas and publications to be created within the database.
|
||||
</para>
|
||||
<para>
|
||||
For schemas, allows new objects to be created within the schema.
|
||||
To rename an existing object, you must own the object <emphasis>and</emphasis>
|
||||
have this privilege for the containing schema.
|
||||
</para>
|
||||
<para>
|
||||
For tablespaces, allows tables, indexes, and temporary files to be
|
||||
created within the tablespace, and allows databases to be created that
|
||||
have the tablespace as their default tablespace. (Note that revoking
|
||||
this privilege will not alter the placement of existing objects.)
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>CONNECT</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows the user to connect to the specified database. This
|
||||
privilege is checked at connection startup (in addition to checking
|
||||
any restrictions imposed by <filename>pg_hba.conf</filename>).
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>TEMPORARY</literal></term>
|
||||
<term><literal>TEMP</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows temporary tables to be created while using the specified database.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>EXECUTE</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Allows the use of the specified function or procedure and the use of
|
||||
any operators that are implemented on top of the function. This is the
|
||||
only type of privilege that is applicable to functions and procedures.
|
||||
The <literal>FUNCTION</literal> syntax also works for aggregate
|
||||
functions. Alternatively, use <literal>ROUTINE</literal> to refer to a function,
|
||||
aggregate function, or procedure regardless of what it is.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>USAGE</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
For procedural languages, allows the use of the specified language for
|
||||
the creation of functions in that language. This is the only type
|
||||
of privilege that is applicable to procedural languages.
|
||||
Specific types of privileges, as defined in <xref linkend="ddl-priv"/>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><literal>TEMP</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
For schemas, allows access to objects contained in the specified
|
||||
schema (assuming that the objects' own privilege requirements are
|
||||
also met). Essentially this allows the grantee to <quote>look up</quote>
|
||||
objects within the schema. Without this permission, it is still
|
||||
possible to see the object names, e.g. by querying the system tables.
|
||||
Also, after revoking this permission, existing backends might have
|
||||
statements that have previously performed this lookup, so this is not
|
||||
a completely secure way to prevent object access.
|
||||
</para>
|
||||
<para>
|
||||
For sequences, this privilege allows the use of the
|
||||
<function>currval</function> and <function>nextval</function> functions.
|
||||
</para>
|
||||
<para>
|
||||
For types and domains, this privilege allows the use of the type or
|
||||
domain in the creation of tables, functions, and other schema objects.
|
||||
(Note that it does not control general <quote>usage</quote> of the type,
|
||||
such as values of the type appearing in queries. It only prevents
|
||||
objects from being created that depend on the type. The main purpose of
|
||||
the privilege is controlling which users create dependencies on a type,
|
||||
which could prevent the owner from changing the type later.)
|
||||
</para>
|
||||
<para>
|
||||
For foreign-data wrappers, this privilege allows creation of
|
||||
new servers using the foreign-data wrapper.
|
||||
</para>
|
||||
<para>
|
||||
For servers, this privilege allows creation of foreign tables using
|
||||
the server. Grantees may also create, alter, or drop their own
|
||||
user mappings associated with that server.
|
||||
Alternative spelling for <literal>TEMPORARY</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@@ -389,7 +183,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
|
||||
<term><literal>ALL PRIVILEGES</literal></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Grant all of the available privileges at once.
|
||||
Grant all of the privileges available for the object's type.
|
||||
The <literal>PRIVILEGES</literal> key word is optional in
|
||||
<productname>PostgreSQL</productname>, though it is required by
|
||||
strict SQL.
|
||||
@@ -397,9 +191,26 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
The privileges required by other commands are listed on the
|
||||
reference page of the respective command.
|
||||
<para>
|
||||
The <literal>FUNCTION</literal> syntax works for plain functions,
|
||||
aggregate functions, and window functions, but not for procedures;
|
||||
use <literal>PROCEDURE</literal> for those.
|
||||
Alternatively, use <literal>ROUTINE</literal> to refer to a function,
|
||||
aggregate function, window function, or procedure regardless of its
|
||||
precise type.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
There is also an option to grant privileges on all objects of the same
|
||||
type within one or more schemas. This functionality is currently supported
|
||||
only for tables, sequences, functions, and procedures. <literal>ALL
|
||||
TABLES</literal> also affects views and foreign tables, just like the
|
||||
specific-object <command>GRANT</command> command. <literal>ALL
|
||||
FUNCTIONS</literal> also affects aggregate and window functions, but not
|
||||
procedures, again just like the specific-object <command>GRANT</command>
|
||||
command. Use <literal>ALL ROUTINES</literal> to include procedures.
|
||||
</para>
|
||||
</refsect2>
|
||||
|
||||
@@ -520,79 +331,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Use <xref linkend="app-psql"/>'s <command>\dp</command> command
|
||||
to obtain information about existing privileges for tables and
|
||||
columns. For example:
|
||||
<programlisting>
|
||||
=> \dp mytable
|
||||
Access privileges
|
||||
Schema | Name | Type | Access privileges | Column access privileges
|
||||
--------+---------+-------+-----------------------+--------------------------
|
||||
public | mytable | table | miriam=arwdDxt/miriam | col1:
|
||||
: =r/miriam : miriam_rw=rw/miriam
|
||||
: admin=arw/miriam
|
||||
(1 row)
|
||||
</programlisting>
|
||||
The entries shown by <command>\dp</command> are interpreted thus:
|
||||
<literallayout class="monospaced">
|
||||
rolename=xxxx -- privileges granted to a role
|
||||
=xxxx -- privileges granted to PUBLIC
|
||||
|
||||
r -- SELECT ("read")
|
||||
w -- UPDATE ("write")
|
||||
a -- INSERT ("append")
|
||||
d -- DELETE
|
||||
D -- TRUNCATE
|
||||
x -- REFERENCES
|
||||
t -- TRIGGER
|
||||
X -- EXECUTE
|
||||
U -- USAGE
|
||||
C -- CREATE
|
||||
c -- CONNECT
|
||||
T -- TEMPORARY
|
||||
arwdDxt -- ALL PRIVILEGES (for tables, varies for other objects)
|
||||
* -- grant option for preceding privilege
|
||||
|
||||
/yyyy -- role that granted this privilege
|
||||
</literallayout>
|
||||
|
||||
The above example display would be seen by user <literal>miriam</literal> after
|
||||
creating table <literal>mytable</literal> and doing:
|
||||
|
||||
<programlisting>
|
||||
GRANT SELECT ON mytable TO PUBLIC;
|
||||
GRANT SELECT, UPDATE, INSERT ON mytable TO admin;
|
||||
GRANT SELECT (col1), UPDATE (col1) ON mytable TO miriam_rw;
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For non-table objects there are other <command>\d</command> commands
|
||||
that can display their privileges.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the <quote>Access privileges</quote> column is empty for a given object,
|
||||
it means the object has default privileges (that is, its privileges column
|
||||
is null). Default privileges always include all privileges for the owner,
|
||||
and can include some privileges for <literal>PUBLIC</literal> depending on the
|
||||
object type, as explained above. The first <command>GRANT</command> or
|
||||
<command>REVOKE</command> on an object
|
||||
will instantiate the default privileges (producing, for example,
|
||||
<literal>{miriam=arwdDxt/miriam}</literal>) and then modify them per the
|
||||
specified request. Similarly, entries are shown in <quote>Column access
|
||||
privileges</quote> only for columns with nondefault privileges.
|
||||
(Note: for this purpose, <quote>default privileges</quote> always means the
|
||||
built-in default privileges for the object's type. An object whose
|
||||
privileges have been affected by an <command>ALTER DEFAULT PRIVILEGES</command>
|
||||
command will always be shown with an explicit privilege entry that
|
||||
includes the effects of the <command>ALTER</command>.)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Notice that the owner's implicit grant options are not marked in the
|
||||
access privileges display. A <literal>*</literal> will appear only when
|
||||
grant options have been explicitly granted to someone.
|
||||
See <xref linkend="ddl-priv"/> for more information about specific
|
||||
privilege types, as well as how to inspect objects' privileges.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user