Merge pull request #299021 from AbhishekMallick01/Apr-29-2025-PSQLFlex

PSQL Flex DB restore updates

Author: v-ccolin

articles/backup/backup-azure-database-postgresql-flex-support-matrix.md

@@ -2,7 +2,7 @@
 title: Azure Database for PostgreSQL- Flexible server support matrix
 description: Provides a summary of support settings and limitations of Azure Database for PostgreSQL- Flexible server backup.
 ms.topic: reference
-ms.date: 04/11/2025
+ms.date: 04/30/2025
 ms.custom: references_regions, ignite-2024
 ms.service: azure-backup
 author: jyothisuri
@@ -41,6 +41,22 @@ Azure Database for PostgreSQL – Flexible Server backups include the following
 - Vaulted backups support full backups only; incremental or differential backups aren't supported.
 
 
+### Restore limitations
+- The use of **create role** scripts for `azure_su`, `azure_pg_admin`, `replication`, `localadmin`, and `Entra Admin` causes the following errors  during restoration on another flexible server, which you can safely ignore.
+
+  - `role "azure_pg_admin" already exists.`
+  - `role "azuresu" already exists.`
+  - `role "replication" already exists.`
+  - `ERROR: must be superuser to create superusers`
+  - `ERROR: Only roles with privileges of role "azuresu" may grant privileges as this role. permission denied granting privileges as role "azuresu"`
+  - `ERROR: permission denied granting privileges as role "azuresu" SQL state: 42501 Detail: Only roles with privileges of role "azuresu" may grant privileges.`
+  - `Ignore any errors related to pg_catalog, pg _aadauth extensions as it is owned by azure_su and localadmin does not have access to directly create this extension on flexible server, but these are automatically created on new flexible servers or when you enable Microsoft entra authentication.`
+  - `ERROR: Only roles with the ADMIN option on role "pg_use_reserved_connections" may grant this role. permission denied to grant role "pg_use_reserved_connections"`
+  - `ERROR: permission denied to grant role "pg_use_reserved_connections" SQL state: 42501 Detail: Only roles with the ADMIN option on role "pg_use_reserved_connections" may grant this role.`
+
+- In PostgreSQL **community version 16**, the requirement for superuser privileges to set the Bypass Row -level security (RLS) attribute was removed. So, in versions 16 and higher, you can grant the Bypass RLS to azure_pg_admin allowing others to set the RLS. For versions lower than 16, the bypasses attribute is granted only to the server admin and no other nonsuperuser roles. 
+- If you're using Entra Admins after restoration, you might encounter the **Owner Change Issue** : As a workaround, use the **grant** option to provide ownership. 
+
 
 ## Next steps
 

articles/backup/media/restore-azure-database-postgresql-flex/database-files.png

@@ -1,18 +1,18 @@
 ---
-title: Restore Azure Database for PostgreSQL -Flexible server using Azure portal
-description: Learn about how to restore Azure Database for PostgreSQL -Flexible backups.
+title: Restore Azure PostgreSQL-Flexible server as Files using Azure portal
+description: Learn about how to restore Azure PostgreSQL-Flexible server as Files.
 ms.topic: how-to
-ms.date: 03/18/2025
+ms.date: 04/30/2025
 ms.service: azure-backup
 ms.custom:
   - ignite-2024
 author: jyothisuri
 ms.author: jsuri
 ---
 
-# Restore Azure Database for PostgreSQL - Flexible Server using Azure portal
+# Restore Azure PostgreSQL-Flexible server as Files using Azure portal
 
-This article describes how to restore an Azure PostgreSQL -Flexible Server backed up using Azure portal.
+This article describes how to restore an Azure PostgreSQL-Flexible server as Files backed up using Azure portal.
 
 ## Prerequisites
 
@@ -26,7 +26,10 @@ Before you restore from Azure Database for PostgreSQL Flexible server backups, r
 
 ## Restore Azure PostgreSQL-Flexible database
 
