Docs: add info how to cope with a protocol-related connection error using login_unix_socket argument (#420) (#430)

(cherry picked from commit f1d63e3fc8)

Co-authored-by: Andrew Klychkov <aklychko@redhat.com>

plugins/doc_fragments/mysql.py

@@ -35,6 +35,7 @@ options:
   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 @@ requirements:
    - 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

@@ -183,10 +183,13 @@ extends_documentation_fragment:
 '''
 
 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 @@ EXAMPLES = r'''
 # 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 @@ extends_documentation_fragment:
 '''
 
 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

@@ -212,9 +212,12 @@ seealso:
 '''
 
 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

@@ -126,6 +126,9 @@ extends_documentation_fragment:
 '''
 
 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

@@ -152,11 +152,14 @@ extends_documentation_fragment:
 '''
 
 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 @@ extends_documentation_fragment:
 '''
 
 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: