github.com/hugorut/terraform@v1.1.3/website/docs/language/settings/backends/pg.mdx (about)

     1  ---
     2  page_title: 'Backend Type: pg'
     3  description: Terraform can store state remotely in a Postgres database with locking.
     4  ---
     5  
     6  # pg
     7  
     8  Stores the state in a [Postgres database](https://www.postgresql.org) version 10 or newer.
     9  
    10  This backend supports [state locking](/language/state/locking).
    11  
    12  ## Example Configuration
    13  
    14  ```hcl
    15  terraform {
    16    backend "pg" {
    17      conn_str = "postgres://user:pass@db.example.com/terraform_backend"
    18    }
    19  }
    20  ```
    21  
    22  Before initializing the backend with `terraform init`, the database must already exist:
    23  
    24  ```
    25  createdb terraform_backend
    26  ```
    27  
    28  This `createdb` command is found in [Postgres client applications](https://www.postgresql.org/docs/10/reference-client.html) which are installed along with the database server.
    29  
    30  We recommend using a
    31  [partial configuration](/language/settings/backends/configuration#partial-configuration)
    32  for the `conn_str` variable, because it typically contains access credentials that should not be committed to source control:
    33  
    34  ```hcl
    35  terraform {
    36    backend "pg" {}
    37  }
    38  ```
    39  
    40  Then, set the credentials when initializing the configuration:
    41  
    42  ```
    43  terraform init -backend-config="conn_str=postgres://user:pass@db.example.com/terraform_backend"
    44  ```
    45  
    46  To use a Postgres server running on the same machine as Terraform, configure localhost with SSL disabled:
    47  
    48  ```
    49  terraform init -backend-config="conn_str=postgres://localhost/terraform_backend?sslmode=disable"
    50  ```
    51  
    52  ## Data Source Configuration
    53  
    54  To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/language/state/remote-state-data).
    55  
    56  ```hcl
    57  data "terraform_remote_state" "network" {
    58    backend = "pg"
    59    config = {
    60      conn_str = "postgres://localhost/terraform_backend"
    61    }
    62  }
    63  ```
    64  
    65  ## Configuration Variables
    66  
    67  The following configuration options or environment variables are supported:
    68  
    69  - `conn_str` - (Required) Postgres connection string; a `postgres://` URL
    70  - `schema_name` - Name of the automatically-managed Postgres schema, default `terraform_remote_state`.
    71  - `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.
    72  - `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.
    73  - `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.
    74  
    75  ## Technical Design
    76  
    77  This backend creates one table **states** in the automatically-managed Postgres schema configured by the `schema_name` variable.
    78  
    79  The table is keyed by the [workspace](/language/state/workspaces) name. If workspaces are not in use, the name `default` is used.
    80  
    81  Locking is supported using [Postgres advisory locks](https://www.postgresql.org/docs/9.5/explicit-locking.html#ADVISORY-LOCKS). [`force-unlock`](/cli/commands/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](https://www.postgresql.org/docs/9.5/view-pg-locks.html).
    82  
    83  The **states** table contains:
    84  
    85  - a serial integer `id`, used as the key for advisory locks
    86  - the workspace `name` key as _text_ with a unique index
    87  - the Terraform state `data` as _text_