-Follow these steps:
+>[!Note]
+>The restore operation transfers all PostgreSQL – flexible server databases to a designated storage account container. After restoration, move the files to a new or existing PostgreSQL – Flexible server.
+
+To restore Azure PostgreSQL-Flexible database, Follow these steps:
 
 1. Go to **Backup vault** > **Backup Instances**. Select the PostgreSQL - Flexible server to be restored and select **Restore**.
 
@@ -49,41 +52,76 @@ Follow these steps:
 1. Submit the Restore operation and track the triggered job under **Backup jobs**.
    :::image type="content" source="./media/restore-azure-database-postgresql-flex/validate.png" alt-text="Screenshot showing the validate process page.":::
 
-1. Once the job is finished, the backed-up data is restored into the storage account. Below are the set of files recovered in your storage account after the restore:
 
-   - The first file is a marker or timestamp file that gives the customer the time the backup was taken at. The file cannot be restored but if opened with a text editor should tell the customer the UTC time when the backup was taken.
-     
-   - The Second file **_database_** is an individual database backup for database called tempdata2 taken using pg_dump. Each database has a separate file with format **– {backup_name}_database_{db_name}.sql**
-     
-   - The Third File **_roles**. Has roles backed up using pg_dumpall
- 
-   - The Fourth file **_schemas**. backed up using pg_dumpall
-     
-   - The Fifth file **_tablespaces**. Has the tablespaces backed up using pg_dumpall
+After the restore job is completed successfully, go to the storage account container to view the restored databases as files (`.sql` files) from your PostgreSQL – Flexible server. Azure Backup also generates the following backup files:
 
-1. Post restoration completion to the target storage account, you can use pg_restore utility to restore the database and other files to a PostgreSQL Flexible server. Use the following command to connect to an existing postgresql flexible server and an existing database
+- `Database.sql file` per database: Contains data and schema information for a particular database.  
+- `Roles.sql files` for entire instance: Contains all  role information ((azure_su(superuser) azure_pg_admin, replication, local admin, Microsoft Entra admins and any other custom roles on the server)) that exists at server level.
+- `Tablespace.sql file`: Tablespace file.
+- `Schema.sql file`: Contains schema information for all the databases on the server.
 
-   `az storage blob download --container-name <container-name> --name <blob-name> --account-name <storage-account-name> --account-key <storage-account-key> --file - | pg_restore -h <postgres-server-url> -p <port> -U <username> -d <database-name> -v -`
+  >[!Note]
+  >We recommend you not to run this script on the PostgreSQL - Flexible server because the schema is already part of the `database.sql` script. 
 
-   * `--account-name`: Name of the Target Storage Account.
-   * `--container-name`: Name of the blob container.
-   * `--blob-name`: Name of the blob.
-   * `--account-key`: Storage Account Key.
-   * `-Fd`: The directory format.   
-   * `-j`: The number of jobs.   
-   * `-C`: Begin the output with a command to create the database itself and then reconnect to it.     
+:::image type="content" source="./media/restore-azure-database-postgresql-flex/database-files.png" alt-text="Screenshot shows the database schema per database." lightbox="./media/restore-azure-database-postgresql-flex/database-files.png":::
 
-   If you have more than one database to restore, re-run the earlier command for each database.
+## Restore the backup files from storage container to a new or existing PostgreSQL – Flexible server
 
-   Also, by using multiple concurrent jobs `-j`, you can reduce the time it takes to restore a large database on a multi-vCore target server. The number of jobs can be equal to or less than the number of vCPUs that are allocated for the target server.
+To restore the backup files from storage container to a new or existing PostgreSQL – Flexible server, follow these steps:
 
