HashiTalks 2025 Learn about unique use cases, homelab setups, and best practices at scale at our 24-hour virtual knowledge sharing event. Register
Terraform
Terraform Home

PostgreSQL Requirements for Terraform Enterprise

Note: These requirements apply to the External Services operational mode, not the Mounted Disk operational mode. Refer to the Pre-Install Checklist for more information.

PostgreSQL v12 End of Life

PostgreSQL v12 will reach end of life on November 12, 2024, and as a result will no longer be supported in Terraform Enterprise after that date.

To use an external PostgreSQL database with Terraform Enterprise, the following requirements must be met:

  • A PostgreSQL server such as Amazon RDS for PostgreSQL or a PostgreSQL-compatible server such as Amazon Aurora PostgreSQL must be used.
  • The PostgreSQL server version must be one of the following:
    • 12.x, 13.x, 14.4 and up, 15.x or 16.x
    • 14.0, 14.1, 14.2, 14.3 are not supported due to a known defect in PostgreSQL.
  • A PostgreSQL user must be created with the following permissions on the database:
    • The ability to create, modify, and read all tables and indices on all schemas within the database. Usually this is granted if the user is an owner of the database.
    • The ability to create extensions. If it is not feasible to have a user with the "CREATE EXTENSION" privilege, then refer to the Creating Extensions section below for information on creating the necessary extensions.
  • The rails, vault, registry, task_worker, and terraform_enterprise PostgreSQL schemas must be created on the database. These schemas will be automatically created if they do not already exist.

Creating Extensions

If the configured PostgreSQL user does not have permission to create PostgreSQL extensions (i.e. is not a superuser), then run the following SQL commands to create the proper extensions:

CREATE EXTENSION IF NOT EXISTS "hstore" WITH SCHEMA "rails";
CREATE EXTENSION IF NOT EXISTS "uuid-ossp" WITH SCHEMA "rails";
CREATE EXTENSION IF NOT EXISTS "citext" WITH SCHEMA "registry";

Connection Parameters

When providing optional extra keyword parameters for the database connection, note an additional restriction on the sslmode parameter is that only the require, verify-full, verify-ca, and disable values are allowed. For installations in External Services mode, the default value of sslmode is set to require. For installations in Mounted Disk mode, the default value of sslmode is set to disable.

Note: See the PostgreSQL library documentation for more about extra parameters related to sslmode. Terraform Enterprise provides a certificates file at /etc/ssl/private/terraform-enterprise/bundle.pem, which is required by the verify-full and verify-ca modes. If you are deploying with Replicated, you can add additional certificates with the CA Custom Bundle setting.

Note: The Client Certificates configuration is currently not supported by Terraform Enterprise due to the limitation of storing certificate files for the sslcert, and sslkey connection parameters.

PostgreSQL 9.5 to 12 Upgrade

In Terraform Enterprise v202103-1, the internally-managed PostgreSQL server was upgraded from PostgreSQL 9.5 to PostgreSQL 12. This change only affected installations in Mounted Disk mode.

For more details, consult the v202103-1 release notes.

PostgreSQL 12 to 14 Upgrade

Terraform Enterprise v202207-1 upgraded the internally-managed PostgresQL server from v12 to v14. This change only affected Mounted disk installations.

For more details, consult the v202207-1 release notes