Troubleshooting Terraform Enterprise with PgBouncer on Azure Flexible PostgreSQL

Problem

You may encounter startup errors when running Terraform Enterprise (TFE) with PgBouncer enabled on Azure Database for PostgreSQL Flexible Server.

Cause

The startup process may fail with one of the following errors, indicating an issue with how PgBouncer is handling prepared statements.

Failed retrieving database version: ERROR: unnamed prepared statement does not exist (SQLSTATE 26000)

Failed to check if table exists: error finding application_versions table: ERROR: unnamed prepared statement does not exist (SQLSTATE 26000)

Solution

Follow these steps to diagnose and resolve the issue.

1. Isolate the Issue by Bypassing PgBouncer

   To confirm the problem is related to PgBouncer, first attempt to connect Terraform Enterprise directly to the PostgreSQL instance on port 5432. If TFE operates correctly with a direct connection, it isolates the problem to the PgBouncer configuration.

2. Configure PgBouncer for Prepared Statements

   If you are using prepared statements, ensure PgBouncer is configured to handle them correctly. In your Azure PostgreSQL Flexible Server configuration, consider setting pgbouncer.max_prepared_statements to a non-zero value. This allows PgBouncer to manage prepared statements required by TFE.

3. Verify the TFE Connection String

   Ensure the connection string used by TFE points to the PgBouncer instance on port 6432. The following is an example connection string.

   $ psql "host=myPgServer.postgres.database.azure.com port=6432 dbname=tfedb user=tfeappadmin password=xxxxxxx sslmode=require"

Outcome

After correctly configuring PgBouncer and verifying the connection string, Terraform Enterprise should start without errors. If TFE still fails with PgBouncer enabled, further investigation into your specific PgBouncer configuration may be necessary.

Additional Information

• For more details on PgBouncer configuration in Azure, refer to the official Microsoft documentation: PgBouncer on Azure Database for PostgreSQL - Flexible Server.