Authentication to Azure PostgreSQL using a Managed Service Identity fails with "ERROR: schema \\\"terraform_enterprise\\\" already exists"

Problem

When switching from password-based authentication to a Managed Service Identity (MSI) for an Azure PostgreSQL database, Terraform Enterprise fails to start with the following error.

{
  "component": "terraform-enterprise",
  "log": "2025-08-06T14:16:15.163Z [INFO] terraform-enterprise.database.pgmultiauth: getting initial db auth token"
}
{
  "component": "terraform-enterprise",
  "log": "2025-08-06T14:16:15.207Z [INFO] terraform-enterprise.database: creating schema: schema=terraform_enterprise"
}
{
  "component": "terraform-enterprise",
  "log": "2025-08-06T14:16:15.209Z [ERROR] terraform-enterprise: startup: error=\"error creating schema: error creating terraform_enterprise schema: ERROR: schema \"terraform_enterprise\" already exists (SQLSTATE 42P06)\"
}

Terraform Enterprise version v202507-1 and later supports authentication with MSI for PostgreSQL, as announced in the v202507-1 release notes.

The following examples demonstrate the configuration change from password-based to MSI-based authentication.

Example of the previous configuration using a password.

TFE_DATABASE_HOST                     = "db.postges.database.azure.com:5432"
TFE_DATABASE_NAME                     = "tfe"
TFE_DATABASE_USER                     = "<postgres>"
TFE_DATABASE_PASSWORD                 = "<password>"

Example of the new configuration using MSI.

TFE_DATABASE_HOST                     = "db.postges.database.azure.com:5432"
TFE_DATABASE_NAME                     = "tfe"
TFE_DATABASE_USER                     = "<MSI_name>"
TFE_DATABASE_PASSWORDLESS_AZURE_USE_MSI = "true"

## Optional; required for user-assigned MSI only.
## For system-assigned MSI, this line is not needed.
TFE_DATABASE_PASSWORDLESS_AZURE_CLIENT_ID = "<identity_client_ID>"

Prerequisites

• Terraform Enterprise version v202507-1 or newer.
• You are configuring authentication to an Azure PostgreSQL database with an MSI.

Cause

The error occurs because the new MSI user does not have the required permissions to the existing terraform_enterprise database schema.

You can validate this by connecting to the PostgreSQL database and executing the following command.

SELECT 1 FROM information_schema.schemata WHERE schema_name='terraform_enterprise';

If the MSI has the correct permissions, the command returns 1. If it returns 0, the MSI is missing permissions.

Solution

To resolve this issue, you must grant the necessary permissions to the new MSI user.

1. Ensure that your MSI meets the database user requirements.
2. Add the MSI to Microsoft Entra Administrators in the Azure Portal. Navigate to your Azure Database for PostgreSQL flexible server instance > Security > Authentication > Add Microsoft Entra Administrators.

3. Connect to the database using the old PostgreSQL username and execute the following commands to transfer ownership to the new MSI user. Replace <old_owner> with the old PostgreSQL username and <new_MSI> with the new MSI user name.

   GRANT <old_owner> TO "<new_MSI>";
   ALTER ROLE "<new_MSI>" SET ROLE <old_owner>;

4. After granting permissions, re-deploy Terraform Enterprise with the updated configuration to use MSI.

To validate the schema ownership, you can run the \dn command in psql to display the list of schemas and their owners.

Outcome

After you apply the solution, Terraform Enterprise starts successfully and authenticates to the Azure PostgreSQL database using the Managed Service Identity.

Additional Information

• Connect to Azure Database for PostgreSQL - Flexible Server with a managed identity
• Terraform Enterprise Database Configuration Settings