github.com/terramate-io/tf@v0.0.0-20230830114523-fce866b4dfcd/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](/terraform/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  
    31  ### Using environment variables
    32  
    33  We recommend using environment variables to configure the `pg` backend in order
    34  not to have sensitive credentials written to  disk and committed to source
    35  control.
    36  
    37  The `pg` backend supports the standard [`libpq` environment variables](https://www.postgresql.org/docs/current/libpq-envars.html).
    38  
    39  The backend can be configured either by giving the whole configuration as an
    40  environment variable:
    41  
    42  ```hcl
    43  terraform {
    44    backend "pg" {}
    45  }
    46  ```
    47  
    48  ```shellsession
    49  $ export PG_CONN_STR=postgres://user:pass@db.example.com/terraform_backend
    50  $ terraform init
    51  ```
    52  
    53  or just the sensitive parameters:
    54  
    55  ```hcl
    56  terraform {
    57    backend "pg" {
    58      conn_str = "postgres://db.example.com/terraform_backend"
    59    }
    60  }
    61  ```
    62  
    63  ```shellsession
    64  $ export PGUSER=user
    65  $ read -s PGPASSWORD
    66  $ export PGPASSWORD
    67  $ terraform init
    68  ```
    69  
    70  ## Data Source Configuration
    71  
    72  To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/terraform/language/state/remote-state-data).
    73  
    74  ```hcl
    75  data "terraform_remote_state" "network" {
    76    backend = "pg"
    77    config = {
    78      conn_str = "postgres://localhost/terraform_backend"
    79    }
    80  }
    81  ```
    82  
    83  ## Configuration Variables
    84  
    85  !> **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](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
    86  
    87  The following configuration options or environment variables are supported:
    88  
    89  - `conn_str` - Postgres connection string; a `postgres://` URL. The `PG_CONN_STR` and [standard `libpq`](https://www.postgresql.org/docs/current/libpq-envars.html) environment variables can also be used to indicate how to connect to the PostgreSQL database.
    90  - `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.
    91  - `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. Terraform won't try to create the schema, this is useful when it has already been created by a database administrator.
    92  - `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. Terraform won't try to create the table, this is useful when it has already been created by a database administrator.
    93  - `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. Terraform won't try to create the index, this is useful when it has already been created by a database administrator.
    94  
    95  ## Technical Design
    96  
    97  This backend creates one table **states** in the automatically-managed Postgres schema configured by the `schema_name` variable.
    98  
    99  The table is keyed by the [workspace](/terraform/language/state/workspaces) name. If workspaces are not in use, the name `default` is used.
   100  
   101  Locking is supported using [Postgres advisory locks](https://www.postgresql.org/docs/9.5/explicit-locking.html#ADVISORY-LOCKS). [`force-unlock`](/terraform/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).
   102  
   103  The **states** table contains:
   104  
   105  - a serial integer `id`, used as the key for advisory locks
   106  - the workspace `name` key as _text_ with a unique index
   107  - the Terraform state `data` as _text_