Bug #118721 Improve documentation for CREATE / ALTER USER syntax related to comments and user_attributes

• Submitted: 26 Jul 9:40
• Modified: 27 Jul 10:44
• Reporter: Simon Mudd (OCA)
• Status: Not a Bug
• Category: MySQL Server: Documentation
• Severity: S3 (Non-critical)
• Version: 8.0, 8.4, 9.x
• OS: Any
• CPU Architecture: Any

[26 Jul 9:40] Simon Mudd

Description:
I thought that it was not possible in CREATE USER / ALTER USER statements to modify the User_attribute JSON field.

Looking at https://dev.mysql.com/doc/refman/8.4/en/create-user.html the overview of the syntax at the top of the page makes no mention to `COMMENT` or `ATTRIBUTE` so it is easy to overlook further down the page a reference to "CREATE USER Comment and Attribute Options" which actually tell you that it is possible to configure or update these values.

This is somewhat confusing and it may be easily missed.

How to repeat:
Check the page 

https://dev.mysql.com/doc/refman/8.4/en/create-user.html
https://dev.mysql.com/doc/refman/8.4/en/alter-user.html

(this is the same in 8.0, 9.X)

Suggested fix:
I consider this a non-critical documentation bug.  Improving this documentation should be easy.

1. Improve the CREATE USER page to include at the top:

attribute_option: {
    ATTRIBUTE 'json_attribute'
}

comment_option: {
    COMMENT 'some comment'
}

2. Improve the ALTER USER page to include at the top:

attribute_option: {
    ATTRIBUTE 'json_attribute'
}

comment_option: {
    COMMENT 'some comment'
}

3. For the ALTER USER page indicate how best to "update" an existing user.User_attributes field using something like JSON_REPLACE() / JSON_MERGE... to only modify those values that needed to be changed while preserving the existing configured values.

[26 Jul 9:48] Simon Mudd

This affects both CREATE USER and ALTER USER syntax documentation.

[26 Jul 11:57] MySQL Verification Team

I see it here, or do I misunderstand the request:

https://dev.mysql.com/doc/refman/8.4/en/alter-user.html

ALTER USER [IF EXISTS]
    user [auth_option] [, user [auth_option]] ...
    [REQUIRE {NONE | tls_option [[AND] tls_option] ...}]
    [WITH resource_option [resource_option] ...]
    [password_option | lock_option] ...
    [COMMENT 'comment_string' | ATTRIBUTE 'json_object']
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

https://dev.mysql.com/doc/refman/8.4/en/create-user.html
CREATE USER [IF NOT EXISTS]
    user [auth_option] [, user [auth_option]] ...
    DEFAULT ROLE role [, role ] ...
    [REQUIRE {NONE | tls_option [[AND] tls_option] ...}]
    [WITH resource_option [resource_option] ...]
    [password_option | lock_option] ...
    [COMMENT 'comment_string' | ATTRIBUTE 'json_object']
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-- 
Shane Bester, MySQL Senior Principal Technical Support Engineer
Oracle Corporation
http://dev.mysql.com/

[27 Jul 10:34] Simon Mudd

Hm. I guess I missed this even if I did look multiple times.

My apologies. My error, clearly not a bug.