feat: Add support for the connector pymysql 1.0.2 (#533)

* Document connector-version relationship

* Fix missing option in the command usage documentation

* Rephrase commands descriptions

* Document that pymysql 0.10.0 disabled its warnings

* Disable tests for pymysql newer than 0.10.0 because the behavior changed

* Enable integration tests for pymysql 1.0.2

* Add exclusion to avoid requesting nonexistent test containers

* Cut comments about PyMySQL 1.0.2 need to be fixed

* docs: explain PyMySQL 0.10.0+ returns changed when using IF EXISTS

.github/workflows/ansible-test-plugins.yml

@@ -64,15 +64,7 @@ jobs:
         connector_version:
           - 0.7.11
           - 0.9.3
-          # Before we can activate test with pymysql 1.0.2 we should debug the
-          # following plugins:
-          #
-          # mysql_query:
-          # test "Assert that create table IF NOT EXISTS is not changed with pymysql" failed
-          #
-          # mysql_replication:
-          # test "Assert that startreplica is not changed" failed
-          # - 1.0.2
+          - 1.0.2
           - 2.0.1
           - 2.0.3
           - 2.1.1
@@ -146,6 +138,9 @@ jobs:
           - db_engine_version: 10.6.11
             python: '3.9'
 
+          - python: '3.8'
+            connector_version: 1.0.2
+
           - python: '3.8'
             connector_version: 2.0.3
 
@@ -155,6 +150,9 @@ jobs:
           - python: '3.9'
             connector_version: 0.7.11
 
+          - python: '3.9'
+            connector_version: 1.0.2
+
           - python: '3.9'
             connector_version: 2.0.1
 

README.md

@@ -85,7 +85,7 @@ 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 >= ???) !!! Unsuported until future release !!!
+- 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)

TESTING.md

@@ -84,7 +84,7 @@ The Makefile accept the following options
   - Choices:
     - "0.7.11" <- pymysql (Only for MySQL 5.7)
     - "0.9.3" <- pymysql
-    - "1.0.2" <- pymysql (Not working, need fix)
+    - "1.0.2" <- pymysql
     - "2.0.1" <- mysqlclient
     - "2.0.3" <- mysqlclient
     - "2.1.1" <- mysqlclient

plugins/modules/mysql_query.py

@@ -26,9 +26,9 @@ options:
       as a formatting character. All literal C(%) characters in the query should be
       escaped as C(%%).
     - Note that if you use the C(IF EXISTS/IF NOT EXISTS) clauses in your query
-      and C(mysqlclient) connector, the module will report that
-      the state has been changed even if it has not. If it is important in your
-      workflow, use the C(PyMySQL) connector instead.
+      and C(mysqlclient) or C(PyMySQL 0.10.0+) connectors, the module will report
+      that the state has been changed even if it has not. If it is important in your
+      workflow, use the C(PyMySQL 0.9.3) connector instead.
     type: raw
     required: true
   positional_args:
@@ -222,7 +222,8 @@ def main():
                     # When something is run with IF NOT EXISTS
                     # and there's "already exists" MySQL warning,
                     # set the flag as True.
-                    # PyMySQL throws the warning, mysqlclinet does NOT.
+                    # PyMySQL < 0.10.0 throws the warning, mysqlclient
+                    # and PyMySQL 0.10.0+ does NOT.
                     already_exists = True
 
         except Exception as e:

tests/integration/targets/test_mysql_query/tasks/mysql_query_initial.yml

@@ -363,21 +363,27 @@
   - name: Assert that create table IF NOT EXISTS is not changed with pymysql
     assert:
       that:
-        # PyMySQL driver throws a warning, so the following is correct
+        # PyMySQL driver throws a warning for version before 0.10.0
         - result is not changed
     when:
       - connector_name == 'pymysql'
+      - connector_version is version('0.10.0', '<')
 
   # Issue https://github.com/ansible-collections/community.mysql/issues/268
   - name: Assert that create table IF NOT EXISTS is changed with mysqlclient
     assert:
       that:
-        # Mysqlclient 2.0.1, driver throws nothing with mysql, so it's
-        # impossible to figure out  if the state was changed or not.
+        # Mysqlclient 2.0.1 and pymysql 0.10.0+ drivers throws no warning,
+        # so it's impossible to figure out if the state was changed or not.
         # We assume that it was for DDL queries by default in the code
         - result is changed
     when:
-      - connector_name == 'mysqlclient'
+      - >
+        connector_name == 'mysqlclient'
+        or (
+          connector_name == 'pymysql'
+          and connector_version is version('0.10.0', '>')
+        )
 
   - name: Drop db {{ test_db }}
     mysql_query:

tests/integration/targets/test_mysql_replication/tasks/mysql_replication_initial.yml

@@ -247,13 +247,14 @@
         fail_on_error: true
       register: result
 
-    # mysqlclient 2.0.1 always return "changed"
+    # mysqlclient 2.0.1 and pymysql 0.10.0+ always return "changed"
     - name: Assert that startreplica is not changed
       assert:
         that:
           - result is not changed
       when:
         - connector_name == 'pymysql'
+        - connector_version is version('0.10.0', '<')
 
     # Test stopreplica mode:
     - name: Stop replica
@@ -274,7 +275,7 @@
         timeout: 2
 
     # Test stopreplica mode:
-    # mysqlclient 2.0.1 always return "changed"
+    # mysqlclient 2.0.1 and pymysql 0.10.0+ always return "changed"
     - name: Stop replica that is no longer running
       mysql_replication:
         <<: *mysql_params
@@ -289,6 +290,7 @@
           - result is not changed
       when:
         - connector_name == 'pymysql'
+        - connector_version is version('0.10.0', '<')
 
     # master / slave related choices were removed in 3.0.0
     # https://github.com/ansible-collections/community.mysql/pull/252