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