• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Configuration Language

Skip to main content
  • Configuration Language
  • Data Sources
    • Overview
    • Terraform Cloud
      • Backend Configuration
        • local
        • remote
        • azurerm
        • consul
        • cos
        • gcs
        • http
        • Kubernetes
        • oss
        • pg
        • s3
  • Upgrading to Terraform v1.3
  • v1.x Compatibility Promises

  • Terraform Internals

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Configuration Language
  4. Terraform Settings
  5. Backends
  6. pg
  • Terraform
  • v1.2.x
  • v1.1 and earlier

»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:pass@db.example.com/terraform_backend"
  }
}

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

createdb terraform_backend

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

We recommend using a partial configuration for the conn_str variable, because it typically contains access credentials that should not be committed to source control:

terraform {
  backend "pg" {}
}

Then, set the credentials when initializing the configuration:

terraform init -backend-config="conn_str=postgres://user:pass@db.example.com/terraform_backend"

To use a Postgres server running on the same machine as Terraform, configure localhost with SSL disabled:

terraform init -backend-config="conn_str=postgres://localhost/terraform_backend?sslmode=disable"

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/terraform_backend"
  }
}

Configuration Variables

Warning: We recommend using environment variables to supply credentials and other sensitive data. If you use -backend-config or hardcode these values directly in your configuration, Terraform will include these values in both the .terraform subdirectory and in plan files. Refer to Credentials and Sensitive Data for details.

The following configuration options or environment variables are supported:

  • conn_str - (Required) Postgres connection string; a postgres:// URL
  • schema_name - Name of the automatically-managed Postgres schema, default terraform_remote_state.
  • skip_schema_creation - If set to true, the Postgres schema must already exist. Terraform 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. Terraform 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. Terraform 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 Terraform state data as text
Edit this page on GitHub

On this page

  1. pg
  2. Example Configuration
  3. Data Source Configuration
  4. Configuration Variables
  5. Technical Design
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)