MySQL Internals Manual  /  The Binary Log  /  Binary Log Versions

20.8 Binary Log Versions

There are several versions of the binary log file format:

  • v1: Used in MySQL 3.23

  • v3: Used in MySQL 4.0.2 though 4.1

  • v4: Used in MySQL 5.0 and up

A v2 format was used briefly (in early MySQL 4.0.x versions), but it is obsolete and no longer supported.

Programs that process the binary log must be able to account for each of the supported binary log formats. This section describes how the server distinguishes each format to identify which one a binary log file uses. mysqlbinlog uses the same principles.

Important constants:

  • START_EVENT_V3 = 1

  • FORMAT_DESCRIPTION_EVENT = 15

  • EVENT_TYPE_OFFSET = 4

  • EVENT_LEN_OFFSET = 9

  • ST_SERVER_VER_LEN = 50

A binary log file begins with a 4-byte magic number followed by an initial descriptor event that identifies the format of the file.

  • In v1 and v3, this event is called a "start event."

  • In v4, it is called a "format description event."

Elsewhere you may see either term used generically to refer collectively to both types of event. This discussion uses "descriptor event" as the collective term.

The header and data parts of the descriptor event for each binary log format version are shown following. The diagrams use the same conventions as those described earlier in Event Structure.

v1 start event (size = 69 bytes):

+=====================================+
| event  | timestamp         0 : 4    |
| header +----------------------------+
|        | type_code         4 : 1    | = START_EVENT_V3 = 1
|        +----------------------------+
|        | server_id         5 : 4    |
|        +----------------------------+
|        | event_length      9 : 4    | = 69
+=====================================+
| event  | binlog_version   13 : 2    | = 1
| data   +----------------------------+
|        | server_version   15 : 50   |
|        +----------------------------+
|        | create_timestamp 65 : 4    |
+=====================================+

v3 start event (size = 75 bytes):

+=====================================+
| event  | timestamp         0 : 4    |
| header +----------------------------+
|        | type_code         4 : 1    | = START_EVENT_V3 = 1
|        +----------------------------+
|        | server_id         5 : 4    |
|        +----------------------------+
|        | event_length      9 : 4    | = 75
|        +----------------------------+
|        | next_position    13 : 4    |
|        +----------------------------+
|        | flags            17 : 2    |
+=====================================+
| event  | binlog_version   19 : 2    | = 3
| data   +----------------------------+
|        | server_version   21 : 50   |
|        +----------------------------+
|        | create_timestamp 71 : 4    |
+=====================================+

v4 format description event (size ≥ 91 bytes; the size is 76 + the number of event types):

+=====================================+
| event  | timestamp         0 : 4    |
| header +----------------------------+
|        | type_code         4 : 1    | = FORMAT_DESCRIPTION_EVENT = 15
|        +----------------------------+
|        | server_id         5 : 4    |
|        +----------------------------+
|        | event_length      9 : 4    | >= 91
|        +----------------------------+
|        | next_position    13 : 4    |
|        +----------------------------+
|        | flags            17 : 2    |
+=====================================+
| event  | binlog_version   19 : 2    | = 4
| data   +----------------------------+
|        | server_version   21 : 50   |
|        +----------------------------+
|        | create_timestamp 71 : 4    |
|        +----------------------------+
|        | header_length    75 : 1    |
|        +----------------------------+
|        | post-header      76 : n    | = array of n bytes, one byte per event
|        | lengths for all            |   type that the server knows about
|        | event types                |
+=====================================+

In all binary log versions, the event data for the descriptor event begins with a common set of fields

  • binlog_version

The binary log version number (1, 3, or 4).

  • server_version

The server version as a string.

  • create_timestamp

The creation timestamp, if nonzero, is the time in seconds when this event was created; it indicates the moment when the binary log was created. This field is actually of no value: If nonzero, it is redundant because it has the same value that is in the header timestamp.

Note: In practice, the creation timestamp field should be considered reserved for future use and programs should not rely on its value. This field may be commandeered in the future to serve another purpose.

The v4 format descriptor event data contains two additional fields that enable interpretation of other types of events:

  • header_length

The length of the event header. This value includes the extra_headers field, so this header length - 19 yields the size of the extra_headers field.

Currently in v4, the header length (at offset 75) is 19, which means that in other events, no extra headers will follow the flags field. If in the future the header length is some value x > 19, then x-19 extra header bytes will appear in other events in the extra_headers field following the flags field.

Note: The FORMAT_DESCRIPTION_EVENT itself contains no extra_headers field. Suppose that the FDE did have a header_length field after the flags field. That would introduce this problem:

  • The value of x is given in the header_length field, which occurs in a position later than where the extra_headers field would be.

  • Until you know the value of x, you cannot know the exact offset of the header_length field.

In other words, you would need to know x to find the header_length field, but you cannot know x until you read the header_length field. (A circular dependency.) This means that the event extensibility mechanism afforded by the FDE does not apply to the FDE itself, which therefore is not itself extensible.

  • post-header lengths

The lengths for the fixed data part of each event. This is an array that provides post-header lengths for all events beginning with START_EVENT_V3 (type code 1). The array includes no length for UNKNOWN_EVENT (type code 0).


User Comments
Sign Up Login You must be logged in to post a comment.