3.3 KiB
layout | page_title | sidebar_current | description |
---|---|---|---|
backend-types | Backend Type: pg | docs-backends-types-standard-pg | Terraform can store state remotely in a Postgres database with locking. |
pg
Kind: Standard (with locking)
Stores the state in a Postgres database version 9.5 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
The following configuration options or environment variables are supported:
conn_str
- (Required) Postgres connection string; apostgres://
URLschema_name
- Name of the automatically-managed Postgres schema, defaultterraform_remote_state
.skip_schema_creation
- If set totrue
, the Postgres schema must already exist. Terraform won't try to create the schema. Useful when the Postgres user does not have "create schema" permission on the database.
Technical Design
Postgres version 9.5 or newer is required to support advisory locks and the "ON CONFLICT" upsert syntax.
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