MySQL Internals Manual  /  ...  /  Determining the Binary Log Version

20.8.1 Determining the Binary Log Version

Given any binary log file, the information in this section describes how to determine the format in which it is written.

Some important points about descriptor event formats:

  • The v1 header fields are common to all formats. (v3 and v4 headers begin with the v1 header fields, and add next_position and flags fields.)

  • The v3 and v4 headers contain the same fields. The data part for v3 and v4 differs, such that the v4 data part enables extensions to the format without having to modify the header.

  • It would be possible to ascertain the binary log version simply by reading the two binlog_version bytes, were it not for the fact that these bytes occur at a different position in v1 compared to v3/v4 (position 13 versus 19). Therefore, it's necessary to determine whether the first event in a file represents a v1-format start event.

To determine the version of a binary log file, use the following procedure:

1) The file begins with a 4-byte magic number. Skip over that to get to the first event in the file (which in most cases is a start event or format description event).

2) From the first event, read two values:

  • The 1-byte type code at position EVENT_TYPE_OFFSET (4) within the event.

  • The 4-byte event length at position EVENT_LEN_OFFSET (9) within the event.

3) If the type code is not START_EVENT_V3 or FORMAT_DESCRIPTION_EVENT, the file format is v3. (See Exceptional Condition 1 later in this section.)

4) If the type code is START_EVENT_V3 (1), check the event length. If the length is less than 75, the file format is v1, and v3 otherwise. Why the value 75? Because that is the length of a v3 start event:

  • header (19 bytes)

  • binlog version (2 bytes)

  • server version (ST_SERVER_VER_LEN = 50 bytes)

  • timestamp (4 bytes)

Summing those lengths yields 19 + 2 + 50 + 4 = 75

Therefore, if the event is shorter than 75 bytes, it must be from a v1 file because that will have a shorter first event than a v3 file.

5) If the type code is FORMAT_DESCRIPTION_EVENT (15), the file format is v4.

The preceding steps describe the general binary log format-recognition principles. However, there are some exceptional conditions that must be accounted for:

Exceptional Condition 1: In MySQL 4.0 and 4.1, the initial event in a binary log file might not be a start event. This occurs because the server writes the start event only to the first binary log file that it creates after startup. For subsequent files, the server writes an event of type ROTATE_EVENT to the end of the current log file, closes it, and the begins the next file without writing a start event to it. If a log file begins with an event that is not START_EVENT_V3 or FORMAT_DESCRIPTION_EVENT, it can be assumed to be a v3 file because this behavior occurs only in MySQL 4.0 and 4.1, and all servers in those versions use v3 format.

Exceptional Condition 2: In MySQL 5.1 and 5.2, several early versions wrote binary log files using v4 format, but using different event numbers from those currently used in v4. Therefore, when the FDE is read and discovered to be v4, it is also necessary to read the server version, which is a string that occurs at position 21. If the version is one of those in the set of affected versions, event renumbering occurs such that events read from the file are mapped onto the current v4 event numbering.