More postgres CI service example cleanup

1 files changed, 35 insertions, 20 deletions

diff --git a/doc/ci/services/postgres.md b/doc/ci/services/postgres.md
index b8436f4f7ca..db5be070ee7 100644
--- a/doc/ci/services/postgres.md
+++ b/doc/ci/services/postgres.md
@@ -13,11 +13,11 @@ First, in your `.gitlab-ci.yml` add:
 
 ```yaml
 services:
-  - postgres
+  - postgres:latest
 
 variables:
   POSTGRES_DB: nice_marmot
-  POSTGRES_USER: gitlab_runner
+  POSTGRES_USER: runner
   POSTGRES_PASSWORD: ""
 ```
 
@@ -25,7 +25,7 @@ And then configure your application to use the database, for example:
 
 ```yaml
 Host: localhost
-User: gitlab_runner
+User: runner
 Password:
 Database: nice_marmot
 ```
@@ -47,39 +47,54 @@ First install the PostgreSQL server:
 sudo apt-get install -y postgresql postgresql-client libpq-dev
 ```
 
-Then create a user:
+The next step is to create a user, so login to PostgreSQL:
 
 ```bash
-# Login to PostgreSQL
 sudo -u postgres psql -d template1
+```
 
-# Create a user for GitLab Runner that can create databases
-# Do not type the 'template1=#', this is part of the prompt
-template1=# CREATE USER gitlab_runner CREATEDB;
+Then create a user (in our case `runner`) which will be used by your
+application. Change `$password` in the command below to a real strong password.
 
-# Create the database & grant all privileges on database
-template1=# CREATE DATABASE nice_marmot OWNER gitlab_runner;
+*__Note:__ Do not type `template1=#`, this is part of the PostgreSQL prompt.*
 
-# Quit the database session
-template1=# \q
+```bash
+template1=# CREATE USER runner WITH PASSWORD '$password' CREATEDB;
 ```
 
-Try to connect to database:
+*__Note:__ Notice that we created the user with the privilege to be able to
+create databases (`CREATEDB`). In the following steps we will create a database 
+explicitly for that user but having that privilege can be useful if in your
+testing framework you have tools that drop and create databases.*
+
+Create the database and grant all privileges on it for the user `runner`:
 
 ```bash
-# Try connecting to the new database with the new user
-sudo -u gitlab_runner -H psql -d nice_marmot
+template1=# CREATE DATABASE nice_marmot OWNER runner;
+```
+
+If all went well you can now quit the database session:
 
-# Quit the database session
-nice_marmot> \q
+```bash
+template1=# \q
 ```
 
-Finally, configure your application to use the database:
+Now, try to connect to the newly created database with the user `runner` to
+check that everything is in place.
 
 ```bash
+psql -U runner -h localhost -d nice_marmot -W
+```
+
+*__Note:__ We are explicitly telling `psql` to connect to localhost in order
+to use the md5 authentication. If you omit this step you will be denied access.*
+
+Finally, configure your application to use the database, for example:
+
+```yaml
 Host: localhost
-User: gitlab_runner
-Password:
+User: runner
+Password: $password
 Database: nice_marmot
 ```