Registry / database / mysql-replication

mysql-replication

JSON →
library1.0.15pypypi✓ verified 82d ago

mysql-replication is a pure Python implementation of the MySQL replication protocol, built on top of PyMYSQL. It enables real-time streaming of binlog events from a MySQL server, facilitating tasks such as change data capture (CDC), data synchronization, and auditing. The current version is 1.0.15, and the project maintains an active release cadence, addressing bugs and adding support for newer Python versions.

pip install mysql-replication
INSTALL
IMPORT
SIG · MYSQL-REPLICATION
M
mysql-replication
databasepythonv1.0.15
Install
1.8s avg
Import
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.15 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.8s · import 0.000s · 20MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BinLogStreamReader
from pymysqlreplication import BinLogStreamReader
from mysql.replication import BinLogStreamReader

This quickstart demonstrates how to connect to a MySQL server's binlog stream and process various row-based replication events (INSERT, UPDATE, DELETE). Ensure your MySQL server is configured for replication, and the provided user has sufficient privileges (`REPLICATION SLAVE`, `REPLICATION CLIENT`). Remember to set a unique `server_id`.

import os from mysql.replication import BinLogStreamReader from mysql.replication.row_event import UpdateRowsEvent, DeleteRowsEvent, WriteRowsEvent # Configure your MySQL connection details. Use environment variables for production. MYSQL_HOST = os.environ.get('MYSQL_HOST', 'localhost') MYSQL_PORT = int(os.environ.get('MYSQL_PORT', 3306)) MYSQL_USER = os.environ.get('MYSQL_USER', 'replication_user') MYSQL_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'password') # Ensure user has REPLICATION SLAVE/CLIENT try: stream = BinLogStreamReader( connection_settings={ "host": MYSQL_HOST, "port": MYSQL_PORT, "user": MYSQL_USER, "passwd": MYSQL_PASSWORD, "charset": "utf8" }, server_id=101, # IMPORTANT: Must be a unique ID > 0 within your replication topology blocking=True, # Wait for new events if no more are available resume_stream=True, # Resume from last position if possible log_file=None, # Start from current position log_pos=None # Start from current position ) print(f"Connected to MySQL binlog stream on {MYSQL_HOST}:{MYSQL_PORT}. Listening for events...") for event in stream: if isinstance(event, (UpdateRowsEvent, DeleteRowsEvent, WriteRowsEvent)): print(f"\n---") print(f"[{type(event).__name__}] Database: {event.schema}, Table: {event.table}") for row in event.rows: if isinstance(event, WriteRowsEvent): print(f" Inserted: {row['values']}") elif isinstance(event, UpdateRowsEvent): print(f" Before: {row['before_values']}") print(f" After: {row['after_values']}") elif isinstance(event, DeleteRowsEvent): print(f" Deleted: {row['values']}") # Add more event types (e.g., QueryEvent, RotateEvent, XidEvent) as needed except Exception as e: print(f"An error occurred: {e}") finally: if 'stream' in locals() and stream: stream.close() print("\nBinLogStreamReader closed.")
Debug
Known issues
gotchaOlder versions (<=1.0.14) of `mysql-replication` could potentially log sensitive connection information (e.g., passwords) if logging was not carefully configured, especially in verbose modes.
fix
Upgrade to version `1.0.15` or newer. Always review your logging configuration in production environments to prevent exposure of sensitive data.
affects: <=1.0.14
gotchaThe `server_id` parameter in `BinLogStreamReader` must be a unique integer greater than 0 within your entire MySQL replication topology. Using a duplicate `server_id` can lead to unexpected behavior or replication conflicts.
fix
Ensure `server_id` is unique for each client connecting to the binlog. A common practice is to pick a high, unused number like 101 or 1000+.
affects: All versions
gotchaYour MySQL server must be explicitly configured for binlog replication. This includes enabling `log_bin`, setting a unique `server-id` in `my.cnf`, and typically `binlog_format = ROW` to get detailed row changes. The replication user also needs `REPLICATION SLAVE` and `REPLICATION CLIENT` privileges.
fix
Configure `my.cnf` with `log_bin`, `server-id`, `binlog_format=ROW`. Grant necessary permissions: `GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'replication_user'@'%' IDENTIFIED BY 'password';` then `FLUSH PRIVILEGES;`.
affects: All versions
Upgrade
Version history
1.0.15latest on PyPI · released Feb 7, 2026
Audit
Dependencies
PyMySQLrequiredCore database driver used for establishing the connection to the MySQL server.
Agent activity
4 hits · last 30 days
node
4
Resources
mysql-replication — pip install mysql-replication · libregistry