Fixing the MySQL docs

rst/modules.rst

@@ -388,28 +388,35 @@ mysql_db
 
 Add or remove MySQL databases from a remote host.
 
-+--------------------+----------+----------+-----------------------------------------------------------------------------+
-| parameter          | required | default  | comments                                                                    |
-+====================+==========+==========+=============================================================================+
-| name               | yes      |           | name of the database to add or remove                                      |
-+--------------------+----------+-----------+----------------------------------------------------------------------------+
-| login_user         | no       |           | user used to authenticate with                                             |
-+--------------------+----------+-----------+----------------------------------------------------------------------------+
-| login_password     | no       |           | password used to authenticate with                                         |
-+--------------------+----------+-----------+----------------------------------------------------------------------------+
-| login_host         | no       | localhost | host running the database                                                  |
-+--------------------+----------+-----------+----------------------------------------------------------------------------+
-| state              | no       | present   | 'absent' or 'present'                                                      |
-+--------------------+----------+-----------+----------------------------------------------------------------------------+
-| collation          | no       |           | collation mode                                                             |
-+--------------------+----------+-----------+----------------------------------------------------------------------------+ 
-| encoding           | no       |           | encoding mode                                                              |
-+--------------------+----------+-----------+----------------------------------------------------------------------------+
+Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as
+apt-get install python-mysqldb.
+
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+| parameter          | required | default   | comments                                                                    |
++====================+==========+===========+=============================================================================+
+| name               | yes      |           | name of the database to add or remove                                       |
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+| login_user         | no       |           | user name used to authenticate with                                         |
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+| login_password     | no       |           | password used to authenticate with                                          |
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+| login_host         | no       | localhost | host running the database                                                   |
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+| state              | no       | present   | 'absent' or 'present'                                                       |
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+| collation          | no       |           | collation mode                                                              |
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+| encoding           | no       |           | encoding mode                                                               |
++--------------------+----------+-----------+-----------------------------------------------------------------------------+
+
+Both 'login_password' and 'login_username' are required when you are passing credentials.
+If none are present, the module will attempt to read the credentials from ~/.my.cnf, and
+finally fall back to using the MySQL default login of 'root' with no password.
 
 Example action from Ansible :doc:`playbooks`::
 
    - name: Create database
-     action: mysql_db loginpass=$mysql_root_password db=bobdata state=present
+     action: mysql_db db=bobdata state=present
 
 
 mysql_user
@@ -417,33 +424,42 @@ mysql_user
 
 Adds or removes a user from a MySQL database.
 
+Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as
+apt-get install python-mysqldb.
+
 +--------------------+----------+------------+----------------------------------------------------------------------------+
 | parameter          | required | default    | comments                                                                   |
 +====================+==========+============+============================================================================+
 | name               | 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                       |
+| password           | no       |            | set the user's password                                                    |
 +--------------------+----------+------------+----------------------------------------------------------------------------+
-| login_user         | no       |            | user (role) used to authenticate with                                      |
+| login_user         | no       |            | user name used to authenticate with                                        |
 +--------------------+----------+------------+----------------------------------------------------------------------------+
 | login_password     | no       |            | password used to authenticate with                                         |
 +--------------------+----------+------------+----------------------------------------------------------------------------+
-| login_host         | no       | localhost  | host running MySQL. Default (blank) implies localhost                      |
+| login_host         | no       | localhost  | host running MySQL.                                                        |
 +--------------------+----------+------------+----------------------------------------------------------------------------+
-| priv               | no       |            | MySQL priveledges string                                                   |
+| priv               | no       |            | MySQL privileges string in the format: db.table:priv1,priv2                |
 +--------------------+----------+------------+----------------------------------------------------------------------------+
 | state              | no       | present    | 'absent' or 'present'                                                      |
 +--------------------+----------+------------+----------------------------------------------------------------------------+
 
+Both 'login_password' and 'login_username' are required when you are passing credentials.
+If none are present, the module will attempt to read the credentials from ~/.my.cnf, and
+finally fall back to using the MySQL default login of 'root' with no password.
+
+Example privileges string format:
+
+    mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
+
 Example action from Ansible :doc:`playbooks`::
 
     - name: Create database user
-      action: mysql_user loginpass=$mysql_root_password name=bob passwd=12345 priv=*.*:ALL state=present
+      action: mysql_user name=bob passwd=12345 priv=*.*:ALL state=present
 
-    - name: Ensure no user named 'sally' exists
-      action: mysql_user loginpass=$mysql_root_password name=sally state=absent
+    - name: Ensure no user named 'sally' exists, also passing in the auth credentials.
+      action: mysql_user login_user=root login_password=123456 name=sally state=absent
 
 
 .. _ohai: