MySQL 8.3.0
Source Code Documentation
clone0api.h
Go to the documentation of this file.
1/*****************************************************************************
2
3Copyright (c) 2017, 2023, Oracle and/or its affiliates.
4
5This program is free software; you can redistribute it and/or modify it under
6the terms of the GNU General Public License, version 2.0, as published by the
7Free Software Foundation.
8
9This program is also distributed with certain software (including but not
10limited to OpenSSL) that is licensed under separate terms, as designated in a
11particular file or component or in included license documentation. The authors
12of MySQL hereby grant you an additional permission to link the program and
13your derivative works with the separately licensed software that they have
14included with MySQL.
15
16This program is distributed in the hope that it will be useful, but WITHOUT
17ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
19for more details.
20
21You should have received a copy of the GNU General Public License along with
22this program; if not, write to the Free Software Foundation, Inc.,
2351 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24
25*****************************************************************************/
26
27/** @file include/clone0api.h
28 Innodb Clone Interface
29
30 *******************************************************/
31
32#ifndef CLONE_API_INCLUDE
33#define CLONE_API_INCLUDE
34
35#include "univ.i"
36#ifndef UNIV_HOTBACKUP
37#include "sql/handler.h"
38
39/** Get capability flags for clone operation
40@param[out] flags capability flag */
42
43/** Begin copy from source database
44@param[in] hton handlerton for SE
45@param[in] thd server thread handle
46@param[in,out] loc locator
47@param[in,out] loc_len locator length
48@param[out] task_id task identifier
49@param[in] type clone type
50@param[in] mode mode for starting clone
51@return error code */
52int innodb_clone_begin(handlerton *hton, THD *thd, const byte *&loc,
53 uint &loc_len, uint &task_id, Ha_clone_type type,
55
56/** Copy data from source database in chunks via callback
57@param[in] hton handlerton for SE
58@param[in] thd server thread handle
59@param[in] loc locator
60@param[in] loc_len locator length in bytes
61@param[in] task_id task identifier
62@param[in] cbk callback interface for sending data
63@return error code */
64int innodb_clone_copy(handlerton *hton, THD *thd, const byte *loc, uint loc_len,
65 uint task_id, Ha_clone_cbk *cbk);
66
67/** Acknowledge data to source database
68@param[in] hton handlerton for SE
69@param[in] thd server thread handle
70@param[in] loc locator
71@param[in] loc_len locator length in bytes
72@param[in] task_id task identifier
73@param[in] in_err inform any error occurred
74@param[in] cbk callback interface for receiving data
75@return error code */
76int innodb_clone_ack(handlerton *hton, THD *thd, const byte *loc, uint loc_len,
77 uint task_id, int in_err, Ha_clone_cbk *cbk);
78
79/** End copy from source database
80@param[in] hton handlerton for SE
81@param[in] thd server thread handle
82@param[in] loc locator
83@param[in] loc_len locator length in bytes
84@param[in] task_id task identifier
85@param[in] in_err error code when ending after error
86@return error code */
87int innodb_clone_end(handlerton *hton, THD *thd, const byte *loc, uint loc_len,
88 uint task_id, int in_err);
89
90/** Begin apply to destination database
91@param[in] hton handlerton for SE
92@param[in] thd server thread handle
93@param[in,out] loc locator
94@param[in,out] loc_len locator length
95@param[out] task_id task identifier
96@param[in] mode mode for starting clone
97@param[in] data_dir target data directory
98@return error code */
99int innodb_clone_apply_begin(handlerton *hton, THD *thd, const byte *&loc,
100 uint &loc_len, uint &task_id, Ha_clone_mode mode,
101 const char *data_dir);
102
103/** Apply data to destination database in chunks via callback
104@param[in] hton handlerton for SE
105@param[in] thd server thread handle
106@param[in] loc locator
107@param[in] loc_len locator length in bytes
108@param[in] task_id task identifier
109@param[in] in_err inform any error occurred
110@param[in] cbk callback interface for receiving data
111@return error code */
112int innodb_clone_apply(handlerton *hton, THD *thd, const byte *loc,
113 uint loc_len, uint task_id, int in_err,
114 Ha_clone_cbk *cbk);
115
116/** End apply to destination database
117@param[in] hton handlerton for SE
118@param[in] thd server thread handle
119@param[in] loc locator
120@param[in] loc_len locator length in bytes
121@param[in] task_id task identifier
122@param[in] in_err error code when ending after error
123@return error code */
124int innodb_clone_apply_end(handlerton *hton, THD *thd, const byte *loc,
125 uint loc_len, uint task_id, int in_err);
126
127/** Check and delete any old list files. */
129
130/** Add file name to clone list file for future replacement or rollback.
131@param[in] list_file_name list file name where to add the file
132@param[in] file_name file name to add to the list
133@return error code */
134int clone_add_to_list_file(const char *list_file_name, const char *file_name);
135
136/** Remove one of the clone list files.
137@param[in] file_name list file name to delete */
138void clone_remove_list_file(const char *file_name);
139
140/** Revert back clone changes in case of an error. */
141void clone_files_error();
142
143#ifdef UNIV_DEBUG
144/** Debug function to check and crash during recovery.
145@param[in] is_cloned_db if cloned database recovery */
146bool clone_check_recovery_crashpoint(bool is_cloned_db);
147#endif
148
149/** Change cloned file states during recovery.
150@param[in] finished if recovery is finishing */
152
153/** Update cloned GTIDs to recovery status file.
154@param[in] gtids cloned GTIDs */
155void clone_update_gtid_status(std::string &gtids);
156
157/** Initialize Clone system
158@return inndodb error code */
160
161/** Uninitialize Clone system */
162void clone_free();
163
164/** Check if active clone is running.
165@return true, if any active clone is found. */
166bool clone_check_active();
167
168/** @return true, if clone provisioning in progress. */
170#endif /* !UNIV_HOTBACKUP */
171
172/** Fix cloned non-Innodb tables during recovery.
173@param[in,out] thd current THD
174@return true if error */
175bool fix_cloned_tables(THD *thd);
176
177/** Clone Notification handler. */
179 public:
180 /** Notification type. Currently used by various DDL commands. */
181 enum class Type {
182 /* Space is being created. */
184 /* Space is being dropped. */
186 /* Space is being renamed. */
188 /* Space is being discarded or imported. */
190 /* Space encryption property is altered. */
192 /* Space encryption property of general tablespace is altered. */
194 /* Space encryption flags of general tablespace are altered. */
196 /* In place Alter general notification. */
198 /* Inplace Alter bulk operation. */
200 /* Special consideration is needed for UNDO as these DDLs
201 don't use DDL log and needs special consideration during recovery. */
203 /* Redo logging is being disabled. */
205 };
206
207#ifdef UNIV_HOTBACKUP
208 Clone_notify(Type, space_id_t, bool) : m_error() {}
209 ~Clone_notify() {}
210#else
211 /** Constructor to initiate notification.
212 @param[in] type notification type
213 @param[in] space tablespace ID for which notification is sent
214 @param[in] no_wait set error and return immediately if needs to wait */
215 Clone_notify(Type type, space_id_t space, bool no_wait);
216
217 /** Destructor to automatically end notification. */
219#endif /* UNIV_HOTBACKUP */
220
221 /** Get notification message for printing.
222 @param[in] begin true if notification begin otherwise end
223 @param[out] mesg notification message */
224 void get_mesg(bool begin, std::string &mesg);
225
226 /** @return true iff notification failed. */
227 bool failed() const { return m_error != 0; }
228
229 /** @return saved error code. */
230 int get_error() const { return m_error; }
231
232 /** Disable copy construction */
234
235 /** Disable assignment */
237
238 private:
239 /** Notification wait type set. */
240 enum class Wait_at {
241 /* Clone doesn't need to wait. */
242 NONE,
243 /* Clone needs to wait before entering. */
244 ENTER,
245 /* Clone needs to wait before state change. */
247 /* Clone needs to abort. */
248 ABORT
249 };
250
251 private:
252 /** Tablespace ID for which notification is sent. */
254
255 /** Notification type. */
257
258 /** Wait type set. */
260
261 /** Blocked clone state if clone is blocked. */
263
264 /** Saved error. */
266};
267
268#endif /* CLONE_API_INCLUDE */
uint32_t space_id_t
Tablespace identifier.
Definition: api0api.h:46
Clone Notification handler.
Definition: clone0api.h:178
Clone_notify(Type type, space_id_t space, bool no_wait)
Constructor to initiate notification.
Definition: clone0api.cc:2491
space_id_t m_space_id
Tablespace ID for which notification is sent.
Definition: clone0api.h:253
void get_mesg(bool begin, std::string &mesg)
Get notification message for printing.
Definition: clone0api.cc:2624
Type m_type
Notification type.
Definition: clone0api.h:256
uint32_t m_blocked_state
Blocked clone state if clone is blocked.
Definition: clone0api.h:262
Type
Notification type.
Definition: clone0api.h:181
int get_error() const
Definition: clone0api.h:230
~Clone_notify()
Destructor to automatically end notification.
Definition: clone0api.cc:2594
Clone_notify & operator=(Clone_notify const &)=delete
Disable assignment.
Wait_at
Notification wait type set.
Definition: clone0api.h:240
int m_error
Saved error.
Definition: clone0api.h:265
Wait_at m_wait
Wait type set.
Definition: clone0api.h:259
bool failed() const
Definition: clone0api.h:227
Clone_notify(Clone_notify &)=delete
Disable copy construction.
Definition: handler.h:1018
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:35
void clone_remove_list_file(const char *file_name)
Remove one of the clone list files.
Definition: clone0api.cc:230
int clone_add_to_list_file(const char *list_file_name, const char *file_name)
Add file name to clone list file for future replacement or rollback.
Definition: clone0api.cc:235
int innodb_clone_apply_end(handlerton *hton, THD *thd, const byte *loc, uint loc_len, uint task_id, int in_err)
End apply to destination database.
Definition: clone0api.cc:980
bool clone_check_active()
Check if active clone is running.
Definition: clone0api.cc:1663
bool clone_check_recovery_crashpoint(bool is_cloned_db)
Debug function to check and crash during recovery.
Definition: clone0api.cc:1531
void clone_init_list_files()
Check and delete any old list files.
Definition: clone0api.cc:212
void clone_files_recovery(bool finished)
Change cloned file states during recovery.
Definition: clone0api.cc:1545
void clone_update_gtid_status(std::string &gtids)
Update cloned GTIDs to recovery status file.
Definition: clone0api.cc:1422
int innodb_clone_apply_begin(handlerton *hton, THD *thd, const byte *&loc, uint &loc_len, uint &task_id, Ha_clone_mode mode, const char *data_dir)
Begin apply to destination database.
Definition: clone0api.cc:782
int innodb_clone_end(handlerton *hton, THD *thd, const byte *loc, uint loc_len, uint task_id, int in_err)
End copy from source database.
Definition: clone0api.cc:635
int innodb_clone_copy(handlerton *hton, THD *thd, const byte *loc, uint loc_len, uint task_id, Ha_clone_cbk *cbk)
Copy data from source database in chunks via callback.
Definition: clone0api.cc:548
void clone_free()
Uninitialize Clone system.
Definition: clone0api.cc:1649
int innodb_clone_begin(handlerton *hton, THD *thd, const byte *&loc, uint &loc_len, uint &task_id, Ha_clone_type type, Ha_clone_mode mode)
Begin copy from source database.
Definition: clone0api.cc:394
int innodb_clone_apply(handlerton *hton, THD *thd, const byte *loc, uint loc_len, uint task_id, int in_err, Ha_clone_cbk *cbk)
Apply data to destination database in chunks via callback.
Definition: clone0api.cc:948
void innodb_clone_get_capability(Ha_clone_flagset &flags)
Get capability flags for clone operation.
Definition: clone0api.cc:310
void clone_files_error()
Revert back clone changes in case of an error.
Definition: clone0api.cc:1495
bool fix_cloned_tables(THD *thd)
Fix cloned non-Innodb tables during recovery.
Definition: clone0api.cc:2239
bool clone_check_provisioning()
Definition: clone0api.cc:1661
dberr_t clone_init()
Initialize Clone system.
Definition: clone0api.cc:1629
int innodb_clone_ack(handlerton *hton, THD *thd, const byte *loc, uint loc_len, uint task_id, int in_err, Ha_clone_cbk *cbk)
Acknowledge data to source database.
Definition: clone0api.cc:567
dberr_t
Definition: db0err.h:38
static int flags[50]
Definition: hp_test1.cc:39
void * begin(THD *thd, const TABLE *table, size_t data_size, size_t memory, size_t num_threads) noexcept
Definition: bulk_data_service.cc:1533
std::string file_name(Log_file_id file_id)
Provides name of the log file with the given file id, e.g.
Definition: log0pre_8_0_30.cc:93
mode
Definition: file_handle.h:59
required string type
Definition: replication_group_member_actions.proto:33
Ha_clone_mode
Clone start operation mode.
Definition: handler.h:948
std::bitset< HA_CLONE_TYPE_MAX > Ha_clone_flagset
Definition: handler.h:990
Ha_clone_type
Clone operation types.
Definition: handler.h:966
handlerton is a singleton structure - one instance per storage engine - to provide access to storage ...
Definition: handler.h:2718
Version control for database, common definitions, and include files.
static int finished(pax_machine *p)
Definition: xcom_base.cc:731