Update documentation for postgresql_user

rst/modules/postgresql_user.rst

@@ -5,8 +5,8 @@ postgresql_user
 
 .. versionadded:: 0.6
 
-Add or remove PostgreSQL users (roles) from a remote host, and grant the users
-access to an existing database.
+Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users
+access to an existing database or tables.
 
 The default authentication assumes that you are either logging in as or
 sudo'ing to the postgres account on the host.
@@ -25,7 +25,11 @@ host before using this module.
 +--------------------+----------+----------+----------------------------------------------------------------------------+
 | password           | yes      |          | set the user's password                                                    |
 +--------------------+----------+----------+----------------------------------------------------------------------------+
-| db                 | yes      |          | name of an existing database to grant user access to                       |
+| db                 | no       |          | name of database where permissions will be granted                         |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| priv               | no       |          | PostgreSQL privileges string in the format: table:priv1,priv2              |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| fail_on_user       | no       | yes      | if yes, fail when user can't be removed. Otherwise just log and continue   |
 +--------------------+----------+----------+----------------------------------------------------------------------------+
 | login_user         | no       | postgres | user (role) used to authenticate with PostgreSQL                           |
 +--------------------+----------+----------+----------------------------------------------------------------------------+
@@ -36,7 +40,26 @@ host before using this module.
 | state              |          | present  | 'absent' or 'present'                                                      |
 +--------------------+----------+----------+----------------------------------------------------------------------------+
 
+The fundamental function of the module is to create, or delete, roles from a PostgreSQL cluster. 
+Privilege assignment, or removal, is an optional step, which works on one database at a time.
+This allows for the module to be called several times in the same module to modify the permissions on 
+different databases, or to grant permissions to already existing users. 
+
+A user cannot be removed untill all the privileges have been stripped from the user. In such situation,
+if the module tries to remove the user it will fail. To avoid this from happening the *fail_on_user* option
+signals the module to try to remove the user, but if not possible keep going; the module will report if changes
+happened and separately if the user was removed or not.
+
+Example privileges string format:
+    
+    INSERT,UPDATE/table:SELECT/anothertable:ALL
 
 Example action from Ansible :doc:`playbooks`::
 
-    postgresql_user db=acme user=django password=ceec4eif7ya
+    - name: Create django user and grant access to database and products table
+      postgresql_user db=acme user=django password=ceec4eif7ya privs=CONNECT/products:ALL
+    
+    - name: Remove test user privileges from acme
+      postgresql_user db=acme user=test privs=ALL/products:ALL state=absent fail_on_user=no
+    - name: Remove test user from test database and the cluster
+      postgresql_user db=test user=test privs=ALL state=absent