"GRANT on Roles" supports multiple options

[Andrei Polushin]

(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 role_name [, ...] TO 
role_specification [, ...]
-[ WITH { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ]
+[ WITH [ { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ] [, ...] ]
 [ GRANTED BY role_specification ]

--
Andrei Polushin

"GRANT on Roles" supports multiple options

[PG Doc comments form]

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/17/docguide.html
Description:

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 role_name [, ...] TO
role_specification [, ...]
-[ WITH { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ]
+[ WITH [ { ADMIN | INHERIT | SET } { OPTION | TRUE | FALSE } ] [, ...]
]
 [ GRANTED BY role_specification ]
--
Andrei Polushin