Backend Type: pg

Stores the state in a Postgres database version 10 or newer.

This backend supports state locking.

Example Configuration​

terraform {
  backend "pg" {
    conn_str = "postgres://user:[email protected]/tofu_backend"
  }
}

Before initializing the backend with tofu init, the database must already exist:

createdb tofu_backend

This createdb command is found in Postgres client applications which are installed along with the database server.

Using environment variables​

We recommend using environment variables to configure the pg backend in order not to have sensitive credentials written to disk and committed to source control.

The pg backend supports the standard libpq environment variables.

The backend can be configured either by giving the whole configuration as an environment variable:

terraform {
  backend "pg" {}
}

$ export PG_CONN_STR=postgres://user:[email protected]/tofu_backend
$ tofu init

or just the sensitive parameters:

terraform {
  backend "pg" {
    conn_str = "postgres://db.example.com/tofu_backend"
  }
}

$ export PGUSER=user
$ read -s PGPASSWORD
$ export PGPASSWORD
$ tofu init

Data Source Configuration​

To make use of the pg remote state in another configuration, use the terraform_remote_state data source.

data "terraform_remote_state" "network" {
  backend = "pg"
  config = {
    conn_str = "postgres://localhost/tofu_backend"
  }
}

Configuration Variables​

The following configuration options or environment variables are supported:

• conn_str - Postgres connection string; a postgres:// URL. The PG_CONN_STR and standard libpq environment variables can also be used to indicate how to connect to the PostgreSQL database.
• schema_name - Name of the automatically-managed Postgres schema, default to terraform_remote_state. Can also be set using the PG_SCHEMA_NAME environment variable.
• skip_schema_creation - If set to true, the Postgres schema must already exist. Can also be set using the PG_SKIP_SCHEMA_CREATION environment variable. OpenTofu won't try to create the schema, this is useful when it has already been created by a database administrator.
• skip_table_creation - If set to true, the Postgres table must already exist. Can also be set using the PG_SKIP_TABLE_CREATION environment variable. OpenTofu won't try to create the table, this is useful when it has already been created by a database administrator.
• skip_index_creation - If set to true, the Postgres index must already exist. Can also be set using the PG_SKIP_INDEX_CREATION environment variable. OpenTofu won't try to create the index, this is useful when it has already been created by a database administrator.

Technical Design​

This backend creates one table states in the automatically-managed Postgres schema configured by the schema_name variable.

The table is keyed by the workspace name. If workspaces are not in use, the name default is used.

Locking is supported using Postgres advisory locks. force-unlock is not supported, because these database-native locks will automatically unlock when the session is aborted or the connection fails. To see outstanding locks in a Postgres server, use the pg_locks system view.

The states table contains:

• a serial integer id, used as the key for advisory locks
• the workspace name key as text with a unique index
• the OpenTofu state data as text