Thread: [HACKERS] "CURRENT_ROLE" is not documented

While trying to understand whether there was any difference, I noticed 
that CURRENT_ROLE is an undocumented synonymous for CURRENT_USER:

  psql> SELECT CURRENT_ROLE;
    current_user -- not a typo, it really says "current_user"
    calvin

  sh> grep -i CURRENT_ROLE doc/src/sgml/*/*.sgml doc/src/sgml/*.sgml
   doc/src/sgml/keywords.sgml: <entry><token>CURRENT_ROLE</token></entry>

Is there a special reason why it does not appear in the documentation? If 
not, I would suggest to apply the attached minimal documentation patch.

Also, there is a SESSION_USER, but no SESSION_ROLE. Not sure of the 
rationale.

-- 
Fabien.
-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Fabien COELHO <coelho@cri.ensmp.fr> writes:
> While trying to understand whether there was any difference, I noticed 
> that CURRENT_ROLE is an undocumented synonymous for CURRENT_USER:

>   psql> SELECT CURRENT_ROLE;
>     current_user -- not a typo, it really says "current_user"

Not as of HEAD ;-)

> Is there a special reason why it does not appear in the documentation?

Oversight, evidently.

> Also, there is a SESSION_USER, but no SESSION_ROLE. Not sure of the 
> rationale.

SQL standard says so, basically.  The standard draws a hard line between
"role" and "user", and says that only "users" can be the initiators of
sessions, so that the initial privilege identifier is always a user name
not a role name; hence no need for SESSION_ROLE.

It looks to me like according to the spec, when the current privilege
identifier is a role name, then CURRENT_ROLE returns that name and
CURRENT_USER returns NULL; when the current privilege identifier is a
user name, the opposite is true.

PG doesn't draw such a hard line; for us, roles and users are the same
kind of entity, with the distinction being a can-login privilege that's
really only a minor attribute.  So I think it's sensible for us to
treat these functions as synonyms.

Perhaps we could satisfy the letter of the spec by having one of these
functions return NULL depending on the current role's can-login attribute,
but I frankly cannot see a reason why that would be a good thing to do.
It would mostly be a foot-gun for SQL queries --- I think you'd basically
always have to write "coalesce(current_user, current_role)" to avoid
having your code break in unexpected contexts.

I agree we ought to document this, but we likely need to mention
the discrepancy from the spec, too.
        regards, tom lane

>>   psql> SELECT CURRENT_ROLE;
>>     current_user -- not a typo, it really says "current_user"
>
> Not as of HEAD ;-)

Good:-) I was connecting to a 9.6.2 server from a pg10dev client.

>> Is there a special reason why it does not appear in the documentation?
>
> Oversight, evidently.

Ok.

>> Also, there is a SESSION_USER, but no SESSION_ROLE. Not sure of the
>> rationale.
>
> SQL standard says so, basically.  The standard draws a hard line between
> "role" and "user", and says that only "users" can be the initiators of
> sessions, so that the initial privilege identifier is always a user name
> not a role name; hence no need for SESSION_ROLE.

Hmmm... why not. I'm in the pg context where a USER is a ROLE, as you 
point out below.

> PG doesn't draw such a hard line; for us, roles and users are the same
> kind of entity, with the distinction being a can-login privilege that's
> really only a minor attribute.  So I think it's sensible for us to
> treat these functions as synonyms.

Yep.

> I agree we ought to document this, but we likely need to mention
> the discrepancy from the spec, too.

Yep. A little subtle, though. Maybe it is enough to just say that for pg a 
user is a role, which is not the case in the standard?

Thanks for the explanation!

-- 
Fabien.

Fabien COELHO <coelho@cri.ensmp.fr> writes:
>> I agree we ought to document this, but we likely need to mention
>> the discrepancy from the spec, too.

> Yep. A little subtle, though. Maybe it is enough to just say that for pg a
> user is a role, which is not the case in the standard?

I did it like this:

*** 15943,15948 ****
--- 15956,15966 ----     functions with the attribute <literal>SECURITY DEFINER</literal>.     In Unix parlance, the
sessionuser is the <quote>real user</quote> and     the current user is the <quote>effective user</quote>. 
+     <function>current_role</function> and <function>user</function> are
+     synonyms for <function>current_user</function>.  (The SQL standard draws
+     a distinction between <function>current_role</function>
+     and <function>current_user</function>, but <productname>PostgreSQL</>
+     does not, since it unifies users and roles into a single kind of entity.)    </para>     <para>

I stole the "unifies..." language out of the CREATE ROLE page.
        regards, tom lane

>      functions with the attribute <literal>SECURITY DEFINER</literal>.
>      In Unix parlance, the session user is the <quote>real user</quote> and
>      the current user is the <quote>effective user</quote>.
> +     <function>current_role</function> and <function>user</function> are
> +     synonyms for <function>current_user</function>.  (The SQL standard draws
> +     a distinction between <function>current_role</function>
> +     and <function>current_user</function>, but <productname>PostgreSQL</>
> +     does not, since it unifies users and roles into a single kind of entity.)

Looks simple and good to me. Thanks for the wording!

-- 
Fabien.