diff --git a/README.md b/README.md index 2678f314..98e90b2f 100644 --- a/README.md +++ b/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 diff --git a/changelogs/fragments/3-deprecate_mysqlclient.yml b/changelogs/fragments/3-deprecate_mysqlclient.yml new file mode 100644 index 00000000..9134413d --- /dev/null +++ b/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). diff --git a/plugins/doc_fragments/mysql.py b/plugins/doc_fragments/mysql.py index 27ec6509..a52243b3 100644 --- a/plugins/doc_fragments/mysql.py +++ b/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: ''))." diff --git a/plugins/module_utils/mysql.py b/plugins/module_utils/mysql.py index 10ccfcf4..97589942 100644 --- a/plugins/module_utils/mysql.py +++ b/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: diff --git a/plugins/modules/mysql_info.py b/plugins/modules/mysql_info.py index 9f0586a3..d8bc88c1 100644 --- a/plugins/modules/mysql_info.py +++ b/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).