From 2831459ca28335a5dfe3802b4d86ae9ea917037d Mon Sep 17 00:00:00 2001
From: Mars Hall <mars@users.noreply.github.com>
Date: Sun, 14 Oct 2018 12:34:34 -0700
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20pg=20backend=20technical=20desig?=
 =?UTF-8?q?n=20&=20clarifications?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 website/docs/backends/types/pg.html.md | 55 +++++++++++++-------------
 1 file changed, 27 insertions(+), 28 deletions(-)

diff --git a/website/docs/backends/types/pg.html.md b/website/docs/backends/types/pg.html.md
index 3be87a548..bdd235f87 100644
--- a/website/docs/backends/types/pg.html.md
+++ b/website/docs/backends/types/pg.html.md
@@ -8,11 +8,11 @@ description: |-
 
 # pg
 
-**Kind: Standard with locking**
+**Kind: Standard (with locking)**
 
-Stores the state in a [Postgres database](https://www.postgresql.org) using two tables, `states` and `locks`.
+Stores the state in a [Postgres database](https://www.postgresql.org) version 9.5 or newer.
 
-Supports Postgres version 10 and newer.
+This backend supports [state locking](/docs/state/locking.html).
 
 ## Example Configuration
 
@@ -24,18 +24,13 @@ terraform {
 }
 ```
 
-This assumes we have a database created called `terraform_backend`. The
-Terraform state is stored in a self-managed schema, by default 
-`terraform_remote_backend`.
+Before initializing the backend with `terraform init`, the database must already exist.
 
-Note that for the access credentials we recommend using a
-[partial configuration](/docs/backends/config.html).
+We recommend using a [partial configuration](/docs/backends/config.html#partial-configuration) for the `conn_str` variable, because it typically contains access credentials that should not be committed to source control.
 
-## Using the pg remote state
+## Example Referencing
 
-To make use of the pg remote state we can use the
-[`terraform_remote_state` data
-source](/docs/providers/terraform/d/remote_state.html).
+To make use of the pg remote state we can use the [`terraform_remote_state` data source](/docs/providers/terraform/d/remote_state.html).
 
 ```hcl
 data "terraform_remote_state" "network" {
@@ -46,24 +41,28 @@ data "terraform_remote_state" "network" {
 }
 ```
 
-The `terraform_remote_state` data source will return all of the root module 
-outputs defined in the referenced remote state (but not any outputs from 
-nested modules unless they are explicitly output again in the root). An 
-example output might look like:
-
-```
-data.terraform_remote_state.network:
-  id = 2018-10-11 01:57:59.780010914 +0000 UTC
-  backend = pg
-  config.% = 1
-  config.conn_str = postgres://localhost/terraform_backend
-```
-
-## Configuration variables
+## Configuration Variables
 
 The following configuration options or environment variables are supported:
 
  * `conn_str` - (Required) Postgres connection string; a `postgres://` URL
  * `lock` - Use locks to synchronize state access, default `true`
- * `schema_name` - Name of the automatically managed Postgres schema to store locks & state.
- 
\ No newline at end of file
+ * `schema_name` - Name of the automatically-managed Postgres schema to store locks & state, default `terraform_remote_backend`.
+ 
+## Technical Design
+
+Postgres version 9.5 or newer is required to support the "ON CONFLICT" upsert syntax and *jsonb* data type.
+
+This backend creates two tables, **states** and **locks**, in the automatically-managed Postgres schema configured by the `schema_name` variable.
+
+Both tables are keyed by the [workspace](/docs/state/workspaces.html) name. If workspaces are not in use, the name `default` is used.
+
+The **states** table contains:
+
+ * the workspace `name` key as *text* with a unique index
+ * the Terraform state `data` JSON as *text*.
+
+The **locks** table contains:
+
+ * the workspace `name` key as *text* with a unique index
+ * the lock's `info` JSON as *jsonb*.