Troubleshoot the Azure Storage extension in Azure Database for PostgreSQL flexible server

Following is the list of errors that the Azure Storage extension can return. It also explains the reasons why or the circumstances in which they can be raised.

ERROR: azure_storage: Permission is not sufficient to perform requested operation

When executing any of the functions that interact with Azure Storage (azure_storage.blob_list, azure_storage.blob_get or azure_storage.blob_put) and the System Assigned Managed Identity isn't granted the adequate data plane roles or permissions (typically a minimum of Storage Blob Data Contributor for azure_storage.blob_put, and a minimum of Storage Blob Data Reader for the other two functions).

It might be the case that you already granted the minimum required permissions, but they aren't yet in effect. It can take a few minutes until those permissions propagate.

ERROR: azure_storage: missing storage credentials

When executing any of the functions that interact with Azure Storage (azure_storage.blob_list, azure_storage.blob_get or azure_storage.blob_put) and the credentials with which you want the extension to authenticate with the storage account aren't registered using azure_storage.account_add.

ERROR: azure_storage: internal error while connecting

When the instance of flexible server can't reach the target storage account. This situation can happen in the following cases:

  • The storage account doesn't exist.
  • Networking configuration doesn't allow traffic originated from the instance of flexible server to reach the storage account. For example, when the instance of flexible server is deployed with public access networking, and the storage account is only accessible via private endpoints.

ERROR: azure_storage: current user <user_or_role> isn't allowed to use storage account <account_name>

When executing any of the functions that interact with Azure Storage (azure_storage.blob_list, azure_storage.blob_get or azure_storage.blob_put) with a user or role that isn't member of azure_storage_admin and isn't granted permissions, using azure_storage.account_user_add, to use the referred storage account.

ERROR: azure_storage: Query is not supported while copying data to blob storage

When executing a COPY TO statement for which the source is a query. Azure Storage extension doesn't support this syntax. It only supports the syntax on which the source of the COPY TO be a relation. As a workaround, you can implement a view with the query as its definition, and rewrite the COPY TO statement to be sourced on the view.

ERROR: azure_storage: could not infer file encoding from extension: '<extension>', use a supported extension [csv, csv.gz, tsv, tsv.gz, json, json.gz, xml, xml.gz, txt, txt.gz, parquet], or specify the decoder argument if you are using blob_get or format if using COPY FROM/TO

When <extension> doesn't correspond to one of the extensions from which Azure Storage extension supports inferring the encoder and compression algorithm (for blob_put and COPY TO) or decoder and decompression algorithm (for blob_get and COPY FROM) that must be used. Either specify one of the supported values for automatic inference, or don't use auto but force specific type of encoder + compression or decoder + decompression.

ERROR: azure_storage: can only use text encoder with a single column

When the tuples passed to blob_put consist of more than one column and the encoder is inferred as text, or manually set to text.

ERROR: azure_storage: can only use text decoder with a single column

When the tuples read from the blob by blob_get consist of more than one column and the encoder is inferred as text, or is manually set to text.

ERROR: azure_storage: container with the given name does not exist

The name of the container passed through the container_name parameter of the blob_get function doesn't exist in the referred storage account.

ERROR: azure_storage: blob with the given name does not exist

The name of the blob passed through the path parameter of the blob_get function doesn't exist in the referred container in the storage account.

ERROR: azure_storage: credential encryption key is not configured

Note that if you create the extension in multiple databases, you must initialize the value of azure_storage.credential_encryption_key at the database level, so all sensitive credentials kept in that database are encrypted using the same key.

To set the value of azure_storage.credential_encryption_key, you must be member of the azure_storage_admin role. Then connect to the server, in the context of the database in which you created the extension. And, in that context, execute ALTER DATABASE <database_with_created_extension> SET azure_storage.credential_encryption_key = '<strong passphrase>'; to initialize the encryption key that's used to encrypt all Azure storage account credentials kept by the extension in the catalog of that database. After running this command, you must disconnect and reconnect to the database again, so that the override value takes effect, and you should also invoke the azure_storage.account_encrypt_existing_credentials() function so that the credentials of existing accounts which were never encrypted before with any other key, are encrypted with this key. To do so, execute SELECT azure_storage.account_encrypt_existing_credentials();.

Although possible, we recommend against trying to use other statements like ALTER ROLE or ALTER ROLE IN DATABASE to set the value of azure_storage.credential_encryption_key.

Notice that if you change the value of azure_storage.credential_encryption_key, you'll have to manually add again, using azure_storage.account_add, all storage accounts for which you provided a sensitive credential (an access key or a SAS token) which was encrypted with the previous value. Currently the extension doesn't support automatic rollover of encryption key.

ERROR: azure_storage: failed to encrypt storage credentials

An attempt to encrypt the credentials used to access an storage account using the encryption key set via azure_storage.credential_encryption_key failed. Retry the operation. If it keeps failing, create an incident with our support services.

ERROR: azure_storage: failed to decrypt storage credentials

An attempt to decrypt the encrypted credentials used to access an storage account using the encryption key set via azure_storage.credential_encryption_key failed. Retry the operation. If it keeps failing, create an incident with our support services.

ERROR: must be owner of table accounts

This error can occur when you create or upgrade the Azure Storage extension in a database where the TimescaleDB extension is also installed. The Azure Storage installation and upgrade scripts alter some internal tables. The TimescaleDB ddl_command_end event trigger can process those ALTER TABLE statements under the TimescaleDB function owner instead of the Azure Storage table owner. As a result, the operation can fail even when the connected user owns the Azure Storage extension and its objects.

Confirm that both extensions are installed and that the TimescaleDB event trigger is enabled:

SELECT extname, extversion
FROM pg_extension
WHERE extname IN ('azure_storage', 'timescaledb')
ORDER BY extname;

SELECT evtname, evtenabled, evtfoid::regprocedure
FROM pg_event_trigger
WHERE evtname = 'timescaledb_ddl_command_end';

Note that the connected user must have the privileges of both the TimescaleDB event trigger owner and, for an upgrade, the Azure Storage extension owner. Owning the event trigger function isn't sufficient.

Temporarily disable only the TimescaleDB ddl_command_end event trigger while creating the Azure Storage extension. Perform all operations in one transaction so that a failure also rolls back the trigger change:

BEGIN;

ALTER EVENT TRIGGER timescaledb_ddl_command_end DISABLE;

CREATE EXTENSION azure_storage;

ALTER EVENT TRIGGER timescaledb_ddl_command_end ENABLE;

COMMIT;

If any statement fails, run ROLLBACK;. The rollback restores the event trigger to its original enabled state. Don't leave the TimescaleDB event trigger disabled.

If the ALTER EVENT TRIGGER statement returns must be owner of event trigger timescaledb_ddl_command_end, don't attempt to change ownership or disable security settings. Open an Azure support request and ask support to perform the transactional workaround.

After the operation completes, verify the Azure Storage extension version and confirm that the TimescaleDB event trigger is enabled:

SELECT extversion
FROM pg_extension
WHERE extname = 'azure_storage';

SELECT evtname, evtenabled
FROM pg_event_trigger
WHERE evtname = 'timescaledb_ddl_command_end';

The evtenabled value should be O. If the error occurs when this trigger isn't present and enabled, contact Azure support.

Related content

  • Last updated on