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

["Dag H. Wanvik (JIRA)" <ji...@apache.org>]

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

Dag H. Wanvik commented on DERBY-3193:
--------------------------------------

Hi Kim!

Thanks for your quick and good work on this!  Here is feedback for ref
man & tools. Will look at devguide next.


* M src/ref/crefsqlj35312.dita

Good!

* A src/ref/rrefcurrentrole.dita

> This function returns a string of up to 128 characters.

Actually, no. This has changed. The identifier length (after case
normalization) is max 128, but the returned identifer string returned
may be up to 2 + (2*128) long due to quoting.

For example:
    create role "A""B"; -- case normal form: A"B
    set role "A""B";
    values current_role -- returns the string "A""B"


* A src/ref/rrefcreaterole.dita

Good!

* A src/ref/rrefsetrole.dita

> - The privileges the role inherits from any other roles granted to it

I think we should try to use the term "contained role" and define once
so we can avoid having to speak about grant relationship between roles
all the time:

"A role contains another role if that role is granted to it, or is
contained in a role granted to it."

Given this definition we can say for this bullet:

"The union of privileges of roles contained in that role."

> The privileges of the current role, if set

should be (I think):

"The privileges identified by the current role, if set" (since you
just defined "identified by").

Examples:

> // These examples show the use of SET ROLE in Java statements.
                                                ****
> // The case normal form is visible in the SYSROLES system table.
                                            ********

We should use JDBC rather than Java, I think. Indent the comment to
the margin of the code. It should be "SYS.SYSROLES".



* M src/ref/rrefsqljrevoke.dita

> "Only the database owner can revoke a role."

"database owner" could be linked here.

(Probably not from this diff, but anyway):

> Before you issue a REVOKE statement, check that the
  derby.database.sqlAuthorization property is set to true. 

This sentence is a bit disingenuous. Since sqlAuthorization must be
set before a GRANT can be performed, and a GRANT must logically be
performed before a REVOKE is meaningful, and sqlAuthorization can't be
switched off once set, the "check that..." sounds a bit weird..

> You can revoke privileges from an object 

Should be "You can revoke privileges for an object".

> The syntax that you use for the REVOKE statement depends on whether
  you are revoking privileges to a table or to a routine.

.. or whether you are revoking a role.

The link to grantees points to
rrefsqljgrant.html#rrefsqljgrant__grantgrantees, but there is a syntax
definition for grantees in rrefsqljrevoke as well? Is this
intentional? Since they are equal, maybe the link can be retained, but
the definition in rrefsqljrevoke can be removed..

> You can revoke the privileges from specific users or roles or from
  all users. 

Add: "You can revoke a role from a role, a user, and from PUBLIC".

Limitations section:

Add:

"Derby tracks any dependencies on the definer's current role for
views, constraints and triggers. If privileges were obtainable only
via the current role when the object in question was defined, that
object will depend on the current role. The object will get dropped if
the role is revoked from the defining user or from PUBLIC, as the case
may be. Also, if a contained role of the current role in such cases
gets revoked, dependent objects will get dropped. Note that dropping
may be too pessimistic. This is because Derby does not presently make
an attempt to re-check if the necessary privileges are still available
in such cases."


* M src/ref/crefsqlj80721.dita

Good!

* A src/ref/rrefrolename.dita

Good!

* M src/ref/rrefsistabssystableperms.dita

Good!

* A src/ref/rrefsistabssysroles.dita

Bullet

> - A role grant (result of a GRANT statement in which the grantee is a role)

The parenthesized statement is a bit misleading. Just remove it, I think:

- "A role grant"

The entry for WITHADMINOPTION is wrong. The Contents filed should
read some such:

"A role definition is modelled as a grant from "_SYSTEM" to the data
base owner so in such cases the value is always 'Y'. This means the
creator (data base owner) is allowed to grant the newly created role
(of course).  Currently roles can not be granted WITH ADMIN OPTION, so
in other cases its value is 'N'."

* M src/ref/rrefsyscsdiagtables.dita

"Spec says "can be used to get the contained roles for a role (or the
inverse relation)." What does "or the inverse relation" mean in this
case?"

Referring to the GRANT relationship between roles, the GRANT^-1
relationship is its inverse. The contained roles set is the transitive
closure of the GRANT^-1 relationship, cf definition of "contained
role" above. I guess you can just link to the definition of contained
role here.


* M src/ref/crefsqlj95081.dita

Good!

Shouldn't crefsqlj18919.html have an entry for roleName?

* M src/ref/rrefsistabssysroutineperms.dita

Good!

* A src/ref/rrefdroprole.dita

Good!

* M src/ref/rrefsistabssyscolperms.dita

Good!

* M src/ref/rrefsqlj30540.dita

Good!

* M src/ref/rrefsqlj31580.dita

Good!

* M src/ref/rrefsqljgrant.dita

Good!

M src/ref/refderby.ditamap

Good!

* M src/tools/rtoolsijcomrefshow.dita

> SHOW ROLES displays all the roles in the current session. That is,
  it shows all roles that have been created.

Not just in current session, this is misleading. Just say:

"SHOW ROLES displays the names of all roles created, whether
settable available for the current session or not."

> SHOW ENABLED ROLES displays all the enabled roles in the current
  session. That is, it shows all roles that have been both created and
  set.

SHOW ENABLED ROLES displays all the roles whose privileges are
available for the current session.  That is, it shows the current role
and any role granted to the current role etc (contained roles, see
definition).


> SHOW SETTABLE ROLES displays all the settable roles in the current
  session. That is, it shows all roles that have been created but have
  not been set. 

SHOW SETTABLE ROLES displays all the roles that the current session
can set, that is, all roles that have been granted to the current
user.

Example:

ij> show roles;
ROLEID                        
------------------------------
CASUALUSER                             
ANYUSER                             
POWERUSER                             

3 rows selected

ij> show enabled roles;
ROLEID                        
------------------------------
CASUALUSER                             
ANYUSER                             

2 rows selected

ij> show settable roles;
ROLEID                        
------------------------------
CASUALUSER                             
POWERUSER

2 rows selected

In the examples above, presumably, both CASUALUSER and POWERUSER
contains ANYUSER, but ANYUSER is not settable directly.


> 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
>
>         Attachments: DERBY-3193-2.diff, DERBY-3193-2.stat, DERBY-3193-2.zip, DERBY-3193.diff, DERBY-3193.stat, DERBY-3193.zip, derby3193-tmp.diff, derby3193-tmp.stat
>
>


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