From 736ba917f4849915b70794f291f85dedd890d2f8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 12 Feb 2020 14:13:13 -0500 Subject: [PATCH] Doc: fix old oversights in GRANT/REVOKE documentation. The GRANTED BY clause in GRANT/REVOKE ROLE has been there since 2005 but was never documented. I'm not sure now whether that was just an oversight or was intentional (given the limited capability of the option). But seeing that pg_dumpall does emit code that uses this option, it seems like not documenting it at all is a bad idea. Also, when we upgraded the syntax to allow CURRENT_USER/SESSION_USER as the privilege recipient, the role form of GRANT was incorrectly not modified to show that, and REVOKE's docs weren't touched at all. Although I'm not that excited about GRANTED BY, the other oversight seems serious enough to justify a back-patch. Discussion: https://postgr.es/m/3070.1581526786@sss.pgh.pa.us --- doc/src/sgml/ref/grant.sgml | 24 +++++++++++++++++---- doc/src/sgml/ref/revoke.sgml | 42 +++++++++++++++++++++++------------- 2 files changed, 47 insertions(+), 19 deletions(-) diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index ff64c7a3ba..1f0a9791ed 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -79,14 +79,16 @@ GRANT { USAGE | ALL [ PRIVILEGES ] } ON TYPE type_name [, ...] TO role_specification [, ...] [ WITH GRANT OPTION ] +GRANT role_name [, ...] TO role_specification [, ...] + [ WITH ADMIN OPTION ] + [ GRANTED BY role_specification ] + where role_specification can be: [ GROUP ] role_name | PUBLIC | CURRENT_USER | SESSION_USER - -GRANT role_name [, ...] TO role_name [, ...] [ WITH ADMIN OPTION ] @@ -425,10 +427,17 @@ GRANT role_name [, ...] TO + + If GRANTED BY is specified, the grant is recorded as + having been done by the specified role. Only database superusers may + use this option, except when it names the same role executing the command. + + Unlike the case with privileges, membership in a role cannot be granted - to PUBLIC. Note also that this form of the command does not - allow the noise word GROUP. + to PUBLIC. Note also that this form of the command + does not allow the noise word GROUP + in role_specification. @@ -658,6 +667,13 @@ GRANT admins TO joe; to roles. + + The SQL standard allows the GRANTED BY option to + be used in all forms of GRANT. PostgreSQL only + supports it when granting role membership, and even then only superusers + may use it in nontrivial ways. + + The SQL standard provides for a USAGE privilege on other kinds of objects: character sets, collations, diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml index 5317f8ccba..05bcc66310 100644 --- a/doc/src/sgml/ref/revoke.sgml +++ b/doc/src/sgml/ref/revoke.sgml @@ -26,14 +26,14 @@ REVOKE [ GRANT OPTION FOR ] [, ...] | ALL [ PRIVILEGES ] } ON { [ TABLE ] table_name [, ...] | ALL TABLES IN SCHEMA schema_name [, ...] } - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { { SELECT | INSERT | UPDATE | REFERENCES } ( column_name [, ...] ) [, ...] | ALL [ PRIVILEGES ] ( column_name [, ...] ) } ON [ TABLE ] table_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] @@ -41,73 +41,81 @@ REVOKE [ GRANT OPTION FOR ] [, ...] | ALL [ PRIVILEGES ] } ON { SEQUENCE sequence_name [, ...] | ALL SEQUENCES IN SCHEMA schema_name [, ...] } - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { { CREATE | CONNECT | TEMPORARY | TEMP } [, ...] | ALL [ PRIVILEGES ] } ON DATABASE database_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { USAGE | ALL [ PRIVILEGES ] } ON DOMAIN domain_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { USAGE | ALL [ PRIVILEGES ] } ON FOREIGN DATA WRAPPER fdw_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { USAGE | ALL [ PRIVILEGES ] } ON FOREIGN SERVER server_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { EXECUTE | ALL [ PRIVILEGES ] } ON { { FUNCTION | PROCEDURE | ROUTINE } function_name [ ( [ [ argmode ] [ arg_name ] arg_type [, ...] ] ) ] [, ...] | ALL { FUNCTIONS | PROCEDURES | ROUTINES } IN SCHEMA schema_name [, ...] } - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { USAGE | ALL [ PRIVILEGES ] } ON LANGUAGE lang_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { { SELECT | UPDATE } [, ...] | ALL [ PRIVILEGES ] } ON LARGE OBJECT loid [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { { CREATE | USAGE } [, ...] | ALL [ PRIVILEGES ] } ON SCHEMA schema_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { CREATE | ALL [ PRIVILEGES ] } ON TABLESPACE tablespace_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ GRANT OPTION FOR ] { USAGE | ALL [ PRIVILEGES ] } ON TYPE type_name [, ...] - FROM { [ GROUP ] role_name | PUBLIC } [, ...] + FROM role_specification [, ...] [ CASCADE | RESTRICT ] REVOKE [ ADMIN OPTION FOR ] - role_name [, ...] FROM role_name [, ...] + role_name [, ...] FROM role_specification [, ...] + [ GRANTED BY role_specification ] [ CASCADE | RESTRICT ] + +where role_specification can be: + + [ GROUP ] role_name + | PUBLIC + | CURRENT_USER + | SESSION_USER @@ -169,8 +177,12 @@ REVOKE [ ADMIN OPTION FOR ] When revoking membership in a role, GRANT OPTION is instead called ADMIN OPTION, but the behavior is similar. + This form of the command also allows a GRANTED BY + option, but that option is currently ignored (except for checking + the existence of the named role). Note also that this form of the command does not - allow the noise word GROUP. + allow the noise word GROUP + in role_specification.