MySQL  8.0.22
Source Code Documentation
rpl_channel_service_interface.h
Go to the documentation of this file.
1 /* Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
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 also distributed 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 included with MySQL.
13 
14  This program is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License, version 2.0, for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with this program; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef RPL_SERVICE_INTERFACE_INCLUDE
24 #define RPL_SERVICE_INTERFACE_INCLUDE
25 
26 #include <string>
27 
28 // Channel errors
29 
30 #define RPL_CHANNEL_SERVICE_RECEIVER_CONNECTION_ERROR -1
31 #define RPL_CHANNEL_SERVICE_DEFAULT_CHANNEL_CREATION_ERROR -2
32 #define RPL_CHANNEL_SERVICE_SLAVE_SKIP_COUNTER_ACTIVE -3
33 #define RPL_CHANNEL_SERVICE_CHANNEL_DOES_NOT_EXISTS_ERROR -4
34 // Error for the wait event consumption, equal to the server wait for GTID
35 // method
36 #define REPLICATION_THREAD_WAIT_TIMEOUT_ERROR -1
37 #define REPLICATION_THREAD_WAIT_NO_INFO_ERROR -2
38 
39 // Settings
40 
41 // Used whenever a parameter should take the server default value
42 #define RPL_SERVICE_SERVER_DEFAULT -1
43 
44 // Channel creation settings
45 
46 /**
47  Types of channels
48 */
50  SLAVE_REPLICATION_CHANNEL, // Master slave replication channels
51  GROUP_REPLICATION_CHANNEL // Group replication channels
52 };
53 
54 /**
55  Know parallelization options that can be applied to channel appliers
56 */
60 };
61 
62 /**
63  SSL information to be used when creating a channel.
64  It maps the SSL options present in a CHANGE MASTER.
65 */
67  int use_ssl; // use SSL
68  char *ssl_ca_file_name; // SSL list of trusted certificate authorities
69  char *ssl_ca_directory; // SSL certificate authorities directory
70  char *ssl_cert_file_name; // SSL connection certificate
71  char *ssl_crl_file_name; // SSL certificate revocation list
72  char *ssl_crl_directory; // SSL certificate revocation list file directory
73  char *ssl_key; // SSL key file for connections
74  char *ssl_cipher; // list of permissible ciphers to use for SSL
75  int ssl_verify_server_cert; // check the server's Common Name value
76  char *tls_version; // TLS version to use for SSL
77  char *tls_ciphersuites; // list of permissible ciphersuites for TLS 1.3
78 };
79 
80 void initialize_channel_ssl_info(Channel_ssl_info *channel_ssl_info);
81 
82 /**
83  Creation information for a channel.
84  It includes the data that is usually associated to a change master command
85 */
88  char *hostname;
89  int port;
90  char *user;
91  char *password;
98  int thd_tx_priority; // The applier thread priority
99  int sql_delay;
100  int connect_retry; // How many seconds to wait between retries.
101  int retry_count; // Limits the number of reconnection attempts
102  bool preserve_relay_logs; // If the logs should be preserved on creation
103  char *public_key_path; // RSA Public key information
104  int get_public_key; // Preference to get public key from donor if not
105  // available
108  /* to enable async connection failover */
109  int m_source_connection_auto_failover{0};
110 };
111 
113 
114 // Start settings
115 
116 /**
117  The known types of channel threads.
118  All new types should be power of 2
119 */
124 };
125 
126 /**
127  The known until conditions that can be applied to channels
128 */
135 };
136 
137 /**
138  Channel information to connect to a receiver
139 */
141  int until_condition; // base on enum_channel_until_condition
142  char *gtid; // Gtids to wait on a until condition
143  char *view_id; // The view id to wait on a until condition
144 };
145 
147 
148 /**
149  Initializes a channel connection in a similar way to a change master command.
150 
151  @note If the channel exists, it is reconfigured with the new options.
152  About the logs, the preserve_relay_logs option allows the user to
153  maintain them untouched.
154 
155  @param channel The channel name
156  @param channel_information Channel creation information.
157 
158  @return the operation status
159  @retval 0 OK
160  @retval !=0 Error on channel creation
161 */
162 int channel_create(const char *channel,
163  Channel_creation_info *channel_information);
164 
165 /**
166  Start the Applier/Receiver threads according to the given options.
167  If the receiver thread is to be started, connection credential must be
168  supported.
169 
170  @param channel The channel name
171  @param connection_info Channel connection information
172  @param threads_to_start The types of threads to be started
173  @param wait_for_connection If when starting the receiver, the method should
174  wait for the connection to succeed
175 
176  @return the operation status
177  @retval 0 OK
178  @retval !=0 Error
179  */
180 int channel_start(const char *channel, Channel_connection_info *connection_info,
181  int threads_to_start, int wait_for_connection);
182 
183 /**
184  Stops the channel threads according to the given options.
185 
186  @param channel The channel name
187  @param threads_to_stop The types of threads to be stopped
188  @param timeout The expected time in which the thread should stop
189  @return the operation status
190  @retval 0 OK
191  @retval !=0 Error
192 */
193 int channel_stop(const char *channel, int threads_to_stop, long timeout);
194 
195 /**
196  Kills the Binlog Dump threads.
197 
198  @return the operation status
199  @retval 0 OK
200 */
202 
203 /**
204  Stops all the running channel threads according to the given options.
205 
206  @param threads_to_stop The types of threads to be stopped
207  @param timeout The expected time in which the thread should stop
208  @param error_message The returned error_message
209 
210  @return the operation status
211  @retval 0 OK
212  @retval !=0 Error
213 */
214 int channel_stop_all(int threads_to_stop, long timeout,
215  std::string *error_message);
216 /**
217  Purges the channel logs
218 
219  @param channel The channel name
220  @param reset_all If true, the method will purge logs and remove the channel
221  If false, only the channel information will be reset.
222 
223  @return the operation status
224  @retval 0 OK
225  @retval !=0 Error
226 */
227 int channel_purge_queue(const char *channel, bool reset_all);
228 
229 /**
230  Tells if the selected component of the channel is active or not.
231  If no component is passed, this method returns if the channel exists or not
232 
233  @param channel The channel name
234  @param type The thread that should be checked.
235  If 0, this method applies to the channel existence.
236 
237  @return is the channel (component) active
238  @retval true Yes
239  @retval false No
240 */
242 
243 /**
244  Returns the id(s) of the channel threads: receiver or applier.
245  If more than one applier exists, an array is returned, on which first
246  index is coordinator thread id.
247 
248  @param[in] channel The channel name
249  @param[in] thread_type The thread type (receiver or applier)
250  @param[out] thread_id The array of id(s)
251 
252  @return the number of returned ids
253  @retval -1 the channel does no exists, or the thread is not present
254  @retval >0 the number of thread ids returned.
255 */
256 int channel_get_thread_id(const char *channel,
258  unsigned long **thread_id);
259 
260 /**
261  Returns last GNO from applier from a given UUID.
262 
263  @param channel the channel name
264  @param sidno the uuid associated to the desired gno
265 
266  @return the last applier gno
267  @retval <0 the channel does no exists, or the applier is not present
268  @retval >0 the gno
269 */
270 long long channel_get_last_delivered_gno(const char *channel, int sidno);
271 
272 /**
273  Adds server executed GTID set to channel received GTID set.
274 
275  @param channel the channel name
276 
277  @return the operation status
278  @retval 0 OK
279  @retval != 0 Error
280 */
282 
283 /**
284  Queues a event packet into the current active channel.
285 
286  @param channel the channel name
287  @param buf the event buffer
288  @param len the event buffer length
289 
290  @return the operation status
291  @retval 0 OK
292  @retval != 0 Error on queue
293 */
294 int channel_queue_packet(const char *channel, const char *buf,
295  unsigned long len);
296 
297 /**
298  Checks if all the queued transactions were executed.
299 
300  @note This method assumes that the channel is not receiving any more events.
301  If it is still receiving, then the method should wait for execution of
302  transactions that were present when this method was invoked.
303 
304  @param channel the channel name
305  @param timeout the time (seconds) after which the method returns if the
306  above condition was not satisfied
307 
308  @return the operation status
309  @retval 0 All transactions were executed
310  @retval REPLICATION_THREAD_WAIT_TIMEOUT_ERROR A timeout occurred
311  @retval REPLICATION_THREAD_WAIT_NO_INFO_ERROR An error occurred
312 */
313 int channel_wait_until_apply_queue_applied(const char *channel, double timeout);
314 
315 /**
316  Checks if all the transactions in the given set were executed.
317 
318  @param channel the channel name
319  @param gtid_set the set in string format of transaction to wait for
320  @param timeout the time (seconds) after which the method returns if the
321  above condition was not satisfied
322  @param update_THD_status Shall the method update the THD stage
323 
324  @return the operation status
325  @retval 0 All transactions were executed
326  @retval REPLICATION_THREAD_WAIT_TIMEOUT_ERROR A timeout occurred
327  @retval REPLICATION_THREAD_WAIT_NO_INFO_ERROR An error occurred
328 */
330  const char *gtid_set,
331  double timeout,
332  bool update_THD_status = true);
333 
334 /**
335  Checks if the applier, and its workers when parallel applier is
336  enabled, has already consumed all relay log, that is, applier is
337  waiting for transactions to be queued.
338 
339  @param channel The channel name
340 
341  @return the operation status
342  @retval <0 Error
343  @retval 0 Applier is not waiting
344  @retval 1 Applier is waiting
345 */
346 int channel_is_applier_waiting(const char *channel);
347 
348 /**
349  Checks if the applier thread, and its workers when parallel applier is
350  enabled, has already consumed all relay log, that is, applier thread
351  is waiting for transactions to be queued.
352 
353  @param thread_id the applier thread id to check
354  @param worker flag to indicate if thread is a parallel worker
355 
356  @return the operation status
357  @retval -1 Unable to find applier thread
358  @retval 0 Applier thread is not waiting
359  @retval 1 Applier thread is waiting
360 */
362  bool worker = false);
363 
364 /**
365  Flush the channel.
366 
367  @return the operation status
368  @retval 0 OK
369  @retval != 0 Error on flush
370 */
371 int channel_flush(const char *channel);
372 
373 /**
374  Initializes channel structures if needed.
375 
376  @return the operation status
377  @retval 0 OK
378  @retval != 0 Error on queue
379 */
381 
382 /**
383  Returns the receiver thread retrieved GTID set in string format.
384 
385  @param channel The channel name.
386  @param[out] retrieved_set Pointer to pointer to string. The function will
387  set it to point to a newly allocated buffer, or
388  NULL on out of memory.
389 
390  @return the operation status
391  @retval 0 OK
392  @retval !=0 Error on retrieval
393 */
394 int channel_get_retrieved_gtid_set(const char *channel, char **retrieved_set);
395 
396 /**
397  Tells if the selected component of the channel is stopping or not.
398 
399  @param channel The channel name
400  @param type The thread that should be checked.
401 
402  @return is the channel (component) stopping
403  @retval true Yes
404  @retval false No, no type was specified or the channel does not exist.
405 */
407 
408 /**
409  Checks if the given channel's relaylog contains a partial transaction.
410 
411  @param channel The channel name
412 
413  @retval true If relaylog contains partial transcation.
414  @retval false If relaylog does not contain partial transaction.
415 */
417 
418 /**
419  Checks if any slave threads of any channel is running
420 
421  @param[in] thread_mask type of slave thread- IO/SQL or any
422 
423  @retval true atleast one channel threads are running.
424  @retval false none of the the channels are running.
425 */
426 bool is_any_slave_channel_running(int thread_mask);
427 
428 /**
429  Method to get the credentials configured for a channel
430 
431  @param[in] channel The channel name
432  @param[out] user The user to extract
433  @param[out] password The password to extract
434 
435  @return the operation status
436  @retval false OK
437  @retval true Error, channel not found
438 */
439 int channel_get_credentials(const char *channel, std::string &user,
440  std::string &password);
441 
442 /**
443  Return type for function
444  has_any_slave_channel_open_temp_table_or_is_its_applier_running()
445 */
447  /*
448  None of all slave channel appliers are running and none
449  of all slave channels have open temporary table(s).
450  */
452  /* At least one slave channel applier is running. */
454  /* At least one slave channel has open temporary table(s). */
456 };
457 
458 /**
459  Checks if any slave channel applier is running or any slave channel has open
460  temporary table(s). This holds handled appliers' run_locks until finding a
461  running slave channel applier or a slave channel which has open temporary
462  table(s), or handling all slave channels.
463 
464  @return SLAVE_CHANNEL_NO_APPLIER_RUNNING_AND_NO_OPEN_TEMPORARY_TABLE,
465  SLAVE_CHANNEL_APPLIER_IS_RUNNING or
466  SLAVE_CHANNEL_HAS_OPEN_TEMPORARY_TABLE.
467 */
470 
471 /**
472  Delete stored credentials from Slave_credentials
473  @param[in] channel_name The channel name
474 
475  @return the operation status
476  @retval 0 OK
477  @retval 1 Error, channel not found
478 
479  */
480 int channel_delete_credentials(const char *channel_name);
481 #endif // RPL_SERVICE_INTERFACE_INCLUDE
int auto_position
Definition: rpl_channel_service_interface.h:93
char * ssl_crl_file_name
Definition: rpl_channel_service_interface.h:71
char * user
Definition: mysqladmin.cc:59
int replicate_same_server_id
Definition: rpl_channel_service_interface.h:97
Definition: rpl_channel_service_interface.h:58
unsigned int zstd_compression_level
Definition: rpl_channel_service_interface.h:107
char * tls_version
Definition: rpl_channel_service_interface.h:76
Definition: rpl_channel_service_interface.h:123
int channel_purge_queue(const char *channel, bool reset_all)
Purges the channel logs.
Definition: rpl_channel_service_interface.cc:656
int channel_mts_parallel_workers
Definition: rpl_channel_service_interface.h:95
char * ssl_ca_file_name
Definition: rpl_channel_service_interface.h:68
SSL information to be used when creating a channel.
Definition: rpl_channel_service_interface.h:66
int channel_stop(const char *channel, int threads_to_stop, long timeout)
Stops the channel threads according to the given options.
Definition: rpl_channel_service_interface.cc:573
int channel_mts_checkpoint_group
Definition: rpl_channel_service_interface.h:96
char * user
Definition: rpl_channel_service_interface.h:90
enum_slave_channel_status has_any_slave_channel_open_temp_table_or_is_its_applier_running()
Checks if any slave channel applier is running or any slave channel has open temporary table(s)...
Definition: rpl_channel_service_interface.cc:1178
Definition: task.h:437
Definition: buf0block_hint.cc:29
bool channel_is_active(const char *channel, enum_channel_thread_types type)
Tells if the selected component of the channel is active or not.
Definition: rpl_channel_service_interface.cc:681
int thd_tx_priority
Definition: rpl_channel_service_interface.h:98
Definition: rpl_channel_service_interface.h:121
char * view_id
Definition: rpl_channel_service_interface.h:143
bool preserve_relay_logs
Definition: rpl_channel_service_interface.h:102
int initialize_channel_service_interface()
Initializes channel structures if needed.
Definition: rpl_channel_service_interface.cc:87
int channel_start(const char *channel, Channel_connection_info *connection_info, int threads_to_start, int wait_for_connection)
Start the Applier/Receiver threads according to the given options.
Definition: rpl_channel_service_interface.cc:411
Definition: rpl_channel_service_interface.h:455
bool is_any_slave_channel_running(int thread_mask)
Checks if any slave threads of any channel is running.
Definition: rpl_channel_service_interface.cc:1139
int channel_is_applier_thread_waiting(unsigned long thread_id, bool worker=false)
Checks if the applier thread, and its workers when parallel applier is enabled, has already consumed ...
Definition: rpl_channel_service_interface.cc:995
bool is_partial_transaction_on_channel_relay_log(const char *channel)
Checks if the given channel&#39;s relaylog contains a partial transaction.
Definition: rpl_channel_service_interface.cc:1126
enum_multi_threaded_workers_type
Know parallelization options that can be applied to channel appliers.
Definition: rpl_channel_service_interface.h:57
Definition: rpl_channel_service_interface.h:132
Definition: rpl_channel_service_interface.h:131
Definition: rpl_channel_service_interface.h:59
int channel_queue_packet(const char *channel, const char *buf, unsigned long len)
Queues a event packet into the current active channel.
Definition: rpl_channel_service_interface.cc:860
char * public_key_path
Definition: rpl_channel_service_interface.h:103
int connect_retry
Definition: rpl_channel_service_interface.h:100
int channel_flush(const char *channel)
Flush the channel.
Definition: rpl_channel_service_interface.cc:1018
char * ssl_ca_directory
Definition: rpl_channel_service_interface.h:69
char * password
Definition: rpl_channel_service_interface.h:91
void initialize_channel_connection_info(Channel_connection_info *channel_info)
Definition: rpl_channel_service_interface.cc:220
char * ssl_key
Definition: rpl_channel_service_interface.h:73
int channel_wait_until_transactions_applied(const char *channel, const char *gtid_set, double timeout, bool update_THD_status=true)
Checks if all the transactions in the given set were executed.
Definition: rpl_channel_service_interface.cc:919
int channel_delete_credentials(const char *channel_name)
Delete stored credentials from Slave_credentials.
Definition: rpl_channel_service_interface.cc:1228
Definition: rpl_channel_service_interface.h:133
int until_condition
Definition: rpl_channel_service_interface.h:141
enum_slave_channel_status
Return type for function has_any_slave_channel_open_temp_table_or_is_its_applier_running() ...
Definition: rpl_channel_service_interface.h:446
Channel information to connect to a receiver.
Definition: rpl_channel_service_interface.h:140
int channel_get_retrieved_gtid_set(const char *channel, char **retrieved_set)
Returns the receiver thread retrieved GTID set in string format.
Definition: rpl_channel_service_interface.cc:1037
Definition: rpl_channel_service_interface.h:130
int channel_wait_until_apply_queue_applied(const char *channel, double timeout)
Checks if all the queued transactions were executed.
Definition: rpl_channel_service_interface.cc:880
enum_channel_until_condition
The known until conditions that can be applied to channels.
Definition: rpl_channel_service_interface.h:129
int retry_count
Definition: rpl_channel_service_interface.h:101
int channel_stop_all(int threads_to_stop, long timeout, std::string *error_message)
Stops all the running channel threads according to the given options.
Definition: rpl_channel_service_interface.cc:587
void initialize_channel_ssl_info(Channel_ssl_info *channel_ssl_info)
Definition: rpl_channel_service_interface.cc:206
char * gtid
Definition: rpl_channel_service_interface.h:142
Channel_ssl_info * ssl_info
Definition: rpl_channel_service_interface.h:92
char * compression_algorithm
Definition: rpl_channel_service_interface.h:106
char * ssl_cert_file_name
Definition: rpl_channel_service_interface.h:70
Definition: rpl_channel_service_interface.h:134
bool channel_is_stopping(const char *channel, enum_channel_thread_types type)
Tells if the selected component of the channel is stopping or not.
Definition: rpl_channel_service_interface.cc:1096
enum_channel_type type
Definition: rpl_channel_service_interface.h:87
int binlog_dump_thread_kill()
Kills the Binlog Dump threads.
Definition: rpl_channel_service_interface.cc:648
char * hostname
Definition: rpl_channel_service_interface.h:88
int channel_get_credentials(const char *channel, std::string &user, std::string &password)
Method to get the credentials configured for a channel.
Definition: rpl_channel_service_interface.cc:1062
enum_channel_thread_types
The known types of channel threads.
Definition: rpl_channel_service_interface.h:120
char * ssl_cipher
Definition: rpl_channel_service_interface.h:74
void initialize_channel_creation_info(Channel_creation_info *channel_info)
Definition: rpl_channel_service_interface.cc:183
char * ssl_crl_directory
Definition: rpl_channel_service_interface.h:72
Definition: rpl_channel_service_interface.h:51
Definition: rpl_channel_service_interface.h:453
char * tls_ciphersuites
Definition: rpl_channel_service_interface.h:77
static char * password
Definition: mysql_secure_installation.cc:55
int use_ssl
Definition: rpl_channel_service_interface.h:67
int channel_get_thread_id(const char *channel, enum_channel_thread_types thread_type, unsigned long **thread_id)
Returns the id(s) of the channel threads: receiver or applier.
Definition: rpl_channel_service_interface.cc:712
thread_type
Definition: memcached.h:234
int port
Definition: rpl_channel_service_interface.h:89
int channel_create(const char *channel, Channel_creation_info *channel_information)
Initializes a channel connection in a similar way to a change master command.
Definition: rpl_channel_service_interface.cc:275
int get_public_key
Definition: rpl_channel_service_interface.h:104
int channel_is_applier_waiting(const char *channel)
Checks if the applier, and its workers when parallel applier is enabled, has already consumed all rel...
Definition: rpl_channel_service_interface.cc:948
int ssl_verify_server_cert
Definition: rpl_channel_service_interface.h:75
int channel_add_executed_gtids_to_received_gtids(const char *channel)
Adds server executed GTID set to channel received GTID set.
Definition: rpl_channel_service_interface.cc:839
int sql_delay
Definition: rpl_channel_service_interface.h:99
Definition: rpl_channel_service_interface.h:122
Creation information for a channel.
Definition: rpl_channel_service_interface.h:86
enum_channel_type
Types of channels.
Definition: rpl_channel_service_interface.h:49
long long channel_get_last_delivered_gno(const char *channel, int sidno)
Returns last GNO from applier from a given UUID.
Definition: rpl_channel_service_interface.cc:804
static my_thread_id thread_id
Definition: my_thr_init.cc:62
Definition: rpl_channel_service_interface.h:451
int channel_mts_parallel_type
Definition: rpl_channel_service_interface.h:94
Definition: rpl_channel_service_interface.h:50