Docs: add info how to cope with a protocol-related connection error u…

…sing login_unix_socket argument (#420)

plugins/doc_fragments/mysql.py

@@ -35,6 +35,7 @@ class ModuleDocFragment(object):
   login_unix_socket:
     description:
       - The path to a Unix domain socket for local connections.
+      - Use this parameter to avoid the C(Please explicitly state intended protocol) error.
     type: str
   connect_timeout:
     description:
@@ -78,6 +79,8 @@ class ModuleDocFragment(object):
    - PyMySQL (Python 2.7 and Python 3.x) or
    - MySQLdb (Python 2.x)
 notes:
+   - "To avoid the C(Please explicitly state intended protocol) error, use the I(login_unix_socket) argument,
+     for example, C(login_unix_socket: /run/mysqld/mysqld.sock)."
    - Requires the PyMySQL (Python 2.7 and Python 3.X) or MySQL-python (Python 2.X) package installed on the remote host.
      The Python package may be installed with apt-get install python-pymysql (Ubuntu; see M(ansible.builtin.apt)) or
      yum install python2-PyMySQL (RHEL/CentOS/Fedora; see M(ansible.builtin.yum)). You can also use dnf install python2-PyMySQL

plugins/modules/mysql_db.py

@@ -198,10 +198,13 @@
 '''
 
 EXAMPLES = r'''
+# If you encounter the "Please explicitly state intended protocol" error,
+# use the login_unix_socket argument
 - name: Create a new database with name 'bobdata'
   community.mysql.mysql_db:
     name: bobdata
     state: present
+    login_unix_socket: /run/mysqld/mysqld.sock
 
 - name: Create new databases with names 'foo' and 'bar'
   community.mysql.mysql_db:

plugins/modules/mysql_info.py

@@ -76,9 +76,12 @@
 # Display all info from databases group except settings:
 # ansible databases -m mysql_info -a 'filter=!settings'
 
+# If you encounter the "Please explicitly state intended protocol" error,
+# use the login_unix_socket argument
 - name: Collect all possible information using passwordless root access
   community.mysql.mysql_info:
     login_user: root
+    login_unix_socket: /run/mysqld/mysqld.sock
 
 - name: Get MySQL version with non-default credentials
   community.mysql.mysql_info:

plugins/modules/mysql_query.py

@@ -57,10 +57,13 @@
 '''
 
 EXAMPLES = r'''
+# If you encounter the "Please explicitly state intended protocol" error,
+# use the login_unix_socket argument
 - name: Simple select query to acme db
   community.mysql.mysql_query:
     login_db: acme
     query: SELECT * FROM orders
+    login_unix_socket: /run/mysqld/mysqld.sock
 
 - name: Select query to db acme with positional arguments
   community.mysql.mysql_query:

plugins/modules/mysql_replication.py

@@ -202,9 +202,12 @@
 '''
 
 EXAMPLES = r'''
+# If you encounter the "Please explicitly state intended protocol" error,
+# use the login_unix_socket argument
 - name: Stop mysql replica thread
   community.mysql.mysql_replication:
     mode: stopreplica
+    login_unix_socket: /run/mysqld/mysqld.sock
 
 - name: Get primary binlog file name and binlog position
   community.mysql.mysql_replication:

plugins/modules/mysql_role.py

@@ -142,6 +142,9 @@
 '''
 
 EXAMPLES = r'''
+# If you encounter the "Please explicitly state intended protocol" error,
+# use the login_unix_socket argument, for example, login_unix_socket: /run/mysqld/mysqld.sock
+
 # Example of a .my.cnf file content for setting a root password
 # [client]
 # user=root

plugins/modules/mysql_user.py

@@ -177,11 +177,14 @@
 '''
 
 EXAMPLES = r'''
+# If you encounter the "Please explicitly state intended protocol" error,
+# use the login_unix_socket argument
 - name: Removes anonymous user account for localhost
   community.mysql.mysql_user:
     name: ''
     host: localhost
     state: absent
+    login_unix_socket: /run/mysqld/mysqld.sock
 
 - name: Removes all anonymous user accounts
   community.mysql.mysql_user:

plugins/modules/mysql_variables.py

@@ -58,9 +58,12 @@
 '''
 
 EXAMPLES = r'''
+# If you encounter the "Please explicitly state intended protocol" error,
+# use the login_unix_socket argument
 - name: Check for sync_binlog setting
   community.mysql.mysql_variables:
     variable: sync_binlog
+    login_unix_socket: /run/mysqld/mysqld.sock
 
 - name: Set read_only variable to 1 persistently
   community.mysql.mysql_variables: