From: Andrei Polushin <polushin@gmail.com>
Content-Type: text/plain;
	charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3826.500.181.1.5\))
Subject: "GRANT on Roles" supports multiple options
Date: Thu, 8 May 2025 21:58:11 +0700
References: 
 <174671599514.1455381.16053182845970432387@wrigleys.postgresql.org>
To: pgsql-docs@lists.postgresql.org
In-Reply-To: 
 <174671599514.1455381.16053182845970432387@wrigleys.postgresql.org>
Message-Id: <ECA41A7A-3F47-4AC8-80AC-2F3C8E2149A1@gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/ECA41A7A-3F47-4AC8-80AC-2F3C8E2149A1%40gmail.com>
Precedence: bulk

(resending with correct formatting)

Hi!

In the documentation of the GRANT[1] command, the Synopsis for "GRANT on =
Roles" command is incomplete. Quoting from the current docs:

  GRANT role_name [, ...] TO role_specification [, ...]
      [ WITH { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ]
      [ GRANTED BY role_specification ]

The "GRANT on Roles" command is documented as if it expects a single =
option after "WITH", but it actually supports multiple options, =
separated by comma, e.g.

  GRANT created_user TO creating_user WITH ADMIN TRUE, SET FALSE, =
INHERIT FALSE

The example is taken from section "21.2. Role Attributes"[2] of the =
documentation.

More examples can be found by searching the codebase:

  git grep -Pi '\bGRANT\b.+\bTO\b.+,\s*(ADMIN|INHERIT|SET)\s+\w+'

The parser is implemented here:

  src/backend/commands/user.c:1480:GrantRole(ParseState *pstate, =
GrantRoleStmt *stmt)

The documentation is to be corrected for v16, v17, and later versions.

[1]: https://www.postgresql.org/docs/17/sql-grant.html
[2]: https://www.postgresql.org/docs/17/role-attributes.html

diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml
index 999f657d5c0..9796e9a49d7 100644
--- a/doc/src/sgml/ref/grant.sgml
+++ b/doc/src/sgml/ref/grant.sgml
@@ -100,3 +100,3 @@ GRANT { USAGE | ALL [ PRIVILEGES ] }
 GRANT <replaceable class=3D"parameter">role_name</replaceable> [, ...] =
TO <replaceable class=3D"parameter">role_specification</replaceable> [, =
...]
-    [ WITH { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ]
+    [ WITH [ { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ] [, =
...] ]
     [ GRANTED BY <replaceable =
class=3D"parameter">role_specification</replaceable> ]

--
Andrei Polushin