MySQL Bugs: #116747: Internals docs incomplete for replication/gtid

Bug #116747	Internals docs incomplete for replication/gtid
Submitted:	21 Nov 2024 13:07	Modified:	10 Jan 17:00
Reporter:	Daniël van Eeden (OCA)	Email Updates:
Status:	Verified	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S2 (Serious)
Version:	9.1.0	OS:	Any
Assigned to:		CPU Architecture:	Any
Tags:	Contribution

Description:
GTID is an important part of replication today and especially with the changes for tagged GTID and the many products that use replication for Change Data Capture (CDC) it should be documented appropriately. Applications written in C that use the binlog could probably use a library, but applications in Java, Go, etc can't easily use a C library.

Page: https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_replication.html
This mentioned "COM_BINLOG_DUMP", but not "COM_BINLOG_DUMP_GTID"

There is https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_com_binlog_dump.html but there is no page for COM_BINLOG_DUMP_GTID

https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_replication_binlog_event.h... doesn't seem to mention GTID at all

PREVIOUS_GTIDS_LOG_EVENT seems to be poorly documented. https://dev.mysql.com/doc/dev/mysql-server/latest/classmysql_1_1binlog_1_1event_1_1Previou... describes the binary format, but this doesn't seem to match actual events. The GTIDs are encoded in two formats: tagged and untagged and how this encoding is done isn't well documented.

GTID_TAGGED_LOG_EVENT isn't well documented and the docs for mysql::serialization that it uses could use some better examples. https://dev.mysql.com/doc/dev/mysql-server/latest/PageLibsMysqlSerialization.html lists some examples, but it is difficult to match these with actual on the wire data. Maybe have the output of `mysqldump --hexdump ...` and use that to explain the encoding.

How to repeat:
See description

Hello Daniël,

Thank you for the report and feedback.

regards,
Umesh

https://dev.mysql.com/doc/dev/mysql-server/latest/page_protocol_replication.html doesn't seem to mention COM_REGISTER_SLAVE

This command has an entry in enum_server_command: https://dev.mysql.com/doc/dev/mysql-server/latest/my__command_8h.html#ae2ff1badf13d2b8099a... but the description next to it is empty.

Contribution/Patch

Attachment: 0001-Docs-update-replication-relatated-documentation.patch (text/x-patch), 16.70 KiB.

Added the Contribution tag