Updated SQL statements for new role options

_includes/v20.2/sql/privileges.md

@@ -0,0 +1,13 @@
+You can manage the following privileges for databases and tables:
+
+Privilege | Levels
+----------|------------
+`ALL` | Database, Table
+`CREATE` | Database, Table
+`DROP` | Database, Table
+`GRANT` | Database, Table
+`SELECT` | Table
+`INSERT` | Table
+`DELETE` | Table
+`UPDATE` | Table
+`ZONECONFIG` | Database, Table

v20.2/alter-role.md

@@ -4,7 +4,7 @@ summary: The ALTER ROLE statement can be used to add or change a role's password
 toc: true
 ---
 
- The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or remove a [role's](create-role.html) password and to change the login privileges for a role.
+ The `ALTER ROLE` [statement](sql-statements.html) can be used to add, change, or remove a [role's](create-role.html) password and to change the privileges for a role.
 
 {{site.data.alerts.callout_info}}
 Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER ROLE` is now an alias for [`ALTER USER`](alter-user.html).
@@ -16,7 +16,7 @@ Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL stat
 
 ## Required privileges
 
- To alter other roles, the role must have the [`CREATEROLE`](create-role.html#allow-the-role-to-create-other-roles) parameter set.
+ To alter other roles, the role must be a member of the `admin` role or have the [`CREATEROLE`](create-role.html#create-a-role-that-can-create-other-roles-and-manage-authentication-methods-for-the-new-roles) parameter set.
 
 ## Synopsis
 
@@ -32,14 +32,85 @@ table td:first-child {
 
 Parameter | Description
 ----------|-------------
-`name` | The name of the role whose password you want to create or add.
-`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier). <br><br>To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication).
+`name` | The name of the role whose role options you want to alter.
+`CREATELOGIN`/`NOCREATELOGIN` | Allow or disallow the role to manage authentication using the `WITH PASSWORD`, `VALID UNTIL`, and `LOGIN/NOLOGIN` parameters. <br><br>By default, the parameter is set to `NOCREATELOGIN` for all non-admin roles.
+`LOGIN`/`NOLOGIN` | The `LOGIN` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). Setting the parameter to `NOLOGIN` prevents the role from logging in using any authentication method.
+`password` | Let the role [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an identifier. <br><br>To prevent a role from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-role-from-using-password-authentication).
 `VALID UNTIL` | The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid.
