Public preview of migration of users/roles

Author: shriram-muthukrishnan

articles/postgresql/migrate/concepts-single-to-flexible.md

@@ -101,15 +101,35 @@ The following table shows the time for performing offline migrations for databas
 > [!IMPORTANT]  
 > In order to perform faster migrations, pick a higher SKU for your flexible server. You can always change the SKU to match the application needs post migration.
 
+## Migration of users/roles, ownerships and privileges
+Along with data migration, the tool automatically provides the following built-in capabilities:
+- Migration of users/roles present on your source server to the target server.
+- Migration of ownership of all the database objects on your source server to the target server.
+- Migration of permissions of database objects on your source server such as GRANTS/REVOKES to the target server.
+
+> [!NOTE]  
+> This functionality is enabled only for flexible servers in **North Europe** region. It will be enabled for flexible servers in other Azure regions soon. In the meantime, you can follow the steps mentioned in this [doc](../single-server/how-to-upgrade-using-dump-and-restore#migrate-the-roles) to perform user/roles migration
+
 ## Limitations
 
 - You can have only one active migration to your flexible server.
 - You can select a max of eight databases in one migration attempt. If you've more than eight databases, you must wait for the first migration to be complete before initiating another migration for the rest of the databases. Support for migration of more than eight databases in a single migration will be introduced later.
 - The source and target server must be in the same Azure region. Cross region migrations are not supported.
-- The tool takes care of the migration of data and schema. It doesn't migrate managed service features such as server parameters, connection security details, firewall rules, users, roles and permissions. In the later part of the document, we point you to docs that can help you perform the migration of users, roles and firewall rules from single server to flexible server.
+- The tool takes care of the migration of data and schema. It doesn't migrate managed service features such as server parameters, connection security details and firewall rules.
 - The migration tool shows the number of tables copied from source to target server. You need to validate the data in target server post migration.
 - The tool only migrates user databases and not system databases like template_0, template_1, azure_sys and azure_maintenance.
 
+> [!NOTE]  
+> The following limitations are applicable only for flexible servers on which the migration of users/roles functionality is enabled.
+
+- AAD users present on your source server will not be migrated to target server. To mitigate this limitation, manually create all AAD users on your target server using this [link](../flexible-server/how-to-manage-azure-ad-users.md) before triggering a migration. If AAD users are not created on target server, migration will fail with appropriate error message.
+- If the target flexible server uses SCRAM-SHA-256 password encrpytion method, connection to flexible server using the users/roles on single server will fail since the passwords are encrypted using md5 algorithm. To mitigate this limitation, please choose the option **MD5** for **password_encryption** server parameter on your flexible server.
+- Though the ownership of database objects such as tables, views, sequences, etc. are copied to the target server, the owner of the database in your target server will be the migration user of your target server. The limitation can be mitigated by executing the following command 
+
+```sql
+    ALTER DATABASE <dbname> OWNER TO <user>;
+```
+ Make sure the user executing the above command is a member of the user to which ownership is being assigned to. This limitation will be fixed in the upcoming releases of the migration tool to match the database owners on your source server.
 ## Experience
 
 Get started with the Single to Flex migration tool by using any of the following methods:
@@ -151,7 +171,7 @@ For calculating the total downtime to perform offline migration of production se
 > [!NOTE]  
 > The size of databases is not the right metric for validation.The source server might have bloats/dead tuples which can bump up the size on the source server. Also, the storage containers used in single and flexible servers are completely different. It is completely normal to have size differences between source and target servers. If there is an issue in the first three steps of validation, it indicates a problem with the migration.
 
-- **Migration of server settings** - The users, roles/privileges, server parameters, firewall rules (if applicable), tags, alerts need to be manually copied from single server to flexible server. Users and roles are migrated from Single to Flexible server by following the steps listed in this [doc](../single-server/how-to-upgrade-using-dump-and-restore.md).
+- **Migration of server settings** - The server parameters, firewall rules (if applicable), tags, alerts need to be manually copied from single server to flexible server.
 
 - **Changing connection strings** - Post successful validation, application should change their connection strings to point to flexible server. This activity is coordinated with the application team to make changes to all the references of connection strings pointing to single server. Note that in the flexible server the user parameter in the connection string no longer needs to be in the **username@servername** format. You should just use the **user=username** format for this parameter in the connection string
 For example
@@ -229,6 +249,25 @@ The changes to this server parameter would require a server restart to come into
 
 Use the **Save and Restart** option and wait for the postgresql server to restart.
 
+> [!NOTE]  
+> The following pre-requisite is applicable only for flexible servers on which the migration of users/roles functionality is enabled.
+##### Create AAD users on target server
+Execute the following query on your source server to get the list of AAD users.
+```sql
+SELECT r.rolname
+	FROM
+	  pg_roles r
+	  JOIN pg_auth_members am ON r.oid = am.member
+	  JOIN pg_roles m ON am.roleid = m.oid
+	WHERE
+	  m.rolname IN (
+		'azure_ad_admin',
+		'azure_ad_user',
+		'azure_ad_mfa'
+	  );
+``` 
+Create the AAD users on your target flexible server using this [link](../flexible-server/how-to-manage-azure-ad-users.md) before creating a migration.
+
 ### Migration
 
 Once the pre-migration steps are complete, you're ready to carry out the migration of the production databases of your single server. At this point, you've finalized the day and time of production migration along with a planned downtime for your applications.
@@ -264,7 +303,6 @@ If the above conditions are met, the table will be migrated in multiple partitio
 - Once the migration is complete, verify the data on your flexible server and make sure it's an exact copy of the single server.
 - Post verification, enable HA option as needed on your flexible server.
 - Change the SKU of the flexible server to match the application needs. This change needs a database server restart.
-- Migrate users and roles from single to flexible servers. This step can be done by creating users on flexible servers and providing them with suitable privileges or by using the steps that are listed in this [doc](../single-server/how-to-upgrade-using-dump-and-restore.md).
 - If you've changed any server parameters from their default values in single server, copy those server parameter values in flexible server.
 - Copy other server settings like tags, alerts, firewall rules (if applicable) from single server to flexible server.
 - Make changes to your application to point the connection strings to flexible server.