MySQL 8.4.3
Source Code Documentation
recovery.h
Go to the documentation of this file.
1/* Copyright (c) 2022, 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#ifndef BINLOG_RECOVERY_H_INCLUDED
25#define BINLOG_RECOVERY_H_INCLUDED
26
27#include "sql/binlog/global.h"
29#include "sql/binlog_ostream.h" // binlog::tools::Iterator
30#include "sql/binlog_reader.h" // Binlog_file_reader
31#include "sql/log_event.h" // Log_event
32#include "sql/xa.h" // XID
33
34namespace binlog {
35/**
36 Recovers from last crashed binlog at server start.
37
38 After a crash, storage engines may contain transactions that are prepared
39 but not committed (in theory any engine, in practice InnoDB). This
40 classe's methods use the binary log as the source of truth to determine
41 which of these transactions should be committed and which should be
42 rolled back.
43
44 The `Binlog::recovery()` method collects the following from the last
45 available binary log:
46 - the list of internally coordinated transactions (normal) that are
47 completely written to the binary log.
48 - the list of externally coordinated transactions (XA) that appear in the
49 binary log, along the state those transactions are in.
50
51 The list of XIDs of all internally coordinated transactions that are
52 completely written to the binary log is passed to the storage engines
53 through the ha_recover function in the handler interface. This tells the
54 storage engines to commit all prepared transactions that are in the set,
55 and to roll back all prepared transactions that are not in the set.
56
57 The list of XIDs of all externally coordinated transactions that appear
58 in the binary log, along with the state they are in, is passed to the
59 storage engines through the ha_recover function in the handler
60 interface. The storage engine will determine if the transaction is to be
61 kept at PREPARE, is to be COMMITTED or ROLLED BACK, in accordance with:
62 the state that is provided in the list; the internal storage engine state
63 for the transaction.
64*/
66 public:
67 /**
68 Class constructor.
69
70 @param binlog_file_reader The already instantiated and initialized file
71 reader for the last available binary log
72 file.
73 */
74 Binlog_recovery(Binlog_file_reader &binlog_file_reader);
75 ~Binlog_recovery() override = default;
76
77 /**
78 Retrieves whether or not the recovery process ended successfully.
79
80 @see Binlog_recovery::is_binlog_malformed()
81 @see Binlog_recovery::has_engine_recovery_failed()
82
83 @return true if the recovery process ended with errors, false
84 otherwise.
85 */
86 bool has_failures() const;
87 /**
88 Retrieves whether or not the binary log was correctly processed in
89 full.
90
91 @return true if the binary log processing ended with errors, false
92 otherwise.
93 */
94 bool is_binlog_malformed() const;
95 /**
96 Retrieves whether or not the storage engines XA recovery process
97 completed successfully.
98
99 @return false if the storge engines completed the XA recovery process
100 successfully, true otherwise.
101 */
102 bool has_engine_recovery_failed() const;
103 /**
104 Retrieves the textual representation of the encontered failure, if any.
105
106 @return the string containing the textual representation of the failure,
107 an empty string otherwise.
108 */
109 std::string const &get_failure_message() const;
110 /**
111 Uses the provided binary log file reader to inspect the binary log and
112 extract transaction information.
113
114 The following is collected from the provided binlog file reader:
115 - the list of internally coordinated transactions (normal) that are
116 completely written to the binary log.
117 - the list of externally coordinated transactions (XA) that appear in
118 the binary log, along the state those transactions are in.
119
120 The list of XIDs of all internally coordinated transactions that are
121 completely written to the binary log is passed to the storage engines
122 through the ha_recover function in the handler interface. This tells the
123 storage engines to commit all prepared transactions that are in the set,
124 and to roll back all prepared transactions that are not in the set.
125
126 The list of XIDs of all externally coordinated transactions that appear
127 in the binary log, along with the state they are in, is passed to the
128 storage engines through the ha_recover function in the handler
129 interface. The storage engine will determine if the transaction is to be
130 kept at PREPARE, is to be COMMITTED or ROLLED BACK, in accordance with:
131 the state that is provided in the list; the internal storage engine state
132 for the transaction.
133
134 After `recover()` returns, `has_failures()` should be invoked to
135 determine if the recover process ended successfully. Additionally,
136 `is_binlog_malformed()` and `has_engine_recovery_failed()` can be
137 invoked to determine the type of error that occurred.
138
139 @return This instance's reference, for chaining purposes.
140 */
142
143 protected:
144 /// @brief Function used to obtain memory key for derived classes
145 /// @returns Reference to a memory key
146 PSI_memory_key &get_memory_key() const override {
147 return key_memory_recovery;
148 }
149
150 private:
151 /** File reader for the last available binary log file */
153 /** Whether or not the recovery in the storage engines failed */
155};
156} // namespace binlog
157
158#endif // BINLOG_RECOVERY_H_INCLUDED
It owns an allocator, a byte stream, an event_data stream and an event object stream.
Definition: binlog_reader.h:295
Recovers from last crashed binlog at server start.
Definition: recovery.h:65
~Binlog_recovery() override=default
bool m_no_engine_recovery
Whether or not the recovery in the storage engines failed.
Definition: recovery.h:154
Binlog_file_reader & m_reader
File reader for the last available binary log file.
Definition: recovery.h:152
Binlog_recovery(Binlog_file_reader &binlog_file_reader)
Class constructor.
Definition: recovery.cc:32
bool has_failures() const
Retrieves whether or not the recovery process ended successfully.
Definition: recovery.cc:37
Binlog_recovery & recover()
Uses the provided binary log file reader to inspect the binary log and extract transaction informatio...
Definition: recovery.cc:53
std::string const & get_failure_message() const
Retrieves the textual representation of the encontered failure, if any.
Definition: recovery.cc:49
bool is_binlog_malformed() const
Retrieves whether or not the binary log was correctly processed in full.
Definition: recovery.cc:41
PSI_memory_key & get_memory_key() const override
Function used to obtain memory key for derived classes.
Definition: recovery.h:146
bool has_engine_recovery_failed() const
Retrieves whether or not the storage engines XA recovery process completed successfully.
Definition: recovery.cc:45
Class used to recover binary / relay log file.
Definition: log_sanitizer.h:62
unsigned int PSI_memory_key
Instrumented memory key.
Definition: psi_memory_bits.h:49
Binary log event definitions.
Definition: pfs.cc:38
PSI_memory_key key_memory_recovery
Definition: psi_memory_key.cc:78