-`LOGIN`/`NOLOGIN` | The `LOGIN` parameter allows a role to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `NOLOGIN`](#change-login-privileges-for-a-role) prevents the role from logging in using any authentication method.
-`CREATEROLE`/`NOCREATEROLE` | Allow or disallow the role to create, alter, and drop other roles. <br><br>By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root roles.
+`CREATEROLE`/`NOCREATEROLE` | Allow or disallow the role to create, alter, and drop other non-admin roles. <br><br>By default, the parameter is set to `NOCREATEROLE` for all non-admin roles.
+`CREATEDB`/`NOCREATEDB` | Allow or disallow the role to create or rename a database. The role is assigned as the owner of the database. <br><br>By default, the parameter is set to `NOCREATEDB` for all non-admin roles.
+`CONTROLJOB`/`NOCONTROLJOB` | Allow or disallow the role to pause, resume, and cancel jobs. Non-admin roles cannot control jobs created by admins. <br><br>By default, the parameter is set to `NOCONTROLJOB` for all non-admin roles.
+`CANCELQUERY`/`NOCANCELQUERY` | Allow or disallow the role to cancel queries and sessions of other roles. Without this privilege, roles can only cancel their own queries and sessions. Even with this privilege, non-admins cannot cancel admin queries or sessions. This option should usually be combined with `VIEWACTIVITY` so that the role can view other roles' query and session information. <br><br>By default, the parameter is set to `NOCANCELQUERY` for all non-admin roles.
+`VIEWACTIVITY`/`NOVIEWACTIVITY` | Allow or disallow a role to see other roles' queries and sessions using `SHOW QUERIES`, `SHOW SESSIONS`, and the Statements and Transactions pages in the Admin UI. Without this privilege, the `SHOW` commands only show the role's own data and the Admin UI pages are unavailable. <br><br>By default, the parameter is set to `NOVIEWACTIVITY` for all non-admin roles.
+`CONTROLCHANGEFEED`/`NOCONTROLCHANGEFEED` | Allow or disallow the role to run `CREATE CHANGEFEED` on tables they have `SELECT` privileges on. <br><br>By default, the parameter is set to `NOCONTROLCHANGEFEED` for all non-admin roles.
+`MODIFYCLUSTERSETTING`/`NOMODIFYCLUSTERSETTING` | Allow or disallow the role to to modify the cluster settings with the `sql.defaults` prefix. <br><br>By default, the parameter is set to `NOMODIFYCLUSTERSETTING` for all non-admin roles.
 
 ## Examples
 
+{{site.data.alerts.callout_info}}
+The following statements are run by the `root` user that is a member of the `admin` role and has `ALL` privileges.
+{{site.data.alerts.end}}
+
+### Allow a role to log in to the database using a password
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH LOGIN PASSWORD 'An0ther$tr0nGpassW0rD' VALID UNTIL '2021-10-10';
+~~~
+
+### Prevent a role from using password authentication
+
+The following statement prevents the user from using password authentication and mandates certificate-based client authentication:
+
+{% include copy-clipboard.html %}
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH PASSWORD NULL;
+~~~
+
+### Allow a role to create other roles and manage authentication methods for the new roles
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH CREATEROLE;
+~~~
+
+### Allow a role to only manage authentication for other roles
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH CREATELOGIN;
+~~~
+
+### Allow a role to create and rename databases
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH CREATEDB;
+~~~
+
+### Allow a role to pause, resume, and cancel non-admin jobs
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH CONTROLJOB;
+~~~
+
+### Allow a role to see and cancel non-admin queries and sessions
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH CANCELQUERY VIEWACTIVITY;
+~~~
+
+### Allow a role to control changefeeds
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH CONTROLCHANGEFEED;
+~~~
+
+### Allow a role to modify cluster settings
+
+~~~ sql
+root@:26257/defaultdb> ALTER ROLE carl WITH MODIFYCLUSTERSETTING;
+~~~
+
+
+<!--
+
 ### Change password using a string literal
 
 {% include copy-clipboard.html %}
@@ -169,6 +240,8 @@ The following statement allows the role to log in with one of the client authent
 (3 rows)
 ~~~
 
+-->
+
 
 ## See also
 

v20.2/alter-user.md

@@ -4,7 +4,7 @@ summary: The ALTER USER statement can be used to add or change a user's password
 toc: true
 ---
 
-The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or remove a [user's](create-user.html) password and to change the login privileges for a user.
+The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or remove a [user's](create-user.html) password and to change the role options for a user.
 
 {{site.data.alerts.callout_info}}
  Since the keywords `ROLE` and `USER` can now be used interchangeably in SQL statements for enhanced Postgres compatibility, `ALTER USER` is now an alias for [`ALTER ROLE`](alter-role.html).
@@ -16,7 +16,7 @@ The `ALTER USER` [statement](sql-statements.html) can be used to add, change, or
 
 ## Required privileges
 
- To alter other users, the user must have the [`CREATEROLE`](create-user.html#allow-the-user-to-create-other-users) parameter set.
+ To alter other users, the user must be a member of the `admin` role or have the [`CREATEROLE`](create-user.html#create-a-user-that-can-create-other-users-and-manage-authentication-methods-for-the-new-users) parameter set.
 
 ## Synopsis
 
@@ -32,14 +32,84 @@ table td:first-child {
 
 Parameter | Description
 ----------|-------------
-`name` | The name of the user whose password you want to create or add.
-`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an [identifier](#change-password-using-an-identifier). <br><br>To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication).
+`name` | The name of the user whose role options you want to alter.
+`CREATELOGIN`/`NOCREATELOGIN` | Allow or disallow the user to manage authentication using the `WITH PASSWORD`, `VALID UNTIL`, and `LOGIN/NOLOGIN` parameters. <br><br>By default, the parameter is set to `NOCREATELOGIN` for all non-admin users.
+`LOGIN`/`NOLOGIN` | The `LOGIN` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). Setting the parameter to `NOLOGIN` prevents the user from logging in using any authentication method.
+`password` | Let the user [authenticate their access to a secure cluster](authentication.html#client-authentication) using this new password. Passwords should be entered as a [string literal](sql-constants.html#string-literals). For compatibility with PostgreSQL, a password can also be entered as an identifier. <br><br>To prevent a user from using [password authentication](authentication.html#client-authentication) and to mandate [certificate-based client authentication](authentication.html#client-authentication), [set the password as `NULL`](#prevent-a-user-from-using-password-authentication).
 `VALID UNTIL` |  The date and time (in the [`timestamp`](timestamp.html) format) after which the password is not valid.
-`LOGIN`/`NOLOGIN` |  The `LOGIN` parameter allows a user to login with one of the [client authentication methods](authentication.html#client-authentication). [Setting the parameter to `NOLOGIN`](#change-login-privileges-for-a-user) prevents the user from logging in using any authentication method.
-`CREATEROLE`/`NOCREATEROLE` |  Allow or disallow the user to create, alter, and drop other users. <br><br>By default, the parameter is set to `NOCREATEROLE` for all non-admin and non-root users.
+`CREATEROLE`/`NOCREATEROLE` |  Allow or disallow the user to create, alter, and drop other non-admin users. <br><br>By default, the parameter is set to `NOCREATEROLE` for all non-admin users.
+`CREATEDB`/`NOCREATEDB` | Allow or disallow the user to create or rename a database. The user is assigned as the owner of the database. <br><br>By default, the parameter is set to `NOCREATEDB` for all non-admin users.
+`CONTROLJOB`/`NOCONTROLJOB` | Allow or disallow the user to pause, resume, and cancel jobs. Non-admin users cannot control jobs created by admins. <br><br>By default, the parameter is set to `NOCONTROLJOB` for all non-admin users.
+`CANCELQUERY`/`NOCANCELQUERY` | Allow or disallow the user to cancel queries and sessions of other users. Without this privilege, users can only cancel their own queries and sessions. Even with this privilege, non-admins cannot cancel admin queries or sessions. This option should usually be combined with `VIEWACTIVITY` so that the user can view other users' query and session information. <br><br>By default, the parameter is set to `NOCANCELQUERY` for all non-admin users.
+`VIEWACTIVITY`/`NOVIEWACTIVITY` | Allow or disallow a role to see other users' queries and sessions using `SHOW QUERIES`, `SHOW SESSIONS`, and the Statements and Transactions pages in the Admin UI. Without this privilege, the `SHOW` commands only show the user's own data and the Admin UI pages are unavailable. <br><br>By default, the parameter is set to `NOVIEWACTIVITY` for all non-admin users.
+`CONTROLCHANGEFEED`/`NOCONTROLCHANGEFEED` | Allow or disallow the user to run `CREATE CHANGEFEED` on tables they have `SELECT` privileges on. <br><br>By default, the parameter is set to `NOCONTROLCHANGEFEED` for all non-admin users.
+`MODIFYCLUSTERSETTING`/`NOMODIFYCLUSTERSETTING` | Allow or disallow the user to to modify the cluster settings with the `sql.defaults` prefix. <br><br>By default, the parameter is set to `NOMODIFYCLUSTERSETTING` for all non-admin users.
 
 ## Examples
 
+{{site.data.alerts.callout_info}}
+The following statements are run by the `root` user that is a member of the `admin` role and has `ALL` privileges.
+{{site.data.alerts.end}}
+
+### Change a user's password
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH PASSWORD 'An0ther$tr0nGpassW0rD' VALID UNTIL '2021-10-10';
+~~~
+
+### Prevent a user from using password authentication
+
+The following statement prevents the user from using password authentication and mandates certificate-based client authentication:
+
+{% include copy-clipboard.html %}
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH PASSWORD NULL;
+~~~
+
+### Allow a user to create other users and manage authentication methods for the new users
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH CREATEROLE;
+~~~
+
+### Allow a user to only manage authentication for other users
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH CREATELOGIN;
+~~~
+
+### Allow a user to create and rename databases
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH CREATEDB;
+~~~
+
+### Allow a user to pause, resume, and cancel non-admin jobs
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH CONTROLJOB;
+~~~
+
+### Allow a user to see and cancel non-admin queries and sessions
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH CANCELQUERY VIEWACTIVITY;
+~~~
+
+### Allow a user to control changefeeds
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH CONTROLCHANGEFEED;
+~~~
+
+### Allow a user to modify cluster settings
+
+~~~ sql
+root@:26257/defaultdb> ALTER USER carl WITH MODIFYCLUSTERSETTING;
+~~~
+
+<!--
+
 ### Change password using a string literal
 
 {% include copy-clipboard.html %}
@@ -134,6 +204,8 @@ The following statement allows the user to log in with one of the client authent
 (3 rows)
 ~~~
 
+-->
+
 ## See also
 
 - [`DROP USER`](drop-user.html)

v20.2/authorization.md

@@ -118,16 +118,7 @@ Take the following points into consideration while granting privileges to roles
 - The `root` user automatically belongs to the `admin` role and has the `ALL` privilege for new databases.
 - For privileges required by specific statements, see the documentation for the respective [SQL statement](sql-statements.html).
 
-You can manage the following privileges for databases and tables:
-
-- `ALL`
-- `CREATE`
-- `DROP`
-- `GRANT`  
-- `SELECT`  
-- `INSERT`  
-- `DELETE`  
-- `UPDATE`  
+{% include {{ page.version.version }}/sql/privileges.md %}
 
 ## Authorization best practices
 
@@ -189,7 +180,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-          database_name |    schema_name     |         table_name         | grantee  | privilege_type  
+      database_name |    schema_name     |         table_name         | grantee  | privilege_type  
     +---------------+--------------------+----------------------------+----------+----------------+
       movr          | crdb_internal      | NULL                       | db_admin | ALL             
       movr          | information_schema | NULL                       | db_admin | ALL             
@@ -222,7 +213,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-          database_name | schema_name | table_name | grantee  | privilege_type  
+      database_name | schema_name | table_name | grantee  | privilege_type  
     +---------------+-------------+------------+----------+----------------+
       movr          | public      | vehicles   | app_user | DELETE          
       movr          | public      | vehicles   | app_user | INSERT          
@@ -287,7 +278,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-            username    |  options   | member_of
+        username    |  options   | member_of
     ----------------+------------+------------
       admin         | CREATEROLE | {}
       db_admin_role | NOLOGIN    | {}
@@ -311,7 +302,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-          database_name |    schema_name     |    grantee    | privilege_type
+      database_name |    schema_name     |    grantee    | privilege_type
     ----------------+--------------------+---------------+-----------------
       movr          | crdb_internal      | admin         | ALL
       movr          | crdb_internal      | db_admin_role | ALL
@@ -358,7 +349,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-            username    |  options   |    member_of
+        username    |  options   |    member_of
     ----------------+------------+------------------
       admin         | CREATEROLE | {}
       app_user_role | NOLOGIN    | {}
@@ -380,7 +371,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-          database_name | schema_name | table_name |    grantee    | privilege_type
+      database_name | schema_name | table_name |    grantee    | privilege_type
     ----------------+-------------+------------+---------------+-----------------
       movr          | public      | vehicles   | admin         | ALL
       movr          | public      | vehicles   | app_user_role | DELETE
@@ -427,7 +418,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-              username     |  options   |    member_of
+          username     |  options   |    member_of
     -------------------+------------+------------------
       admin            | CREATEROLE | {}
       app_user_1       |            | {app_user_role}
@@ -453,7 +444,7 @@ Let's say we want to create the following access control setup for the `movr` da
     ~~~
 
     ~~~
-          database_name | schema_name | table_name |     grantee      | privilege_type
+      database_name | schema_name | table_name |     grantee      | privilege_type
     ----------------+-------------+------------+------------------+-----------------
       movr          | public      | vehicles   | admin            | ALL
       movr          | public      | vehicles   | app_user_role    | DELETE