Add documentation on MySQL 5.7 support

Author: julien-duponchelle

docs/index.rst

@@ -26,6 +26,7 @@ Contents
 
     installation
     limitations
+    mysql57_support
     binlogstream
     events
     examples

docs/mysql57_support.rst

@@ -0,0 +1,69 @@
+.. _mysql57_support:
+
+MySQL 5.7, MySQL 8.0+ and `use_column_name_cache`
+==================================================
+
+In MySQL 5.7 and earlier, the binary log events for row-based replication do not include column name metadata. This means that `python-mysql-replication` cannot map column values to their names directly from the binlog event.
+
+Starting with MySQL 8.0.1, the `binlog_row_metadata` system variable was introduced to control the amount of metadata written to the binary log. The default value for this variable is `MINIMAL`, which provides the same behavior as MySQL 5.7.
+
+The Problem
+-----------
+
+When column metadata is not present in the binlog (as in MySQL 5.7 and earlier, or when `binlog_row_metadata` is set to `MINIMAL` in MySQL 8.0+), the `values` dictionary in a `WriteRowsEvent`, `UpdateRowsEvent`, or `DeleteRowsEvent` will contain integer keys corresponding to the column index, not the column names.
+
+For example, for a table `users` with columns `id` and `name`, an insert event might look like this:
+
+.. code-block:: python
+
+    {0: 1, 1: 'John Doe'}
+
+This can make your replication logic harder to write and maintain, as you need to know the column order.
+
+The Solution: `use_column_name_cache`
+-------------------------------------
+
+To address this, `python-mysql-replication` provides the `use_column_name_cache` parameter for the `BinLogStreamReader`.
+
+When you set `use_column_name_cache=True`, the library will perform a query to the `INFORMATION_SCHEMA.COLUMNS` table to fetch the column names for a given table the first time it encounters an event for that table. The column names are then cached in memory for subsequent events for the same table, avoiding redundant queries.
+
+This allows you to receive row data with column names as keys.
+
+MySQL 8.0+ with `binlog_row_metadata=FULL`
+------------------------------------------
+
+In MySQL 8.0.1 and later, you can set `binlog_row_metadata` to `FULL`. When this setting is enabled, the column names are included directly in the binlog events, and `use_column_name_cache` is not necessary.
+
+Example
+-------
+
+Here is how to enable the column name cache when needed:
+
+.. code-block:: python
+
+    from pymysqlreplication import BinLogStreamReader
+
+    mysql_settings = {'host': '127.0.0.1', 'port': 3306, 'user': 'root', 'passwd': ''}
+
+    # Enable the column name cache for MySQL 5.7 or MySQL 8.0+ with binlog_row_metadata=MINIMAL
+    stream = BinLogStreamReader(
+        connection_settings=mysql_settings,
+        server_id=100,
+        use_column_name_cache=True
+    )
+
+    for binlogevent in stream:
+        if isinstance(binlogevent, WriteRowsEvent):
+            # Now you can access values by column name
+            user_id = binlogevent.rows[0]["values"]["id"]
+            user_name = binlogevent.rows[0]["values"]["name"]
+            print(f"New user: id={user_id}, name={user_name}")
+
+    stream.close()
+
+Important Considerations
+------------------------
+
+*   **Performance:** Enabling `use_column_name_cache` will result in an extra query to the database for each new table encountered in the binlog. The results are cached, so the performance impact should be minimal after the initial query for each table.
+*   **Permissions:** The MySQL user used for replication must have `SELECT` privileges on the `INFORMATION_SCHEMA.COLUMNS` table.
+*   **Default Behavior:** This feature is disabled by default (`use_column_name_cache=False`) to maintain backward compatibility and to avoid making extra queries unless explicitly requested.

pymysqlreplication/tests/base.py

@@ -1,11 +1,12 @@
-import pymysql
 import copy
-from pymysqlreplication import BinLogStreamReader
-import os
 import json
+import os
+import unittest
+
+import pymysql
 import pytest
 
-import unittest
+from pymysqlreplication import BinLogStreamReader
 
 
 def get_databases():

pymysqlreplication/tests/test_basic.py

@@ -1,19 +1,19 @@
 import io
 import time
 import unittest
+from unittest.mock import patch
+
+from pymysql.protocol import MysqlPacket
 
-from pymysqlreplication.json_binary import JsonDiff, JsonDiffOperation
-from pymysqlreplication.tests import base
 from pymysqlreplication import BinLogStreamReader
-from pymysqlreplication.gtid import GtidSet, Gtid
-from pymysqlreplication.event import *
 from pymysqlreplication.constants.BINLOG import *
 from pymysqlreplication.constants.NONE_SOURCE import *
-from pymysqlreplication.row_event import *
+from pymysqlreplication.event import *
+from pymysqlreplication.gtid import Gtid, GtidSet
+from pymysqlreplication.json_binary import JsonDiff, JsonDiffOperation
 from pymysqlreplication.packet import BinLogPacketWrapper
-from pymysql.protocol import MysqlPacket
-from unittest.mock import patch
-
+from pymysqlreplication.row_event import *
+from pymysqlreplication.tests import base
 
 __all__ = [
     "TestBasicBinLogStreamReader",
@@ -276,7 +276,10 @@ def test_fetch_column_names_from_schema(self):
         if not self.isMySQL57AndMore():
             self.skipTest("Test for MySQL 5.7+ where binlog_row_metadata can be MINIMAL")
 
-        self.execute("SET SESSION binlog_row_metadata = 'MINIMAL'")
+        # Minimal is only supported for MySQL 8 and later        
+        if self.isMySQL80AndMore():
+            self.execute("SET SESSION binlog_row_metadata = 'MINIMAL'")
+
         query = "CREATE TABLE test_column_cache (id INT NOT NULL AUTO_INCREMENT, data VARCHAR (50) NOT NULL, PRIMARY KEY (id))"
         self.execute(query)
         self.execute("INSERT INTO test_column_cache (data) VALUES('Hello')")