From 39e9839a04c416ac70cdbd48f33ff574d56c7fbe Mon Sep 17 00:00:00 2001
From: Lrizika <github@lrizika.com>
Date: Thu, 11 Jul 2019 06:31:36 -0700
Subject: [PATCH]  Improved docs on setting up Postgresql (#5661)

Added that synapse_user needs a database to access before it can auth
Noted you'll need to enable password auth, linked to pg_hba.conf docs
---
 changelog.d/5661.docs |  1 +
 docs/postgres.rst     | 19 +++++++++++++++----
 2 files changed, 16 insertions(+), 4 deletions(-)
 create mode 100644 changelog.d/5661.docs

diff --git a/changelog.d/5661.docs b/changelog.d/5661.docs
new file mode 100644
index 0000000000..c70e62014e
--- /dev/null
+++ b/changelog.d/5661.docs
@@ -0,0 +1 @@
+Improvements to Postgres setup instructions. Contributed by @Lrizika - thanks!
diff --git a/docs/postgres.rst b/docs/postgres.rst
index 33f58e3ace..0ae52ccbd8 100644
--- a/docs/postgres.rst
+++ b/docs/postgres.rst
@@ -34,9 +34,14 @@ Assuming your PostgreSQL database user is called ``postgres``, create a user
    su - postgres
    createuser --pwprompt synapse_user
 
-The PostgreSQL database used *must* have the correct encoding set, otherwise it
-would not be able to store UTF8 strings. To create a database with the correct
-encoding use, e.g.::
+Before you can authenticate with the ``synapse_user``, you must create a 
+database that it can access. To create a database, first connect to the database
+with your database user::
+
+   su - postgres
+   psql
+
+and then run::
 
    CREATE DATABASE synapse
     ENCODING 'UTF8'
@@ -46,7 +51,13 @@ encoding use, e.g.::
     OWNER synapse_user;
 
 This would create an appropriate database named ``synapse`` owned by the
-``synapse_user`` user (which must already exist).
+``synapse_user`` user (which must already have been created as above).
+
+Note that the PostgreSQL database *must* have the correct encoding set (as 
+shown above), otherwise it will not be able to store UTF8 strings.
+
+You may need to enable password authentication so ``synapse_user`` can connect
+to the database. See https://www.postgresql.org/docs/11/auth-pg-hba-conf.html.
 
 Tuning Postgres
 ===============