Repository navigation
ProxySQL MySQL Binlog Reader v2.5.0
This release adds MariaDB GTID support to the reader, and makes the replication stream observable and controllable from the command line. The reader can now connect to a MariaDB backend, snapshot its GTID position from @@gtid_binlog_pos, and stream MariaDB GTID_EVENTs to ProxySQL as domain:sequence positions.
MariaDB GTID support
The reader previously assumed a MySQL backend: it required Executed_Gtid_Set in SHOW MASTER STATUS and stopped when that column was absent. MariaDB does not report an executed GTID set, so the reader could not be used with it at all.
- The reader detects the backend flavor and reads the snapshot from
@@gtid_binlog_poswhen the MySQL fifth column is missing or empty. An invalid non-empty MySQL column still fails rather than silently falling back. - MariaDB
GTID_EVENTs are decoded from the event body:domain_idandsequence_nrbecome adomain:sequenceposition. - MariaDB domain ids are validated as a canonical decimal
uint32, so0and00can never name the same domain and a value aboveUINT32_MAXis rejected instead of truncated. - An empty
@@gtid_binlog_posis treated as a valid empty GTID set: the reader waits for the first non-empty position rather than failing to start. - Covered by a live TAP test against MariaDB 10.11 that asserts the snapshot line, a streamed update, and the reader's own
to_string()/to_display_string()wire-vs-display split.
On the wire, a MariaDB id is domain:start-end — for example ST=0:1-270. This is GTID_Set::to_string(), not MariaDB's native domain-server-sequence spelling. The two are not interchangeable, and the design document now states both explicitly.
Replication heartbeats and read timeouts
A silent network partition between the reader and its backend previously left the reader blocked indefinitely, with nothing in the logs to show why.
--heartbeat-period=<seconds>(default5) enables replication heartbeats, so an idle stream stays provably alive instead of looking like a stall.--read-timeout=<seconds>(default60) bounds how long a read may block, so a partition surfaces as an error rather than a hang. It must be positive, at least three times the heartbeat period, and at mostINT_MAX/1000seconds — the MariaDB Connector/C stores the timeout as a millisecond count in a signedint, so a larger value would wrap into a bogus timeout and is rejected at startup instead.- A read timeout now reports a specific, actionable error rather than falling back to a generic connector message.
- Covered by live tests that assert a heartbeat keeps an idle stream alive and that the read timeout is enforced.
Explicit listener bind addresses
The listener address is now parsed rather than treated as a bare port, so -l accepts a full address in addition to a port:
-l 6020— IPv4 wildcard (unchanged behaviour)-l 10.0.0.5:6020— bind a specific IPv4 address-l [::1]:6020— bind a specific IPv6 address
This is for deployments that need the reader reachable on one interface only, instead of every interface. Numeric addresses only; hostnames are not resolved. Covered by dedicated listener bind and option TAP tests.
Native ARM64 release images
Runtime images are now built and published for ARM64 alongside AMD64, and the multi-architecture manifests are created by the release pipeline rather than assembled by hand.
ARM64 is available through the multi-architecture tags: 2.5.0, 2.5.0-debian13, 2.5.0-ubuntu24, and the unversioned latest, debian, and ubuntu aliases. The 2.5.0-ubuntu22, 2.5.0-debian12, 2.5.0-centos9, and 2.5.0-centos10 tags remain AMD64-only — each of those is published with publish_amd64 in the release workflow, so they carry a single architecture exactly as in v2.4.0. If you need ARM64, use a Debian 13 or Ubuntu 24.04 base, or the bare version tag.
Release pipeline hardening
Published images are verified to be anonymously readable from GHCR, and the image metadata (including the OCI source labels) is validated in CI, so a release cannot silently publish an image that consumers cannot pull or that cannot be traced back to a commit.
Container images continue to be published only after the full runtime test gate passes on CentOS 9, CentOS 10, Debian 12, Debian 13, Ubuntu 22.04, and Ubuntu 24.04.
Available artifacts
Debian and RPM packages for all six targets, plus GHCR images:
docker pull ghcr.io/sysown/proxysql-mysqlbinlog:2.5.0 # multi-arch
docker pull ghcr.io/sysown/proxysql-mysqlbinlog:2.5.0-ubuntu22 # amd64For configuration examples and the full TLS option reference, see the README.
Full Changelog: v2.4.0...v2.5.0