MySQL 9.0.0
Source Code Documentation
binlog_event.h
Go to the documentation of this file.
1/* Copyright (c) 2011, 2024, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is designed to work with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24/// @defgroup GroupLibsMysql MySQL Libraries
25
26/// @defgroup GroupLibsMysqlBinlog MySQL Libraries : Binlog Libraries
27/// @ingroup GroupLibsMysql
28
29/// @defgroup GroupLibsMysqlBinlogEvent MySQL Libraries : Binlog Event
30/// @ingroup GroupLibsMysqlBinlog
31
32/**
33 @file binlog_event.h
34
35 @brief Contains the classes representing events occurring in the replication
36 stream. Each event is represented as a byte sequence with logical divisions
37 as event header, event specific data and event footer. The header and footer
38 are common to all the events and are represented as two different subclasses.
39*/
40
41#ifndef MYSQL_BINLOG_EVENT_BINLOG_EVENT_H
42#define MYSQL_BINLOG_EVENT_BINLOG_EVENT_H
43
44#include <stdlib.h>
45#include <string.h>
46#include <sys/types.h>
47#include <zlib.h> //for checksum calculations
48#include <climits>
49#include <cstdio>
50#include <iostream>
51
52#include "my_checksum.h"
53#include "my_io.h"
57
58#if defined(_WIN32)
59#include <Winsock2.h>
60#else
61#include <sys/times.h>
62#endif
63
64/// @addtogroup GroupLibsMysqlBinlogEvent
65/// @{
66
67/*
68 The symbols below are a part of the common definitions between
69 the MySQL server and the client. Since they should not be a part of
70 this library but the server, these should be placed in a header file
71 common to the library and the MySQL server code, so that if they are
72 updated in the server code, it is reflected in the libbinlogevent also.
73
74 TODO(WL#7984): Moving the binlog constant in library libbinlogevents into a
75 separate file and make them const variables
76*/
77#ifndef SYSTEM_CHARSET_MBMAXLEN
78#define SYSTEM_CHARSET_MBMAXLEN 3
79#endif
80#ifndef NAME_CHAR_LEN
81#define NAME_CHAR_LEN 64 /* Field/table name length */
82#endif
83#ifndef NAME_LEN
84#define NAME_LEN (NAME_CHAR_LEN * SYSTEM_CHARSET_MBMAXLEN)
85#endif
86/* Length of the server_version_split array in FDE class */
87#ifndef ST_SERVER_VER_SPLIT_LEN
88#define ST_SERVER_VER_SPLIT_LEN 3
89#endif
90
91/*
92 Do not decrease the value of BIN_LOG_HEADER_SIZE.
93 Do not even increase it before checking code.
94*/
95#ifndef BIN_LOG_HEADER_SIZE
96#define BIN_LOG_HEADER_SIZE 4U
97#endif
98
99/**
100 binlog_version 3 is MySQL 4.x; 4 is MySQL 5.0.0.
101 Compared to version 3, version 4 has:
102 - a different Start_event, which includes info about the binary log
103 (sizes of headers); this info is included for better compatibility if the
104 master's MySQL version is different from the slave's.
105*/
106#define BINLOG_VERSION 4
107
108/*
109 Constants used by Query_event.
110*/
111
112/**
113 The maximum number of updated databases that a status of
114 Query-log-event can carry. It can be redefined within a range
115 [1.. OVER_MAX_DBS_IN_EVENT_MTS].
116*/
117#define MAX_DBS_IN_EVENT_MTS 16
118
119/**
120 When the actual number of databases exceeds MAX_DBS_IN_EVENT_MTS
121 the value of OVER_MAX_DBS_IN_EVENT_MTS is is put into the
122 mts_accessed_dbs status.
123*/
124#define OVER_MAX_DBS_IN_EVENT_MTS 254
125
126/**
127 Maximum length of time zone name that we support (Time zone name is
128 char(64) in db). mysqlbinlog needs it.
129*/
130#define MAX_TIME_ZONE_NAME_LENGTH (NAME_LEN + 1)
131
132/**
133 Max number of possible extra bytes in a replication event compared to a
134 packet (i.e. a query) sent from client to master;
135 First, an auxiliary log_event status vars estimation:
136*/
137#define MAX_SIZE_LOG_EVENT_STATUS \
138 (1U + 4 /* type, flags2 */ + 1U + 8 /* type, sql_mode */ + 1U + 1 + \
139 255 /* type, length, catalog */ + 1U + 4 /* type, auto_increment */ + 1U + \
140 6 /* type, charset */ + 1U + 1 + \
141 MAX_TIME_ZONE_NAME_LENGTH /* type, length, time_zone */ + 1U + \
142 2 /* type, lc_time_names_number */ + 1U + \
143 2 /* type, charset_database_number */ + 1U + \
144 8 /* type, table_map_for_update */ + 1U + 1 + \
145 32 * 3 /* type, user_len, user */ + 1 + 255 /* host_len, host */ \
146 + 1U + 1 + \
147 (MAX_DBS_IN_EVENT_MTS * (1 + NAME_LEN)) /* type, db_1, db_2, ... */ \
148 + 1U + 3 /* type, microseconds */ + 1U + 1 /* type, explicit_def..ts*/ + \
149 1U + 8 /* type, xid of DDL */ + 1U + \
150 2 /* type, default_collation_for_utf8mb4_number */ + 1U + \
151 1 /* sql_require_primary_key */ + 1U + \
152 1 /* type, default_table_encryption */)
153
154/**
155 Uninitialized timestamp value (for either last committed or sequence number).
156 Often carries meaning of the minimum value in the logical timestamp domain.
157*/
158const int64_t SEQ_UNINIT = 0;
159
160/** We use 7 bytes, 1 bit being used as a flag. */
161#define MAX_COMMIT_TIMESTAMP_VALUE (1ULL << 55)
162/**
163 Used to determine whether the original_commit_timestamp is already known or if
164 it still needs to be determined when computing it.
165*/
167
168const uint32_t UNDEFINED_SERVER_VERSION = 999999;
169const uint32_t UNKNOWN_SERVER_VERSION = 0;
170
171/** Setting this flag will mark an event as Ignorable */
172#define LOG_EVENT_IGNORABLE_F 0x80
173
174/**
175 In case the variable is updated,
176 make sure to update it in $MYSQL_SOURCE_DIR/my_io.h.
177*/
178#ifndef FN_REFLEN
179#define FN_REFLEN 512 /* Max length of full path-name */
180#endif
181
182/**
183 Splits server 'version' string into three numeric pieces stored
184 into 'split_versions':
185 X.Y.Zabc (X,Y,Z numbers, a not a digit) -> {X,Y,Z}
186 X.Yabc -> {X,Y,0}
187
188 @param version String representing server version
189 @param split_versions Array with each element containing one split of the
190 input version string
191*/
192inline void do_server_version_split(const char *version,
193 unsigned char split_versions[3]) {
194 const char *p = version;
195 char *r;
196 unsigned long number;
197 for (unsigned int i = 0; i <= 2; i++) {
198 number = strtoul(p, &r, 10);
199 /*
200 It is an invalid version if any version number greater than 255 or
201 first number is not followed by '.'.
202 */
203 if (number < 256 && (*r == '.' || i != 0))
204 split_versions[i] = static_cast<unsigned char>(number);
205 else {
206 split_versions[0] = 0;
207 split_versions[1] = 0;
208 split_versions[2] = 0;
209 break;
210 }
211
212 p = r;
213 if (*r == '.') p++; // skip the dot
214 }
215}
216
217/**
218 Transforms the server version from 'XX.YY.ZZ-suffix' into an integer in the
219 format XXYYZZ.
220
221 @param version String representing server version
222 @return The server version in the format XXYYZZ
223*/
224inline uint32_t do_server_version_int(const char *version) {
225 unsigned char version_split[3];
226 do_server_version_split(version, version_split);
227 const uint32_t ret = static_cast<uint32_t>(version_split[0]) * 10000 +
228 static_cast<uint32_t>(version_split[1]) * 100 +
229 static_cast<uint32_t>(version_split[2]);
230 return ret;
231}
232
233/**
234 Calculate the version product from the numeric pieces representing the server
235 version:
236 For a server version X.Y.Zabc (X,Y,Z numbers, a not a digit), the input is
237 {X,Y,Z}. This is converted to XYZ in bit representation.
238
239 @param version_split Array containing the version information of the server
240 @return The version product of the server
241*/
242inline unsigned long version_product(const unsigned char *version_split) {
243 return ((version_split[0] * 256 + version_split[1]) * 256 + version_split[2]);
244}
245
246/**
247 Replication event checksum is introduced in the following "checksum-home"
248 version. The checksum-aware servers extract FD's version to decide whether
249 the FD event carries checksum info.
250*/
251extern const unsigned char checksum_version_split[3];
252extern const unsigned long checksum_version_product;
253/**
254 @namespace mysql::binlog::event
255
256 The namespace contains classes representing events that can occur in a
257 replication stream.
258*/
259namespace mysql::binlog::event {
260/*
261 This flag only makes sense for Format_description_event. It is set
262 when the event is written, and *reset* when a binlog file is
263 closed (yes, it's the only case when MySQL modifies an already written
264 part of the binlog). Thus it is a reliable indicator that the binlog was
265 closed correctly. (Stop_event is not enough, there's always a
266 small chance that mysqld crashes in the middle of insert and end of
267 the binlog would look like a Stop_event).
268
269 This flag is used to detect a restart after a crash, and to provide
270 "unbreakable" binlog. The problem is that on a crash storage engines
271 rollback automatically, while binlog does not. To solve this we use this
272 flag and automatically append ROLLBACK to every non-closed binlog (append
273 virtually, on reading, file itself is not changed). If this flag is found,
274 mysqlbinlog simply prints "ROLLBACK". Replication master does not abort on
275 binlog corruption, but takes it as EOF, and replication slave forces a
276 rollback in this case.
277
278 Note, that old binlogs does not have this flag set, so we get a
279 a backward-compatible behaviour.
280*/
281#define LOG_EVENT_BINLOG_IN_USE_F 0x1
282
283/**
284 Enumeration type for the different types of log events.
285*/
287 /**
288 Every time you add a type, you have to
289 - Assign it a number explicitly. Otherwise it will cause trouble
290 if a event type before is deprecated and removed directly from
291 the enum.
292 - Fix Format_description_event::Format_description_event().
293 */
295 /*
296 Deprecated since mysql 8.0.2. It is just a placeholder,
297 should not be used anywhere else.
298 */
304
306
309
316
318
319 /*
320 The V1 event numbers are used from 5.1.16 until mysql-5.6.
321 Not generated since 8.2.0, and rejected by the applier since 8.4.0
322 */
326
327 /**
328 Something out of the ordinary happened on the master
329 */
331
332 /**
333 Heartbeat event to be send by master at its idle time
334 to ensure master's online status to slave
335 */
337
338 /**
339 In some situations, it is necessary to send over ignorable
340 data to the slave: data that a slave can handle in case there
341 is code for handling it, but which can be ignored if it is not
342 recognized.
343 */
346
347 /** Version 2 of the Row events */
351
354
356
358
360
361 /* Prepared XA transaction terminal event similar to Xid */
363
364 /**
365 Extension of UPDATE_ROWS_EVENT, allowing partial values according
366 to binlog_row_value_options.
367 */
369
371
373
375 /**
376 Add new events here - right above this comment!
377 Existing events (except ENUM_END_EVENT) should never change their numbers
378 */
379 ENUM_END_EVENT /* end marker */
381
382/**
383 @brief Get the event type as string object
384
385 @param type the event type for which to get a textual representation.
386 @return std::string a text representing the event name.
387*/
389
390/// @brief Event type helpers, enclosed in the structure
392 /// @brief Helps to identify known GTID event - returns true
393 /// for GTID_LOG_EVENT and GTID_TAGGED_LOG_EVENT
394 inline static bool is_assigned_gtid_event(const Log_event_type &type) {
396 }
397 /// @brief Helps to identify any GTID event - returns true
398 /// for GTID_LOG_EVENT, GTID_TAGGED_LOG_EVENT and ANONYMOUS_GTID_LOG_EVENT
399 inline static bool is_any_gtid_event(const Log_event_type &type) {
401 }
402};
403
404/**
405 Struct to pass basic information about a event: type, query, is it ignorable
406*/
409 const char *query{nullptr};
410 size_t query_length{0};
411 bool ignorable_event{false};
412};
413
414/**
415 The length of the array server_version, which is used to store the version
416 of MySQL server.
417 We could have used SERVER_VERSION_LENGTH, but this introduces an
418 obscure dependency - if somebody decided to change SERVER_VERSION_LENGTH
419 this would break the replication protocol
420 both of these are used to initialize the array server_version
421 SERVER_VERSION_LENGTH is used for global array server_version
422 and ST_SERVER_VER_LEN for the Start_event_v3 member server_version
423*/
424
425#define ST_SERVER_VER_LEN 50
426
427/*
428 Event header offsets;
429 these point to places inside the fixed header.
430*/
431#define EVENT_TYPE_OFFSET 4
432#define SERVER_ID_OFFSET 5
433#define EVENT_LEN_OFFSET 9
434#define LOG_POS_OFFSET 13
435#define FLAGS_OFFSET 17
436
437/** start event post-header (for v3 and v4) */
438#define ST_BINLOG_VER_OFFSET 0
439#define ST_SERVER_VER_OFFSET 2
440#define ST_CREATED_OFFSET (ST_SERVER_VER_OFFSET + ST_SERVER_VER_LEN)
441#define ST_COMMON_HEADER_LEN_OFFSET (ST_CREATED_OFFSET + 4)
442
443#define LOG_EVENT_HEADER_LEN 19U /* the fixed header length */
444
445/// The maximum value for MAX_ALLOWED_PACKET. This is also the
446/// maxmium size of binlog events, and dump threads always use this
447/// value for max_allowed_packet.
448constexpr size_t max_log_event_size = 1024 * 1024 * 1024;
449
450/**
451 Fixed header length, where 4.x and 5.0 agree. That is, 5.0 may have a longer
452 header (it will for sure when we have the unique event's ID), but at least
453 the first 19 bytes are the same in 4.x and 5.0. So when we have the unique
454 event's ID, LOG_EVENT_HEADER_LEN will be something like 26, but
455 LOG_EVENT_MINIMAL_HEADER_LEN will remain 19.
456*/
457#define LOG_EVENT_MINIMAL_HEADER_LEN 19U
458
459/**
460 Enumeration spcifying checksum algorithm used to encode a binary log event
461*/
463 /**
464 Events are without checksum though its generator is checksum-capable
465 New Master (NM).
466 */
468 /** CRC32 of zlib algorithm */
470 /** the cut line: valid alg range is [1, 0x7f] */
472 /**
473 Special value to tag undetermined yet checksum or events from
474 checksum-unaware servers
475 */
478
479#define CHECKSUM_CRC32_SIGNATURE_LEN 4
480
481/**
482 defined statically while there is just one alg implemented
483*/
484#define BINLOG_CHECKSUM_LEN CHECKSUM_CRC32_SIGNATURE_LEN
485#define BINLOG_CHECKSUM_ALG_DESC_LEN 1 /* 1 byte checksum alg descriptor */
486#define LOG_EVENT_HEADER_SIZE 20
487
488/**
489 Calculate a long checksum for a memoryblock.
490
491 @param crc start value for crc
492 @param pos pointer to memory block
493 @param length length of the block
494
495 @return checksum for a memory block
496*/
497inline uint32_t checksum_crc32(uint32_t crc, const unsigned char *pos,
498 size_t length) {
499 BAPI_ASSERT(length <= UINT_MAX);
500 return my_checksum(crc, pos, length);
501}
502
503/*
504 Forward declaration of Format_description_event class to be used in class
505 Log_event_header
506*/
508
509/**
510 @class Log_event_footer
511
512 The footer, in the current version of the MySQL server, only contains
513 the checksum algorithm descriptor. The descriptor is contained in the
514 FDE of the binary log. This is common for all the events contained in
515 that binary log, and defines the algorithm used to checksum
516 the events contained in the binary log.
517
518 @anchor Table_common_footer
519 The footer contains the following:
520 <table>
521 <caption>Common-Footer</caption>
522
523 <tr>
524 <th>Name</th>
525 <th>Format</th>
526 <th>Description</th>
527 </tr>
528
529 <tr>
530 <td>checkusm_alg</td>
531 <td>enum_checksum_alg</td>
532 <td>Algorithm used to checksum the events contained in the binary log</td>
533 </tr>
534
535 </table>
536
537 @note checksum *value* is not generated with the event. On master's side, it
538 is calculated right before writing the event into the binary log. The
539 data_written field of the event is adjusted (+BINLOG_CHECKSUM_LEN) to
540 consider the checksum value as part of the event. On reading the event,
541 if the Format Description Event (FDE) used when serializing the event
542 tells that the events have checksum information, the checksum value can
543 be retrieved from a particular offset of the serialized event buffer
544 (event length - BINLOG_CHECKSUM_LEN) and checked for corruption by
545 computing a new value over the event buffer. It is not required after
546 that. Therefore, the checksum value is not required to be stored in the
547 instance as a class member.
548*/
550 public:
551 /**
552 Wrapper to call get_checksum_alg(const char *, ulong) function based on the
553 event reader object (which knows both buffer and buffer length).
554
555 @param[in] reader The Event_reader object associated to the event buffer
556 of the FD event.
557
558 @retval BINLOG_CHECKSUM_ALG_UNDEF originator is checksum-unaware
559 (effectively no checksum).
560 @retval BINLOG_CHECKSUM_ALG_OFF no checksum.
561 @retval other the actual checksum algorithm descriptor.
562 */
564
565 /**
566 The method returns the checksum algorithm used to checksum the binary log
567 from a Format Description Event serialized buffer.
568
569 For MySQL server versions < 5.6, the algorithm is undefined.
570
571 @param buf buffer holding serialized FD event.
572 @param len length of the event buffer.
573
574 @retval BINLOG_CHECKSUM_ALG_UNDEF originator is checksum-unaware
575 (effectively no checksum).
576 @retval BINLOG_CHECKSUM_ALG_OFF no checksum.
577 @retval other the actual checksum algorithm descriptor.
578 */
580 unsigned long len);
581
582 static bool event_checksum_test(unsigned char *buf, unsigned long event_len,
584
585 /* Constructors */
587
588 /**
589 This ctor will create a new object of Log_event_footer, and will adjust
590 the event reader buffer size with respect to CRC usage.
591
592 @param reader the Event_reader containing the serialized event (including
593 header, event data and optional checksum information).
594 @param event_type the type of the event the footer belongs to.
595 @param fde An FDE event, used to get information about CRC.
596 */
597 Log_event_footer(Event_reader &reader, Log_event_type event_type,
598 const Format_description_event *fde);
599
601 : checksum_alg(checksum_alg_arg) {}
602
603 /**
604 @verbatim
605 Master side:
606 The value is set by caller of FD(Format Description) constructor
607 In the FD case it's propagated into the last byte
608 of post_header_len[].
609 Slave side:
610 On the slave side the value is assigned from post_header_len[last]
611 of the last seen FD event.
612 @endverbatim
613 TODO(WL#7546): Revisit this comment when encoder is moved in libbinlogevent
614 */
616};
617
618/**
619 @class Log_event_header
620
621 The Common-Header always has the same form and length within one
622 version of MySQL. Each event type specifies a format and length
623 of the Post-Header. The length of the Common-Header is the same
624 for all events of the same type.
625
626 @anchor Table_common_header
627 The binary format of Common-Header is as follows:
628 <table>
629 <caption>Common-Header</caption>
630
631 <tr>
632 <th>Name</th>
633 <th>Format</th>
634 <th>Description</th>
635 </tr>
636
637 <tr>
638 <td>when</td>
639 <td>4 byte unsigned integer, represented by type struct timeval</td>
640 <td>The time when the query started, in seconds since 1970.
641 </td>
642 </tr>
643
644 <tr>
645 <td>type_code</td>
646 <td>1 byte enumeration</td>
647 <td>See enum #Log_event_type.</td>
648 </tr>
649
650 <tr>
651 <td>unmasked_server_id</td>
652 <td>4 byte unsigned integer</td>
653 <td>Server ID of the server that created the event.</td>
654 </tr>
655
656 <tr>
657 <td>data_written</td>
658 <td>4 byte unsigned integer</td>
659 <td>The total size of this event, in bytes. In other words, this
660 is the sum of the sizes of Common-Header, Post-Header, and Body.
661 </td>
662 </tr>
663
664 <tr>
665 <td>log_pos</td>
666 <td>4 byte unsigned integer</td>
667 <td>The position of the next event in the master binary log, in
668 bytes from the beginning of the file. In a binlog that is not a
669 relay log, this is just the position of the next event, in bytes
670 from the beginning of the file. In a relay log, this is
671 the position of the next event in the master's binlog.
672 </td>
673 </tr>
674
675 <tr>
676 <td>flags</td>
677 <td>2 byte bitfield</td>
678 <td>16 or less flags depending on the version of the binary log.</td>
679 </tr>
680 </table>
681
682 Summing up the numbers above, we see that the total size of the
683 common header is 19 bytes.
684*/
686 public:
687 /*
688 Timestamp on the master(for debugging and replication of
689 NOW()/TIMESTAMP). It is important for queries and LOAD DATA
690 INFILE. This is set at the event's creation time, except for Query
691 and Load (and other events) events where this is set at the query's
692 execution time, which guarantees good replication (otherwise, we
693 could have a query and its event with different timestamps).
694 */
695 struct timeval when;
696
697 /**
698 Event type extracted from the header. In the server, it is decoded
699 by read_log_event(), but adding here for complete decoding.
700 */
702
703 /*
704 The server id read from the Binlog.
705 */
706 unsigned int unmasked_server_id;
707
708 /* Length of an event, which will be written by write() function */
710
711 /*
712 The offset in the log where this event originally appeared (it is
713 preserved in relay logs, making SHOW REPLICA STATUS able to print
714 coordinates of the event in the master's binlog).
715 */
716 unsigned long long log_pos;
717
718 /*
719 16 or less flags depending on the version of the binary log.
720 See the definitions above for LOG_EVENT_TIME_F,
721 LOG_EVENT_FORCED_ROTATE_F, LOG_EVENT_THREAD_SPECIFIC_F, and
722 LOG_EVENT_SUPPRESS_USE_F for notes.
723 */
724 uint16_t flags;
725
726 /**
727 The following type definition is to be used whenever data is placed
728 and manipulated in a common buffer. Use this typedef for buffers
729 that contain data containing binary and character data.
730 */
731 typedef unsigned char Byte;
732
734 : type_code(type_code_arg), data_written(0), log_pos(0), flags(0) {
735 when.tv_sec = 0;
736 when.tv_usec = 0;
737 }
738 /**
739 Log_event_header constructor.
740
741 @param reader the Event_reader containing the serialized event (including
742 header, event data and optional checksum information).
743 */
745
746 /**
747 The get_is_valid function is related to event specific sanity checks to
748 determine that the object was initialized without errors.
749
750 Note that a given event object may be valid at some point (ancestor
751 event type initialization was fine) but be turned invalid in a later
752 stage.
753
754 @return True if the event object is valid, false otherwise.
755 */
756
757 bool get_is_valid() { return m_is_valid; }
758
759 /**
760 Set if the event object shall be considered valid or not.
761
762 @param is_valid if the event object shall be considered valid.
763 */
764
766
767 /// @brief Accessor for decoding error
768 /// @return Error that occurred during decoding
770
771 /// @brief Sets specific decoding error
772 /// @param decoding_error Decoding error to be set
773 void set_decoding_error(const Event_decoding_error &decoding_error);
774
775 private:
776 /*
777 As errors might happen when de-serializing events, the m_is_valid variable
778 will hold information about the validity of the event.
779
780 An invalid event shall never be applied/dumped/displayed, as its
781 interpretation (accessing its contents) might lead to using invalid
782 memory pointers.
783 */
785
786 /// Holds information about specific decoding error
788};
789
790/**
791 This is the abstract base class for binary log events.
792
793 @section Binary_log_event_binary_format Binary Format
794
795 @anchor Binary_log_event_format
796 Any @c Binary_log_event saved on disk consists of the following four
797 components.
798
799 - Common-Header
800 - Post-Header
801 - Body
802 - Footer
803
804 Common header has the same format and length in a given MySQL version. It is
805 documented @ref Table_common_header "here".
806
807 The Body may be of different format and length even for different events of
808 the same type. The binary formats of Post-Header and Body are documented
809 separately in each subclass.
810
811 Footer is common to all the events in a given MySQL version. It is documented
812 @ref Table_common_footer "here".
813
814 @anchor packed_integer
815 - Some events, used for RBR use a special format for efficient representation
816 of unsigned integers, called Packed Integer. A Packed Integer has the
817 capacity of storing up to 8-byte integers, while small integers
818 still can use 1, 3, or 4 bytes. The value of the first byte
819 determines how to read the number, according to the following table:
820
821 <table>
822 <caption>Format of Packed Integer</caption>
823
824 <tr>
825 <th>First byte</th>
826 <th>Format</th>
827 </tr>
828
829 <tr>
830 <td>0-250</td>
831 <td>The first byte is the number (in the range 0-250), and no more
832 bytes are used.</td>
833 </tr>
834
835 <tr>
836 <td>252</td>
837 <td>Two more bytes are used. The number is in the range
838 251-0xffff.</td>
839 </tr>
840
841 <tr>
842 <td>253</td>
843 <td>Three more bytes are used. The number is in the range
844 0xffff-0xffffff.</td>
845 </tr>
846
847 <tr>
848 <td>254</td>
849 <td>Eight more bytes are used. The number is in the range
850 0xffffff-0xffffffffffffffff.</td>
851 </tr>
852
853 </table>
854
855 - Strings are stored in various formats. The format of each string
856 is documented separately.
857
858*/
860 public:
861 /*
862 The number of types we handle in Format_description_event (UNKNOWN_EVENT
863 is not to be handled, it does not exist in binlogs, it does not have a
864 format).
865 */
866 static const int LOG_EVENT_TYPES = (ENUM_END_EVENT - 1);
867
868 /**
869 The lengths for the fixed data part of each event.
870 This is an enum that provides post-header lengths for all events.
871 */
873 // where 3.23, 4.x and 5.0 agree
874 QUERY_HEADER_MINIMAL_LEN = (4 + 4 + 1 + 2),
875 // where 5.0 differs: 2 for length of N-bytes vars.
879 // this is FROZEN (the Rotate post-header is frozen)
902 }; // end enum_post_header_length
903 protected:
904 /**
905 This constructor is used to initialize the type_code of header object
906 m_header.
907 We set the type code to ENUM_END_EVENT so that the decoder
908 asserts if event type has not been modified by the sub classes
909 */
911 : m_reader(nullptr, 0), m_header(type_code) {}
912
913 /**
914 This constructor will create a new object of Log_event_header and initialize
915 the variable m_header, which in turn will be used to initialize Log_event's
916 member common_header.
917 It will also advance the Event_reader cursor after decoding the header (it
918 is done through the constructor of Log_event_header) and will be pointing to
919 the start of event data.
920
921 @param buf Contains the serialized event.
922 @param fde An FDE event used to get checksum information of non FDE events.
923 */
924 Binary_log_event(const char **buf, const Format_description_event *fde);
925
926 public:
927#ifndef HAVE_MYSYS
928 /*
929 The print_event_info functions are used in the free standing version of
930 the library only. Since MySQL server does not use them, and it does not
931 link to standard input/output library on Windows 32 bit system ,these
932 methods are commented out when the library(libbinlogevents) is built
933 with the server.
934 */
935 /**
936 Returns short information about the event
937 */
938 virtual void print_event_info(std::ostream &info) = 0;
939 /**
940 Returns detailed information about the event
941 */
942 virtual void print_long_info(std::ostream &info) = 0;
943#endif
944 virtual ~Binary_log_event() = 0;
945
950
951 /**
952 * Helper method
953 */
955
956 /**
957 Return a const pointer to the header of the log event
958 */
959 const Log_event_header *header() const { return &m_header; }
960 /**
961 Return a non-const pointer to the header of the log event
962 */
964 /**
965 Return a const pointer to the footer of the log event
966 */
967 const Log_event_footer *footer() const { return &m_footer; }
968 /**
969 Return a non-const pointer to the footer of the log event
970 */
972 /**
973 Returns a reference to the event Event_reader object.
974 */
976
977 private:
978 /*
979 All the accesses to the event buffer shall be performed by using m_reader
980 methods.
981 */
985};
986
987/**
988 @class Unknown_event
989
990 An unknown event should never occur. It is never written to a binary log.
991 If an event is read from a binary log that cannot be recognized as
992 something else, it is treated as UNKNOWN_EVENT.
993
994 The Post-Header and Body for this event type are empty; it only has
995 the Common-Header.
996*/
998 public:
999 /**
1000 This is the minimal constructor, and set the type_code as
1001 UNKNOWN_EVENT in the header object in Binary_log_event
1002 */
1004
1005 Unknown_event(const char *buf, const Format_description_event *fde);
1006#ifndef HAVE_MYSYS
1007 void print_event_info(std::ostream &info) override;
1008 void print_long_info(std::ostream &info) override;
1009#endif
1010};
1011} // end namespace mysql::binlog::event
1012
1013/// @}
1014
1015#endif // MYSQL_BINLOG_EVENT_BINLOG_EVENT_H
Kerberos Client Authentication nullptr
Definition: auth_kerberos_client_plugin.cc:251
#define ST_SERVER_VER_LEN
The length of the array server_version, which is used to store the version of MySQL server.
Definition: binlog_event.h:425
This is the abstract base class for binary log events.
Definition: binlog_event.h:859
enum_post_header_length
The lengths for the fixed data part of each event.
Definition: binlog_event.h:872
@ QUERY_HEADER_LEN
Definition: binlog_event.h:876
@ APPEND_BLOCK_HEADER_LEN
Definition: binlog_event.h:882
@ IGNORABLE_HEADER_LEN
Definition: binlog_event.h:896
@ TRANSACTION_CONTEXT_HEADER_LEN
Definition: binlog_event.h:898
@ STOP_HEADER_LEN
Definition: binlog_event.h:877
@ FORMAT_DESCRIPTION_HEADER_LEN
Definition: binlog_event.h:886
@ XID_HEADER_LEN
Definition: binlog_event.h:887
@ ROWS_HEADER_LEN_V1
Definition: binlog_event.h:889
@ BEGIN_LOAD_QUERY_HEADER_LEN
Definition: binlog_event.h:888
@ RAND_HEADER_LEN
Definition: binlog_event.h:884
@ QUERY_HEADER_MINIMAL_LEN
Definition: binlog_event.h:874
@ START_V3_HEADER_LEN
Definition: binlog_event.h:878
@ XA_PREPARE_HEADER_LEN
Definition: binlog_event.h:900
@ EXECUTE_LOAD_QUERY_EXTRA_HEADER_LEN
Definition: binlog_event.h:891
@ INCIDENT_HEADER_LEN
Definition: binlog_event.h:894
@ USER_VAR_HEADER_LEN
Definition: binlog_event.h:885
@ DELETE_FILE_HEADER_LEN
Definition: binlog_event.h:883
@ ROTATE_HEADER_LEN
Definition: binlog_event.h:880
@ EXECUTE_LOAD_QUERY_HEADER_LEN
Definition: binlog_event.h:892
@ TABLE_MAP_HEADER_LEN
Definition: binlog_event.h:890
@ ROWS_HEADER_LEN_V2
Definition: binlog_event.h:897
@ VIEW_CHANGE_HEADER_LEN
Definition: binlog_event.h:899
@ TRANSACTION_PAYLOAD_HEADER_LEN
Definition: binlog_event.h:901
@ HEARTBEAT_HEADER_LEN
Definition: binlog_event.h:895
@ INTVAR_HEADER_LEN
Definition: binlog_event.h:881
const Log_event_header * header() const
Return a const pointer to the header of the log event.
Definition: binlog_event.h:959
Event_reader & reader()
Returns a reference to the event Event_reader object.
Definition: binlog_event.h:975
Binary_log_event(Log_event_type type_code)
This constructor is used to initialize the type_code of header object m_header.
Definition: binlog_event.h:910
Log_event_footer * footer()
Return a non-const pointer to the footer of the log event.
Definition: binlog_event.h:971
Log_event_header m_header
Definition: binlog_event.h:983
Log_event_footer m_footer
Definition: binlog_event.h:984
Binary_log_event & operator=(Binary_log_event &&)=default
Binary_log_event(Binary_log_event &&)=default
static const int LOG_EVENT_TYPES
Definition: binlog_event.h:866
Binary_log_event(const Binary_log_event &)=default
Binary_log_event & operator=(const Binary_log_event &)=default
Event_reader m_reader
Definition: binlog_event.h:982
Log_event_header * header()
Return a non-const pointer to the header of the log event.
Definition: binlog_event.h:963
enum Log_event_type get_event_type() const
Helper method.
Definition: binlog_event.h:954
const Log_event_footer * footer() const
Return a const pointer to the footer of the log event.
Definition: binlog_event.h:967
Event_reader class purpose is to avoid out-of-buffer reads when deserializing binary log events and i...
Definition: event_reader.h:74
For binlog version 4.
Definition: control_events.h:239
The Common-Header always has the same form and length within one version of MySQL.
Definition: binlog_event.h:685
unsigned int unmasked_server_id
Definition: binlog_event.h:706
unsigned long long log_pos
Definition: binlog_event.h:716
unsigned char Byte
The following type definition is to be used whenever data is placed and manipulated in a common buffe...
Definition: binlog_event.h:731
Event_decoding_error m_decoding_error
Holds information about specific decoding error.
Definition: binlog_event.h:787
struct timeval when
Definition: binlog_event.h:695
Log_event_type type_code
Event type extracted from the header.
Definition: binlog_event.h:701
const Event_decoding_error & get_decoding_error() const
Accessor for decoding error.
Definition: binlog_event.cpp:290
void set_is_valid(bool is_valid)
Set if the event object shall be considered valid or not.
Definition: binlog_event.h:765
size_t data_written
Definition: binlog_event.h:709
uint16_t flags
Definition: binlog_event.h:724
void set_decoding_error(const Event_decoding_error &decoding_error)
Sets specific decoding error.
Definition: binlog_event.cpp:294
bool m_is_valid
Definition: binlog_event.h:784
bool get_is_valid()
The get_is_valid function is related to event specific sanity checks to determine that the object was...
Definition: binlog_event.h:757
Log_event_header(Log_event_type type_code_arg=ENUM_END_EVENT)
Definition: binlog_event.h:733
An unknown event should never occur.
Definition: binlog_event.h:997
Unknown_event()
This is the minimal constructor, and set the type_code as UNKNOWN_EVENT in the header object in Binar...
Definition: binlog_event.h:1003
const char * p
Definition: ctype-mb.cc:1225
This header file contains the status of variables used by MySQL tests for debug operations.
Contains the class responsible for deserializing fields of an event previously stored in a buffer.
const unsigned char checksum_version_split[3]
Replication event checksum is introduced in the following "checksum-home" version.
Definition: binlog_event.cpp:31
void do_server_version_split(const char *version, unsigned char split_versions[3])
In case the variable is updated, make sure to update it in $MYSQL_SOURCE_DIR/my_io....
Definition: binlog_event.h:192
const int64_t UNDEFINED_COMMIT_TIMESTAMP
Used to determine whether the original_commit_timestamp is already known or if it still needs to be d...
Definition: binlog_event.h:166
const int64_t SEQ_UNINIT
Uninitialized timestamp value (for either last committed or sequence number).
Definition: binlog_event.h:158
unsigned long version_product(const unsigned char *version_split)
Calculate the version product from the numeric pieces representing the server version: For a server v...
Definition: binlog_event.h:242
const uint32_t UNKNOWN_SERVER_VERSION
Definition: binlog_event.h:169
uint32_t do_server_version_int(const char *version)
Transforms the server version from 'XX.YY.ZZ-suffix' into an integer in the format XXYYZZ.
Definition: binlog_event.h:224
const unsigned long checksum_version_product
Definition: binlog_event.cpp:32
#define MAX_COMMIT_TIMESTAMP_VALUE
We use 7 bytes, 1 bit being used as a flag.
Definition: binlog_event.h:161
const uint32_t UNDEFINED_SERVER_VERSION
Definition: binlog_event.h:168
Abstraction functions over zlib/intrinsics.
ha_checksum my_checksum(ha_checksum crc, const unsigned char *pos, size_t length)
Calculate a CRC32 checksum for a memoryblock.
Definition: my_checksum.h:117
Common #defines and includes for file and socket I/O.
Definition: buf0block_hint.cc:30
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:76
bool is_valid(const dd::Spatial_reference_system *srs, const Geometry *g, const char *func_name, bool *is_valid) noexcept
Decides if a geometry is valid.
Definition: is_valid.cc:95
The namespace contains classes representing events that can occur in a replication stream.
Definition: binlog_event.cpp:36
constexpr size_t max_log_event_size
The maximum value for MAX_ALLOWED_PACKET.
Definition: binlog_event.h:448
uint32_t checksum_crc32(uint32_t crc, const unsigned char *pos, size_t length)
Calculate a long checksum for a memoryblock.
Definition: binlog_event.h:497
Log_event_type
Enumeration type for the different types of log events.
Definition: binlog_event.h:286
@ OBSOLETE_UPDATE_ROWS_EVENT_V1
Definition: binlog_event.h:324
@ HEARTBEAT_LOG_EVENT
Heartbeat event to be send by master at its idle time to ensure master's online status to slave.
Definition: binlog_event.h:336
@ HEARTBEAT_LOG_EVENT_V2
Definition: binlog_event.h:372
@ INCIDENT_EVENT
Something out of the ordinary happened on the master.
Definition: binlog_event.h:330
@ FORMAT_DESCRIPTION_EVENT
Definition: binlog_event.h:312
@ BEGIN_LOAD_QUERY_EVENT
Definition: binlog_event.h:314
@ EXECUTE_LOAD_QUERY_EVENT
Definition: binlog_event.h:315
@ OBSOLETE_WRITE_ROWS_EVENT_V1
Definition: binlog_event.h:323
@ XID_EVENT
Definition: binlog_event.h:313
@ ROWS_QUERY_LOG_EVENT
Definition: binlog_event.h:345
@ WRITE_ROWS_EVENT
Version 2 of the Row events.
Definition: binlog_event.h:348
@ DELETE_ROWS_EVENT
Definition: binlog_event.h:350
@ IGNORABLE_LOG_EVENT
In some situations, it is necessary to send over ignorable data to the slave: data that a slave can h...
Definition: binlog_event.h:344
@ XA_PREPARE_LOG_EVENT
Definition: binlog_event.h:362
@ QUERY_EVENT
Definition: binlog_event.h:300
@ VIEW_CHANGE_EVENT
Definition: binlog_event.h:359
@ START_EVENT_V3
Definition: binlog_event.h:299
@ UNKNOWN_EVENT
Every time you add a type, you have to.
Definition: binlog_event.h:294
@ PREVIOUS_GTIDS_LOG_EVENT
Definition: binlog_event.h:355
@ UPDATE_ROWS_EVENT
Definition: binlog_event.h:349
@ RAND_EVENT
Definition: binlog_event.h:310
@ TABLE_MAP_EVENT
Definition: binlog_event.h:317
@ DELETE_FILE_EVENT
Definition: binlog_event.h:308
@ STOP_EVENT
Definition: binlog_event.h:301
@ OBSOLETE_DELETE_ROWS_EVENT_V1
Definition: binlog_event.h:325
@ PARTIAL_UPDATE_ROWS_EVENT
Extension of UPDATE_ROWS_EVENT, allowing partial values according to binlog_row_value_options.
Definition: binlog_event.h:368
@ GTID_LOG_EVENT
Definition: binlog_event.h:352
@ ANONYMOUS_GTID_LOG_EVENT
Definition: binlog_event.h:353
@ TRANSACTION_PAYLOAD_EVENT
Definition: binlog_event.h:370
@ APPEND_BLOCK_EVENT
Definition: binlog_event.h:307
@ INTVAR_EVENT
Definition: binlog_event.h:303
@ USER_VAR_EVENT
Definition: binlog_event.h:311
@ GTID_TAGGED_LOG_EVENT
Definition: binlog_event.h:374
@ ROTATE_EVENT
Definition: binlog_event.h:302
@ SLAVE_EVENT
Definition: binlog_event.h:305
@ ENUM_END_EVENT
Add new events here - right above this comment! Existing events (except ENUM_END_EVENT) should never ...
Definition: binlog_event.h:379
@ TRANSACTION_CONTEXT_EVENT
Definition: binlog_event.h:357
const std::string & get_event_type_as_string(Log_event_type type)
Get the event type as string object.
Definition: binlog_event.cpp:80
enum_binlog_checksum_alg
Enumeration spcifying checksum algorithm used to encode a binary log event.
Definition: binlog_event.h:462
@ BINLOG_CHECKSUM_ALG_OFF
Events are without checksum though its generator is checksum-capable New Master (NM).
Definition: binlog_event.h:467
@ BINLOG_CHECKSUM_ALG_ENUM_END
the cut line: valid alg range is [1, 0x7f]
Definition: binlog_event.h:471
@ BINLOG_CHECKSUM_ALG_UNDEF
Special value to tag undetermined yet checksum or events from checksum-unaware servers.
Definition: binlog_event.h:476
@ BINLOG_CHECKSUM_ALG_CRC32
CRC32 of zlib algorithm.
Definition: binlog_event.h:469
Event_decoding_error
Errors that we distinguish during event decoding, that are translated to specific error returned by t...
Definition: event_decoding_error.h:34
const mysql_service_registry_t * r
Definition: pfs_example_plugin_employee.cc:86
required uint64 version
Definition: replication_group_member_actions.proto:41
required string type
Definition: replication_group_member_actions.proto:34
Struct to pass basic information about a event: type, query, is it ignorable.
Definition: binlog_event.h:407
Log_event_type event_type
Definition: binlog_event.h:408
const char * query
Definition: binlog_event.h:409
size_t query_length
Definition: binlog_event.h:410
bool ignorable_event
Definition: binlog_event.h:411
Event type helpers, enclosed in the structure.
Definition: binlog_event.h:391
static bool is_any_gtid_event(const Log_event_type &type)
Helps to identify any GTID event - returns true for GTID_LOG_EVENT, GTID_TAGGED_LOG_EVENT and ANONYMO...
Definition: binlog_event.h:399
static bool is_assigned_gtid_event(const Log_event_type &type)
Helps to identify known GTID event - returns true for GTID_LOG_EVENT and GTID_TAGGED_LOG_EVENT.
Definition: binlog_event.h:394
#define BAPI_ASSERT(x)
Definition: wrapper_functions.h:61