-1. To restore the other three files (roles, schema and tablespaces), use the psql utility to restore them to a PostgreSQL Flexible server.
+1. Ensure that all required [extensions are enabled](/azure/postgresql/extensions/how-to-allow-extensions?tabs=allow-extensions-portal) on the new target Flexible server. 
+1. [Match the server parameter](/azure/postgresql/flexible-server/how-to-server-parameters-list-all?tabs=portal-list) values from the source PostgreSQL database to the Azure Database for PostgreSQL by accessing the **Server parameters** section in the Azure portal and manually updating the values accordingly. Save the parameter changes, and then restart the Azure Database for PostgreSQL - Flexible server to apply the new configuration. 
+1. If **Microsoft Entra Authentication** is required on the new server, enable it and create the relevant Microsoft Entra admins. 
+1. Create a new database for restoration.
 
-    `az storage blob download --container-name <container-name> --name <blob-name> --account-name <storage-account-name> --account-key <storage-account-key> --file - 
-     | psql -h <hostname> -U <username> -d <db name> -f <dump directory> -v -`
+   >[!Note]
+   >Before the database restoration, you must create a new, empty database. Ensure that your user account has the **`CREATEDB`** permission.  
+   >
+   >To create the database, use the `CREATE DATABASE Database_name` command.
 
-   Re-run the above command for each file.
+1. Restore the database using the `database.sql file` as the target admin user.
+1.After the target database is created, restore the data in this database (from the dump file) from an Azure storage account by running the following command:
+
+   ```azurecli-interactive
+   az storage blob download --container-name <container-name> --name <blob-name> --account-name <storage-account-name> --account-key <storage-account-key> --file - | pg_restore -h <postgres-server-url> -p <port> -U <username> -d <database-name> --no-owner -v – 
+   ```
+   
+   - `--account-name`: Name of the Target Storage Account. 
+   - `--container-name`: Name of the blob container. 
+   - `--blob-name`: Name of the blob. 
+   - `--account-key`: Storage Account Key. 
+   - `-Fd`: The directory format. 
+   - `-j`: The number of jobs. 
+   - `-C`: Begin the output with a command to create the database itself and then reconnect to it. 
 
-## Next steps
+   Alternatively, you can download the backup file and run the restore directly. 
+
+1. Restore only the required roles and privileges, and ignore the [common errors](backup-azure-database-postgresql-flex-support-matrix.md#restore-limitations). Skip this step if you're performing the restoration for compliance requirements and data retrieval, as a local admin.
+
+## Restore roles and users for the restored databases
+
+Vaulted backups are primarily restored for compliance needs such as, testing and audits. You can sign in as a local admin and restore using the `database.sql` file; no other roles are needed for data retrieval.
+
+For other uses like accidental deletion protection or disaster recovery, ensure necessary roles are created as per your organization needs. Avoid duplications between `roles.sql` and `database.sql`.
+ 
+- **Restore the same Flexible server**: Role restoration might not be necessary. 
+- **Restore to a different Flexible server**: Use the `roles.sql` file to recreate the required roles. 
+
+When you restore from `roles.sql`, some roles or attributes might not be valid for the new target server.
+
+For environments with superuser access (on-premises or VMs), you can run all commands seamlessly.
+
+### Key considerations for the Flexible server scenario
+
+Here are the key considerations:
+
+- **Remove Superuser-Only Attributes**: On Flexible server, there's no superuser privileges. So, remove attributes, such as `NOSUPERUSER` and `NOBYPASSRLS` from the roles dump. 
+- **Exclude Service-Specific Users**: Exclude users specific to Flexible Server services (` azure_su`, `azure_pg_admin`, `replication`, `localadmin`, `Entra Admin`). These specific service roles are automatically recreated when administrators are added to the new Flexible server. 
+
+Before you restore the database objects, ensure that you properly dump and clean up the roles. To perform this action, download the `roles.sql`script from your storage container and create all required logins. 
+- **Create Non-Entra Roles**: Use a local admin account to run the role creation scripts. 
+- **Create Microsoft Entra Roles**: If you need to create roles for Microsoft Entra users, use a Microsoft Entra administrator account to run the necessary scripts. 
+                          
+ ## Next steps
 
 [Manage backup of Azure PostgreSQL - Flexible Server using Azure portal](backup-azure-database-postgresql-flex-manage.md).