Skip to content

ProxySQL MySQL Binlog Reader v2.5.0

Latest

Choose a tag to compare

@renecannao renecannao released this 28 Sep 18:36
6b3e8fd

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_pos when 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_id and sequence_nr become a domain:sequence position.
  • MariaDB domain ids are validated as a canonical decimal uint32, so 0 and 00 can never name the same domain and a value above UINT32_MAX is rejected instead of truncated.
  • An empty @@gtid_binlog_pos is 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> (default 5) enables replication heartbeats, so an idle stream stays provably alive instead of looking like a stall.
  • --read-timeout=<seconds> (default 60) 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 most INT_MAX/1000 seconds — the MariaDB Connector/C stores the timeout as a millisecond count in a signed int, 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  # amd64

For configuration examples and the full TLS option reference, see the README.

Full Changelog: v2.4.0...v2.5.0