[jira] Commented: (DERBY-3193) SQL roles: Add documentation

["Kim Haase (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DERBY-3193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12643076#action_12643076 ] 

Kim Haase commented on DERBY-3193:
----------------------------------

The following changes will need to be made to the Reference Manual, Tools Guide, and Developer's Guide. There are a couple of questions at the end asking for clarifications of some of the Roles spec language.

Ref Manual

Information mostly comes from section 4 of the Roles spec, unless otherwise stated.

rrefrauthid.html (AuthorizationIdentifier): Update to include a role as well as a user as a valid identifier.

New topic: add CURRENT_ROLE built-in function.

rrefsqlj30540.html (column-definition): Update "Column default" section to include CURRENT_ROLE in the list of values for DefaultConstantExpression. Note: the Roles spec also mentions the ALTER TABLE topic, but this topic points to rrefsqlj30540.html in a couple of places; it doesn't seem that the topic itself needs any fixes.

rrefsqljgrant.html (GRANT statement): Add syntax for granting a role to a grantee. Under "grantees" section, make "authorization ID" a link to the AuthorizationIdentifier section? Also change text to mention roles as well as users? And add examples of GRANT statements for roles.

New topic: add CREATE ROLE statement.

New topic: add DROP ROLE statement.

rrefsqljrevoke.html (REVOKE statement): Under "grantees" section, make "authorization ID" a link to the AuthorizationIdentifier section? Also change text to mention roles as well as users? And add an example of a REVOKE statement for a role.

New topic: add SET ROLE statement.

rrefkeywords29722.html (SQL reserved words): Add ROLE to list. (Oddly, CURRENT_ROLE is already on the list.)

rrefsqlj31580.html (CREATE SCHEMA statement): add note that "AUTHORIZATION user-name" in the syntax really does mean that only a user, not a role, can create a schema. (section 5.12 of roles spec)

rrefsistabssyscolperms.html (SYSCOLPERMS system table): for the GRANTEE row, change "user" to "user or role". (Section 6.1)

rrefsistabssysroutineperms.html (SYSROUTINEPERMS system table): ditto.
rrefsistabssystableperms.html (SYSTABLEPERMS system table): ditto.

New topic: add SYSROLES system table. Has primary key and unique key but no foreign key. (Section 6.1)

Tools Guide:

ctoolsgenddldb.html (Generating the DDL for a database, under dblook): Add roles to the list of objects? (Section 6.4)

rtoolsijcomrefshow.html (Show command): Add descriptions of the commands commands "show roles", "show settable_roles" and "show enabled_roles". (Section 8)

Developer's Guide:

cdevcsecure866060.html (Setting the SQL standard authorization mode): Add subsection explaining roles. (Section 8)

----
Questions:

In section 5.6, the second paragraph is a bit confusing. Does "the latter" refer to "all the privileges granted to the current role and to the roles contained in the current role"? And should "the union of privileges roles" be just "the union of privileges"? And is the rest of the sentence correct? 

In section 5.8, the second sentence is confusing: 

"If the role loses that privilege, and a session that has a current role which is that role or a role that contains that role, the session may lose that privilege, unless it available the current user, or to PUBLIC or another role contained in the current role." 

Should it say the following instead?

"If the role loses that privilege, and a session has a current role which is that role or a role that contains that role, the session may lose that privilege, unless it is available to the current user, or to PUBLIC or another role contained in the current role."


> SQL roles: Add documentation
> ----------------------------
>
>                 Key: DERBY-3193
>                 URL: https://issues.apache.org/jira/browse/DERBY-3193
>             Project: Derby
>          Issue Type: Task
>          Components: Documentation
>            Reporter: Dag H. Wanvik
>            Assignee: Kim Haase
>             Fix For: 10.5.0.0
>
>


-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.