Deprecate mysqlclient/MySQLdb connector support (#655)

* Deprecate mysqlclient/MySQLdb connector support

* Update README

* Put in README that mysqlclient is deprecated

README.md

@@ -122,17 +122,12 @@ For MariaDB, only Long Term releases are tested.
 - pymysql 0.7.11 (Only tested with MySQL 5.7)
 - pymysql 0.9.3
 - pymysql 1.0.2 (only collection version >= 3.6.1)
-- mysqlclient 2.0.1
-- mysqlclient 2.0.3 (only collection version >= 3.5.2)
-- mysqlclient 2.1.1 (only collection version >= 3.5.2)
 
 ## External requirements
 
-The MySQL modules rely on a MySQL connector. The list of supported drivers is below:
+The MySQL modules rely on a [PyMySQL](https://github.com/PyMySQL/PyMySQL) connector.
 
-- [PyMySQL](https://github.com/PyMySQL/PyMySQL)
-- [mysqlclient](https://github.com/PyMySQL/mysqlclient)
-- Support for other Python MySQL connectors may be added in a future release.
+The `mysqlclient` connector support has been [deprecated](https://github.com/ansible-collections/community.mysql/issues/654) - use `PyMySQL` connector instead! We will stop testing against it in collection version 4.0.0 and remove the related code in 5.0.0.
 
 ## Using this collection
 

changelogs/fragments/3-deprecate_mysqlclient.yml

@@ -0,0 +1,2 @@
+breaking_changes:
+- collection - support of mysqlclient connector is deprecated - use PyMySQL connector instead! We will stop testing against it in collection version 4.0.0 and remove the related code in 5.0.0 (https://github.com/ansible-collections/community.mysql/issues/654).

plugins/doc_fragments/mysql.py

@@ -71,24 +71,21 @@ class ModuleDocFragment(object):
       - Whether to validate the server host name when an SSL connection is required. Corresponds to MySQL CLIs C(--ssl) switch.
       - Setting this to C(false) disables hostname verification. Use with caution.
       - Requires pymysql >= 0.7.11.
-      - This option has no effect on MySQLdb.
     type: bool
     version_added: '1.1.0'
 requirements:
-   - mysqlclient (Python 3.5+) or
-   - PyMySQL (Python 2.7 and Python 3.x) or
-   - MySQLdb (Python 2.x)
+   - PyMySQL (Python 2.7 and Python 3.x)
 notes:
-   - Requires the PyMySQL (Python 2.7 and Python 3.X) or MySQL-python (Python 2.X) package installed on the remote host.
+   - Requires the PyMySQL (Python 2.7 and Python 3.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
      for newer versions of Fedora; see M(ansible.builtin.dnf).
-   - Be sure you have mysqlclient, PyMySQL, or MySQLdb library installed on the target machine
-     for the Python interpreter Ansible discovers.  For example if ansible discovers and uses Python 3, you need to install
-     the Python 3 version of PyMySQL or mysqlclient.  If ansible discovers and uses Python 2, you need to install the Python 2
-     version of either PyMySQL or MySQL-python.
+   - Be sure you have PyMySQL library installed on the target machine
+     for the Python interpreter Ansible discovers. For example if ansible discovers and uses Python 3, you need to install
+     the Python 3 version of PyMySQL. If ansible discovers and uses Python 2, you need to install the Python 2
+     version of PyMySQL.
    - If you have trouble, it may help to force Ansible to use the Python interpreter you need by specifying
-     C(ansible_python_interpreter).  For more information, see
+     C(ansible_python_interpreter). For more information, see
      U(https://docs.ansible.com/ansible/latest/reference_appendices/interpreter_discovery.html).
    - Both C(login_password) and C(login_user) are required when you are
      passing credentials. If none are present, the module will attempt to read
@@ -99,9 +96,6 @@ class ModuleDocFragment(object):
      and later uses the unix_socket authentication plugin by default that
      without using I(login_unix_socket=/var/run/mysqld/mysqld.sock) (the default path)
      causes the error ``Host '127.0.0.1' is not allowed to connect to this MariaDB server``.
-   - Alternatively, you can use the mysqlclient library instead of MySQL-python (MySQLdb)
-     which supports both Python 2.X and Python >=3.5.
-     See U(https://pypi.org/project/mysqlclient/) how to install it.
    - "If credentials from the config file (for example, C(/root/.my.cnf)) are not needed to connect to a database server, but
      the file exists and does not contain a C([client]) section, before any other valid directives, it will be read and this
      will cause the connection to fail, to prevent this set it to an empty string, (for example C(config_file: ''))."

plugins/module_utils/mysql.py

@@ -154,6 +154,13 @@ def mysql_connect(module, login_user=None, login_password=None, config_file='',
         db_connection = mysql_driver.connect(autocommit=autocommit, **config)
     else:
         # In case of MySQLdb driver
+
+        # Will be deprecated and dropped
+        # https://github.com/ansible-collections/community.mysql/issues/654
+        module.warn('Support of mysqlcline/MySQLdb connector is deprecated. '
+                    'We\'ll stop testing against it in collection version 4.0.0 '
+                    'and remove the related code in 5.0.0. Use PyMySQL connector instead.')
+
         if mysql_driver.version_info[0] < 2 or (mysql_driver.version_info[0] == 2 and mysql_driver.version_info[1] < 1):
             # for MySQLdb < 2.1.0, use 'db' instead of 'database' and 'passwd' instead of 'password'
             if 'database' in config:

plugins/modules/mysql_info.py

@@ -280,7 +280,6 @@
   type: str
   sample:
   - "pymysql"
-  - "MySQLdb"
   version_added: '3.6.0'
 connector_version:
   description: Version of the python connector used by the module. When the connector is not identified, returns C(Unknown).