Merge pull request #265148 from mulander/flex-azure-extension-permissions

Flex azure extension permissions

Author: prmerger-automator[bot]

articles/postgresql/flexible-server/generative-ai-azure-overview.md

@@ -3,7 +3,7 @@ title: Azure AI Extension
 description: Azure AI Extension in Azure Database for PostgreSQL - Flexible Server.
 author: mulander
 ms.author: adamwolk
-ms.date: 01/02/2024
+ms.date: 02/02/2024
 ms.service: postgresql
 ms.subservice: flexible-server
 ms.custom:
@@ -45,6 +45,15 @@ The extension also allows calling Azure OpenAI and Azure Cognitive Services.
 
 Configuring the extension requires you to provide the endpoints to connect to the Azure AI services and the API keys required for authentication. Service settings are stored using following functions:
 
+### permissions
+
+Your Azure AI access keys are similar to a root password for your account. Always be careful to protect your access keys. Use Azure Key Vault to manage and rotate your keys securely.
+To manage service keys used by the extension, users require the `azure_ai_settings_manager` role granted to them. The following functions require the role:
+* azure_ai.set_setting
+* azure_ai.get_setting
+
+The `azure_ai_settings_manager` role is by default granted to the `azure_pg_admin` role.
+
 ### `azure_ai.set_setting`
 
 Used to set configuration options.

articles/postgresql/flexible-server/reference-pg-azure-storage.md

@@ -4,7 +4,7 @@ description: Azure Storage Extension in Azure Database for PostgreSQL - Flexible
 author: gennadNY
 ms.author: gennadyk
 ms.reviewer: maghan
-ms.date: 01/02/2024
+ms.date: 02/02/2024
 ms.service: postgresql
 ms.subservice: flexible-server
 ms.custom:
@@ -17,12 +17,28 @@ ms.topic: reference
 [!INCLUDE [applies-to-postgresql-flexible-server](../includes/applies-to-postgresql-flexible-server.md)]
 
 The [pg_azure_storage extension](./concepts-storage-extension.md) allows you to import  or export data in multiple file formats directly between Azure blob storage and your Azure Database for PostgreSQL flexible server instance. Containers with access level "Private" or "Blob" requires adding private access key.  
-You can create the extension by running:
+
+Before you can enable `azure_storage` on your Azure Database for PostgreSQL flexible server instance, you need to add the extension to your allowlist as described in [how to use PostgreSQL extensions](./concepts-extensions.md#how-to-use-postgresql-extensions) and check if correctly added by running `SHOW azure.extensions;`.
+
+Then you can install the extension, by connecting to your target database and running the [CREATE EXTENSION](https://www.postgresql.org/docs/current/static/sql-createextension.html) command. You need to repeat the command separately for every database you want the extension to be available in.
 
 ```sql
-SELECT create_extension('azure_storage');
+CREATE EXTENSION azure_storage;
 ```
 
+## Permissions
+
+Your Azure blob storage (ABS) access keys are similar to a root password for your storage account. Always be careful to protect your access keys. Use Azure Key Vault to manage and rotate your keys securely. The account key is stored in a table that is accessible only by the superuser.
+
+Users granted the `azure_storage_admin` role can interact with this table using the following functions:
+* account_add
+* account_list
+* account_remove
+* account_user_add
+* account_user_remove
+
+The `azure_storage_admin` role is by default granted to the `azure_pg_admin` role.
+
 ## azure_storage.account_add
 
 Function allows adding access to a storage account.
@@ -41,7 +57,7 @@ An Azure blob storage (ABS) account contains all of your ABS objects: blobs, fil
 
 #### account_key_p
 
-Your Azure blob storage (ABS) access keys are similar to a root password for your storage account. Always be careful to protect your access keys. Use Azure Key Vault to manage and rotate your keys securely. The account key is stored in a table that is accessible by the postgres superuser, azure_storage_admin and all roles granted those admin permissions. To see which storage accounts exist, use the function account_list.
+Your Azure blob storage (ABS) access keys are similar to a root password for your storage account. Always be careful to protect your access keys. Use Azure Key Vault to manage and rotate your keys securely. The account key is stored in a table that is accessible only by the superuser. Users granted the `azure_storage_admin` role can interact with this table via functions. To see which storage accounts exist, use the function account_list.
 
 ## azure_storage.account_remove
 
@@ -175,7 +191,7 @@ Size of file object in bytes.
 
 #### last_modified
 
-When was the file content last modified?
+Describes when the file content was last modified.
 
 #### etag
 
@@ -185,13 +201,13 @@ An ETag property is used for optimistic concurrency during updates. It isn't a t
 
 The Blob object represents a blob, which is a file-like object of immutable, raw data. They can be read as text or binary data, or converted into a ReadableStream so its methods can be used for processing the data. Blobs can represent data that isn't necessarily in a JavaScript-native format.
 
-#### content_encode
+#### content_encoding
 
 Azure Storage allows you to define Content-Encoding property on a blob. For compressed content, you could set the property to be GZIP.  When the browser accesses the content, it automatically decompresses the content.
 
 #### content_hash
 
-This hash is used to verify the integrity of the blob during transport. When this header is specified, the storage service checks the hash that has arrived with the one that was sent. If the two hashes don't match, the operation fails with error code 400 (Bad Request).
+This hash is used to verify the integrity of the blob during transport. When this header is specified, the storage service checks the provided hash with one computed from content. If the two hashes don't match, the operation fails with error code 400 (Bad Request).
 
 ### Return type
 
@@ -271,7 +287,7 @@ For handling custom headers, custom separators, escape characters etc., `options
 
 ### Return type
 
-SETOF Record / any element
+SETOF Record / `anyelement`
 
 > [!NOTE]  
 > There are four utility functions, called as a parameter within blob_get that help building values for it. Each utility function is designated for the decoder matching its name.
@@ -298,33 +314,33 @@ Returns jsonb;
 
 #### delimiter
 
-Specifies the character that separates columns within each row (line) of the file. The default is a tab character in text format, a comma in CSV format. It must be a single one-byte character.
+Specifies the character that separates columns within each row (line) of the file. The default is a tab character in text format, a comma in CSV format. It must be a single 1-byte character.
 
-#### null_str
+#### null_string
 
 Specifies the string that represents a null value. The default is \N (backslash-N) in text format, and an unquoted empty string in CSV format. You might prefer an empty string even in text format for cases where you don't want to distinguish nulls from empty strings.
 
 #### header
 
-Specifies that the file contains a header line with the names of each column in the file. On output, the frontline contains the column names from the table.
+Specifies that the file contains a header line with the names of each column in the file. On output, the initial line contains the column names from the table.
 
 #### quote
 
-Specifies the quoting character to be used when a data value is quoted. The default is double-quote. It must be a single one-byte character.
+Specifies the quoting character to be used when a data value is quoted. The default is double-quote. It must be a single 1-byte character.
 
 #### escape
 
-Specifies the character that should appear before a data character that matches the QUOTE value. The default is the same as the QUOTE value (so that the quoting character is doubled if it appears in the data). It must be a single one-byte character.
+Specifies the character that should appear before a data character that matches the QUOTE value. The default is the same as the QUOTE value (so that the quoting character is doubled if it appears in the data). It must be a single 1-byte character.
 
 #### force_not_null
 
 Don't match the specified columns' values against the null string. In the default case where the null string is empty, it means that empty values are read as zero-length strings rather than nulls, even when they aren't quoted.
 
 #### force_null
 
-Match the specified columns' values against the null string, even if it has been quoted, and if a match is found set the value to NULL. In the default case where the null string is empty, it converts a quoted empty string into NULL.
+Match the specified columns' values against the null string, even if quoted, and if a match is found, set the value to NULL. In the default case where the null string is empty, it converts a quoted empty string into NULL.
 
-#### content_encode
+#### content_encoding
 
 Specifies that the file is encoded in the encoding_name. If the option is omitted, the current client encoding is used.
 
@@ -355,23 +371,23 @@ Returns jsonb;
 
 #### delimiter
 
-Specifies the character that separates columns within each row (line) of the file. The default is a tab character in text format, a comma in CSV format. It must be a single one-byte character.
+Specifies the character that separates columns within each row (line) of the file. The default is a tab character in text format, a comma in CSV format. It must be a single 1-byte character.
 
-#### null_str
+#### null_string
 
 Specifies the string that represents a null value. The default is \N (backslash-N) in text format, and an unquoted empty string in CSV format. You might prefer an empty string even in text format for cases where you don't want to distinguish nulls from empty strings.
 
 #### header
 
-Specifies that the file contains a header line with the names of each column in the file. On output, the frontline contains the column names from the table.
+Specifies that the file contains a header line with the names of each column in the file. On output, the initial line contains the column names from the table.
 
 #### quote
 
-Specifies the quoting character to be used when a data value is quoted. The default is double-quote. It must be a single one-byte character.
+Specifies the quoting character to be used when a data value is quoted. The default is double-quote. It must be a single 1-byte character.
 
 #### escape
 
-Specifies the character that should appear before a data character that matches the QUOTE value. The default is the same as the QUOTE value (so that the quoting character is doubled if it appears in the data). It must be a single one-byte character.
+Specifies the character that should appear before a data character that matches the QUOTE value. The default is the same as the QUOTE value (so that the quoting character is doubled if it appears in the data). It must be a single 1-byte character.
 
 #### force_quote
 
@@ -383,9 +399,9 @@ Don't match the specified columns' values against the null string. In the defaul
 
 #### force_null
 
-Match the specified columns' values against the null string, even if it has been quoted, and if a match is found set the value to NULL. In the default case where the null string is empty, it converts a quoted empty string into NULL.
+Match the specified columns' values against the null string, even if quoted, and if a match is found, set the value to NULL. In the default case where the null string is empty, it converts a quoted empty string into NULL.
 
-#### content_encode
+#### content_encoding
 
 Specifies that the file is encoded in the encoding_name. If the option is omitted, the current client encoding is used.
 
@@ -410,13 +426,13 @@ Returns jsonb;
 
 #### delimiter
 
-Specifies the character that separates columns within each row (line) of the file. The default is a tab character in text format, a comma in CSV format. It must be a single one-byte character.
+Specifies the character that separates columns within each row (line) of the file. The default is a tab character in text format, a comma in CSV format. It must be a single 1-byte character.
 
-#### null_str
+#### null_string
 
 Specifies the string that represents a null value. The default is \N (backslash-N) in text format, and an unquoted empty string in CSV format. You might prefer an empty string even in text format for cases where you don't want to distinguish nulls from empty strings.
 
-#### content_encode
+#### content_encoding
 
 Specifies that the file is encoded in the encoding_name. If the option is omitted, the current client encoding is used.
 
@@ -436,22 +452,21 @@ Returns jsonb;
 
 ### Arguments
 
-#### content_encode
+#### content_encoding
 
 Specifies that the file is encoded in the encoding_name. If this option is omitted, the current client encoding is used.
 
 ### Return Type
 
 jsonb
 
-> [!NOTE]  
-**Permissions**
-Now you can list containers set to Private and Blob access levels for that storage but only as the `citus user`, which has the `azure_storage_admin` role granted to it. If you create a new user named support, it won't be allowed to access container contents by default.
-
 ## Examples
 
 The examples used make use of sample Azure storage account `(pgquickstart)` with custom files uploaded for adding to coverage of different use cases. We can start by creating table used across the set of example used.
 
+> [!NOTE]  
+> You can list containers set to Private and Blob access levels for a storage but only as a user with the `azure_storage_admin` role granted to it. If you create a new user named support, it won't be allowed to access container contents by default.
+
 ```sql
 CREATE TABLE IF NOT EXISTS public.events
         (