Merge pull request #154 from lorin/postgres-docs

Document postgresql_db and postgresql_user modules.

rst/modules.rst

@@ -348,7 +348,86 @@ This module does not support change hooks and is informative only - it
 takes no parameters & does not support change hooks, nor does it make
 any changes on the system.
 
-.. _service:
+
+.. postgresql_db:
+
+postgresql_db
+`````````````
+
+Add or remove PostgreSQL databases from a remote host.
+
+The default authentication assumes that you are either logging in as or
+sudo'ing to the postgres account on the host.
+
+This module uses psycopg2, a Python PostgreSQL database adapter. You must
+ensure that psycopg2 is installed on the host before using this module. If
+the remote host is the PostgreSQL server (which is the default case), then
+PostgreSQL must also be installed on the remote host. For Ubuntu-based systems,
+install the postgresql, libpq-dev, and python-psycopg2 packages on the remote
+host before using this module.
+
+
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| parameter          | required | default  | comments                                                                   |
++====================+==========+==========+============================================================================+
+| db                 | yes      |          | name of the database to add or remove                                      |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| login_user         | no       | postgres | user (role) used to authenticate with PostgreSQL                           |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| login_password     | no       |          | password used to authenticate with PostgreSQL                              |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| login_host         | no       |          | host running PostgreSQL. Default (blank) implies localhost                 |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| state              |          | present  | 'absent' or 'present'                                                      |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+
+Example action from Ansible :doc:`playbooks`::
+
+    postgresql_db db=acme
+
+
+.. postgresql_user:
+
+postgresql_user
+```````````````
+
+Add or remove PostgreSQL users (roles) from a remote host, and grant the users
+access to an existing database.
+
+The default authentication assumes that you are either logging in as or
+sudo'ing to the postgres account on the host.
+
+This module uses psycopg2, a Python PostgreSQL database adapter. You must
+ensure that psycopg2 is installed on the host before using this module. If
+the remote host is the PostgreSQL server (which is the default case), then
+PostgreSQL must also be installed on the remote host. For Ubuntu-based systems,
+install the postgresql, libpq-dev, and python-psycopg2 packages on the remote
+host before using this module.
+
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| parameter          | required | default  | comments                                                                   |
++====================+==========+==========+============================================================================+
+| user               | yes      |          | name of the user (role) to add or remove                                   |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| password           | yes      |          | set the user's password                                                    |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| db                 | yes      |          | name of an existing database to grant user access to                       |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| login_user         | no       | postgres | user (role) used to authenticate with PostgreSQL                           |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| login_password     | no       |          | password used to authenticate with PostgreSQL                              |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| login_host         | no       |          | host running PostgreSQL. Default (blank) implies localhost                 |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+| state              |          | present  | 'absent' or 'present'                                                      |
++--------------------+----------+----------+----------------------------------------------------------------------------+
+
+
+Example action from Ansible :doc:`playbooks`::
+
+    postgresql_user db=acme user=django password=ceec4eif7ya
+
+.. _raw:
 
 raw
 ```
@@ -370,6 +449,8 @@ Example from `/usr/bin/ansible` to bootstrap a legacy python 2.4 host::
 
     ansible newhost.example.com raw -a "yum install python-simplejson"
 
+.. _service:
+
 service
 ```````