Merge pull request #99919 from jonels-msft/role-mgmt-back

Restore role mgmt howto to TOC

Author: v-shils

articles/postgresql/TOC.yml

@@ -281,6 +281,8 @@
         href: howto-read-replicas-cli.md
   - name: Hyperscale (Citus)
     items:
+    - name: Create users
+      href: howto-hyperscale-create-users.md
     - name: Scale
       href: howto-hyperscale-scaling.md
     - name: Manage firewall

articles/postgresql/howto-hyperscale-create-users.md

@@ -5,39 +5,54 @@ author: jonels-msft
 ms.author: jonels
 ms.service: postgresql
 ms.topic: conceptual
-ms.date: 11/04/2019
+ms.date: 1/8/2019
 ---
 
 # Create users in Azure Database for PostgreSQL - Hyperscale (Citus)
 
-This article describes how you can create users within a Hyperscale (Citus)
-server group. To learn instead about Azure subscription users and their
-privileges, visit the [Azure role based access control (RBAC)
-article](../role-based-access-control/built-in-roles.md) or review [how to
-customize roles](../role-based-access-control/custom-roles.md).
+> [!NOTE]
+> The term "users" refers to users within a Hyperscale (Citus)
+> server group. To learn instead about Azure subscription users and their
+> privileges, visit the [Azure role based access control (RBAC)
+> article](../role-based-access-control/built-in-roles.md) or review [how to
+> customize roles](../role-based-access-control/custom-roles.md).
 
 ## The server admin account
 
-A newly created Hyperscale (Citus) server group comes with several roles
-pre-defined:
+The PostgreSQL engine uses
+[roles](https://www.postgresql.org/docs/current/sql-createrole.html) to control
+access to database objects, and a newly created Hyperscale (Citus) server group
+comes with several roles pre-defined:
 
 * The [default PostgreSQL roles](https://www.postgresql.org/docs/current/default-roles.html)
-* *azure_pg_admin*
-* *postgres*
-* *citus*
+* `azure_pg_admin`
+* `postgres`
+* `citus`
 
-The PostgreSQL engine uses privileges to control access to database objects, as
-discussed in the [PostgreSQL product
-documentation](https://www.postgresql.org/docs/current/static/sql-createrole.html).
-Your server admin user, *citus*, is a member of the *azure_pg_admin* role.
-However, it isn't part of the *postgres* (super user) role.  Since Hyperscale
-is a managed PaaS service, only Microsoft is part of the super user role. The
-*citus* user has limited permissions and can't e.g. create new databases.
+Since Hyperscale is a managed PaaS service, only Microsoft can sign in with the
+`postgres` super user role. For limited administrative access, Hyperscale
+provides the `citus` role.
 
-## How to create additional users
+Permissions for the `citus` role:
 
-The *citus* admin account lacks permission to create additional users. To
-add a user, use the Azure portal interface.
+* Read all configuration variables, even variables normally visible only to
+  superusers.
+* Read all pg\_stat\_\* views and use various statistics-related extensions --
+  even views or extensions normally visible only to superusers.
+* Execute monitoring functions that may take ACCESS SHARE locks on tables,
+  potentially for a long time.
+* [Create PostgreSQL extensions](concepts-hyperscale-extensions.md) (because
+  the role is a member of `azure_pg_admin`).
+
+Notably, the `citus` role has some restrictions:
+
+* Can't create roles
+* Can't create databases
+
+## How to create additional user roles
+
+As mentioned, the `citus` admin account lacks permission to create additional
+users. To add a user, use the Azure portal interface.
 
 1. Go to the **Roles** page for your Hyperscale server group, and click **+ Add**:
 
@@ -48,36 +63,28 @@ add a user, use the Azure portal interface.
    ![Add role](media/howto-hyperscale-create-users/2-add-user-fields.png)
 
 The user will be created on the coordinator node of the server group,
-and propagated to all the worker nodes.
-
-## How to delete a user or change their password
-
-Go to the **Roles** page for your Hyperscale server group, and click the
-ellipses **...** next to a user. The ellipses will open a menu to delete
-the user or reset their password.
-
-   ![Edit a role](media/howto-hyperscale-create-users/edit-role.png)
-
-The *citus* role is privileged and can't be deleted.
+and propagated to all the worker nodes. Roles created through the Azure
+portal have the `LOGIN` attribute, which means they are true users who
+can sign in to the database.
 
-## How to modify privileges for role
+## How to modify privileges for user role
 
-New roles are commonly used to provide database access with restricted
+New user roles are commonly used to provide database access with restricted
 privileges. To modify user privileges, use standard PostgreSQL commands, using
 a tool such as PgAdmin or psql. (See [connecting with
 psql](quickstart-create-hyperscale-portal.md#connect-to-the-database-using-psql)
 in the Hyperscale (Citus) quickstart.)
 
-For example, to allow *db_user* to read *mytable*, grant the permission:
+For example, to allow `db_user` to read `mytable`, grant the permission:
 
 ```sql
 GRANT SELECT ON mytable TO db_user;
 ```
 
 Hyperscale (Citus) propagates single-table GRANT statements through the entire
 cluster, applying them on all worker nodes. However GRANTs that are system-wide
-(e.g. for all tables in a schema) need to be run on every date node.  Use the
-*run_command_on_workers()* helper function:
+(for example, for all tables in a schema) need to be run on every date node.  Use the
+`run_command_on_workers()` helper function:
 
 ```sql
 -- applies to the coordinator node
@@ -89,6 +96,16 @@ SELECT run_command_on_workers(
 );
 ```
 
+## How to delete a user role or change their password
+
+To update a user, visit the **Roles** page for your Hyperscale server group,
+and click the ellipses **...** next to the user. The ellipses will open a menu
+to delete the user or reset their password.
+
+   ![Edit a role](media/howto-hyperscale-create-users/edit-role.png)
+
+The `citus` role is privileged and can't be deleted.
+
 ## Next steps
 
 Open the firewall for the IP addresses of the new users' machines to enable