MySQL 8.3.0
Source Code Documentation
ha_federated.h
Go to the documentation of this file.
1/* Copyright (c) 2004, 2023, 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 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/*
24 Please read ha_exmple.cc before reading this file.
25 Please keep in mind that the federated storage engine implements all methods
26 that are required to be implemented. handler.h has a full list of methods
27 that you can implement.
28*/
29
30#include <mysql.h>
31#include <sys/types.h>
32
33#include "my_dbug.h"
34#include "my_inttypes.h"
35#include "prealloced_array.h"
36#include "sql/handler.h"
37#include "thr_lock.h"
38
39/*
40 handler::print_error has a case statement for error numbers.
41 This value is (10000) is far out of range and will envoke the
42 default: case.
43 (Current error range is 120-159 from include/my_base.h)
44*/
45#define HA_FEDERATED_ERROR_WITH_REMOTE_SYSTEM 10000
46
47#define FEDERATED_QUERY_BUFFER_SIZE STRING_BUFFER_USUAL_SIZE * 5
48#define FEDERATED_RECORDS_IN_RANGE 2
49#define FEDERATED_MAX_KEY_LENGTH 3500 // Same as innodb
50
51/*
52 FEDERATED_SHARE is a structure that will be shared among all open handlers
53 The example implements the minimum of what you will probably need.
54*/
57
58 bool parsed;
59 /* this key is unique db/tablename */
60 const char *share_key;
61 /*
62 the primary select query to be used in rnd_init
63 */
65 /*
66 remote host info, parse_url supplies
67 */
70 char *scheme;
72 char *hostname;
73 char *username;
74 char *password;
75 char *database;
77 char *table;
78 const char *socket;
79 char *sport;
81 ushort port;
82
87};
88
89/*
90 Class definition for the storage engine
91*/
92class ha_federated : public handler {
93 THR_LOCK_DATA lock; /* MySQL lock */
94 FEDERATED_SHARE *share; /* Shared lock info */
95 MYSQL *mysql; /* MySQL connection */
97 /**
98 Array of all stored results we get during a query execution.
99 */
102 MYSQL_ROW_OFFSET current_position; // Current position used by ::position()
108 /// Memory area for BLOB data.
110
111 private:
112 /*
113 return 0 on success
114 return errorcode otherwise
115 */
118 bool create_where_from_key(String *to, KEY *key_info,
119 const key_range *start_key,
120 const key_range *end_key, bool records_in_range,
121 bool eq_range);
122 int stash_remote_error();
123
125
127 int index_read_idx_with_result_set(uchar *buf, uint index, const uchar *key,
128 uint key_len, ha_rkey_function find_flag,
129 MYSQL_RES **result);
130 int real_query(const char *query, size_t length);
131 int real_connect();
132
133 public:
134 ha_federated(handlerton *hton, TABLE_SHARE *table_arg);
135 ~ha_federated() override = default;
136 /* The name that will be used for display purposes */
137 const char *table_type() const override { return "FEDERATED"; }
138 /*
139 Next pointer used in transaction
140 */
142 /*
143 This is a list of flags that says what the storage engine
144 implements. The current table flags are documented in
145 handler.h
146 */
147 ulonglong table_flags() const override {
148 /* fix server to be able to get remote server table flags */
154 HA_NO_TRANSACTIONS /* until fixed by WL#2952 */ |
156 }
157 /*
158 This is a bitmap of flags that says how the storage engine
159 implements indexes. The current index flags are documented in
160 handler.h. If you do not implement indexes, just return zero
161 here.
162
163 part is the key part to check. First key part is 0
164 If all_parts it's set, MySQL want to know the flags for the combined
165 index up to and including 'part'.
166 */
167 /* fix server to be able to get remote server index flags */
168 ulong index_flags(uint, uint, bool) const override {
170 }
171 uint max_supported_record_length() const override {
172 return HA_MAX_REC_LENGTH;
173 }
174 uint max_supported_keys() const override { return MAX_KEY; }
175 uint max_supported_key_parts() const override { return MAX_REF_PARTS; }
176 uint max_supported_key_length() const override {
178 }
180 [[maybe_unused]]) const override {
182 }
183 /*
184 Called in test_quick_select to determine if indexes should be used.
185 Normally, we need to know number of blocks . For federated we need to
186 know number of blocks on remote side, and number of packets and blocks
187 on the network side (?)
188 Talk to Kostja about this - how to get the
189 number of rows * ...
190 disk scan time on other side (block size, size of the row) + network time
191 ... The reason for "records * 1000" is that such a large number forces this
192 to use indexes "
193 */
194 double scan_time() override {
195 DBUG_PRINT("info", ("records %lu", (ulong)stats.records));
196 return (double)(stats.records * 1000);
197 }
198 /*
199 The next method will never be called if you do not implement indexes.
200 */
201 double read_time(uint, uint, ha_rows rows) override {
202 /*
203 Per Brian, this number is bogus, but this method must be implemented,
204 and at a later date, he intends to document this issue for handler code
205 */
206 return (double)rows / 20.0 + 1;
207 }
208
209 /*
210 Everything below are methods that we implement in ha_federated.cc.
211
212 Most of these methods are not obligatory, skip them and
213 MySQL will treat them as not implemented
214 */
215 int open(const char *name, int mode, uint test_if_locked,
216 const dd::Table *table_def) override; // required
217 int close(void) override; // required
218
219 void start_bulk_insert(ha_rows rows) override;
220 int end_bulk_insert() override;
221 int write_row(uchar *buf) override;
222 int update_row(const uchar *old_data, uchar *new_data) override;
223 int delete_row(const uchar *buf) override;
224 int index_init(uint keynr, bool sorted) override;
226 int index_read_idx_map(uchar *buf, uint index, const uchar *key,
227 key_part_map keypart_map,
228 enum ha_rkey_function find_flag) override;
229 int index_read(uchar *buf, const uchar *key, uint key_len,
230 enum ha_rkey_function find_flag) override;
231 int index_read_idx(uchar *buf, uint idx, const uchar *key, uint key_len,
232 enum ha_rkey_function find_flag);
233 int index_next(uchar *buf) override;
234 int index_end() override;
235 int read_range_first(const key_range *start_key, const key_range *end_key,
236 bool eq_range, bool sorted) override;
237 int read_range_next() override;
238 /*
239 unlike index_init(), rnd_init() can be called two times
240 without rnd_end() in between (it only makes sense if scan=1).
241 then the second call should prepare for the new table scan
242 (e.g if rnd_init allocates the cursor, second call should
243 position it to the start of the table, no need to deallocate
244 and allocate it again
245 */
246 int rnd_init(bool scan) override; // required
247 int rnd_end() override;
248 int rnd_next(uchar *buf) override; // required
249 int rnd_next_int(uchar *buf);
250 int rnd_pos(uchar *buf, uchar *pos) override; // required
251 void position(const uchar *record) override; // required
252 int info(uint) override; // required
253 int extra(ha_extra_function operation) override;
254
255 void update_auto_increment(void);
256 int repair(THD *thd, HA_CHECK_OPT *check_opt) override;
257 int optimize(THD *thd, HA_CHECK_OPT *check_opt) override;
258
259 int delete_all_rows(void) override;
260 int truncate(dd::Table *table_def) override;
261 int create(const char *name, TABLE *form, HA_CREATE_INFO *create_info,
262 dd::Table *table_def) override; // required
263 ha_rows records_in_range(uint inx, key_range *start_key,
264 key_range *end_key) override;
265
267 THD *thd, THR_LOCK_DATA **to,
268 enum thr_lock_type lock_type) override; // required
269 bool get_error_message(int error, String *buf) override;
270
272 void free_result();
273
274 int external_lock(THD *thd, int lock_type) override;
275 int connection_commit();
277 int connection_autocommit(bool state);
278 int execute_simple_query(const char *query, int len);
279 int reset(void) override;
280 int rnd_pos_by_record(uchar *record) override;
281};
app_data_ptr new_data(u_int n, char *val, cons_type consensus)
Definition: key.h:112
A typesafe replacement for DYNAMIC_ARRAY.
Definition: prealloced_array.h:70
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:166
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:35
Definition: table.h:46
Definition: ha_federated.h:92
int truncate(dd::Table *table_def) override
Quickly remove all rows from a table.
Definition: ha_federated.cc:2812
uint max_supported_key_length() const override
Definition: ha_federated.h:176
int index_read_idx_with_result_set(uchar *buf, uint index, const uchar *key, uint key_len, ha_rkey_function find_flag, MYSQL_RES **result)
Definition: ha_federated.cc:2260
ha_federated * trx_next
Definition: ha_federated.h:141
int create(const char *name, TABLE *form, HA_CREATE_INFO *create_info, dd::Table *table_def) override
Create table (implementation).
Definition: ha_federated.cc:2904
int read_next(uchar *buf, MYSQL_RES *result)
Definition: ha_federated.cc:2507
int real_connect()
Definition: ha_federated.cc:2916
int index_next(uchar *buf) override
Definition: ha_federated.cc:2377
ha_federated(handlerton *hton, TABLE_SHARE *table_arg)
Definition: ha_federated.cc:885
int rnd_next(uchar *buf) override
Definition: ha_federated.cc:2466
MEM_ROOT m_blob_root
Memory area for BLOB data.
Definition: ha_federated.h:109
int index_read_idx(uchar *buf, uint idx, const uchar *key, uint key_len, enum ha_rkey_function find_flag)
Definition: ha_federated.cc:2237
int delete_row(const uchar *buf) override
Definition: ha_federated.cc:2126
int open(const char *name, int mode, uint test_if_locked, const dd::Table *table_def) override
Definition: ha_federated.cc:1565
FEDERATED_SHARE * share
Definition: ha_federated.h:94
MYSQL_RES * stored_result
Definition: ha_federated.h:96
int index_init(uint keynr, bool sorted) override
Definition: ha_federated.cc:2326
int connection_commit()
Definition: ha_federated.cc:3161
int index_read(uchar *buf, const uchar *key, uint key_len, enum ha_rkey_function find_flag) override
Definition: ha_federated.cc:2213
double scan_time() override
Definition: ha_federated.h:194
uint convert_row_to_internal_format(uchar *buf, MYSQL_ROW row, MYSQL_RES *result)
Definition: ha_federated.cc:914
int reset(void) override
Reset state of file to after 'open'.
Definition: ha_federated.cc:2758
char remote_error_buf[FEDERATED_QUERY_BUFFER_SIZE]
Definition: ha_federated.h:104
bool position_called
Definition: ha_federated.h:101
int stash_remote_error()
Definition: ha_federated.cc:3052
int close(void) override
Definition: ha_federated.cc:1592
int connection_autocommit(bool state)
Definition: ha_federated.cc:3171
bool get_error_message(int error, String *buf) override
Return an error message specific to this handler.
Definition: ha_federated.cc:3065
ulonglong table_flags() const override
Definition: ha_federated.h:147
THR_LOCK_DATA lock
Definition: ha_federated.h:93
int index_end() override
Definition: ha_federated.cc:2448
uint max_supported_key_part_length(HA_CREATE_INFO *create_info) const override
Definition: ha_federated.h:179
int read_range_first(const key_range *start_key, const key_range *end_key, bool eq_range, bool sorted) override
Read first row between two ranges.
Definition: ha_federated.cc:2337
double read_time(uint, uint, ha_rows rows) override
The cost of reading a set of ranges from the table using an index to access it.
Definition: ha_federated.h:201
int connection_rollback()
Definition: ha_federated.cc:3166
void start_bulk_insert(ha_rows rows) override
Prepares the storage engine for bulk inserts.
Definition: ha_federated.cc:1848
int extra(ha_extra_function operation) override
Handles extra signals from MySQL server.
Definition: ha_federated.cc:2718
int delete_all_rows(void) override
Delete all rows in a table.
Definition: ha_federated.cc:2785
MYSQL_ROW_OFFSET current_position
Definition: ha_federated.h:102
int end_bulk_insert() override
End bulk insert.
Definition: ha_federated.cc:1886
DYNAMIC_STRING bulk_insert
Definition: ha_federated.h:107
int index_read_idx_map(uchar *buf, uint index, const uchar *key, key_part_map keypart_map, enum ha_rkey_function find_flag) override
Positions an index cursor to the index specified in argument.
Definition: ha_federated.cc:2192
MYSQL_RES * store_result(MYSQL *mysql)
Store a result set.
Definition: ha_federated.cc:3092
int rnd_pos_by_record(uchar *record) override
This function only works for handlers having HA_PRIMARY_KEY_REQUIRED_FOR_POSITION set.
Definition: ha_federated.cc:3187
MYSQL * mysql
Definition: ha_federated.h:95
int repair(THD *thd, HA_CHECK_OPT *check_opt) override
In this method check_opt can be modified to specify CHECK option to use to call check() upon the tabl...
Definition: ha_federated.cc:1939
bool create_where_from_key(String *to, KEY *key_info, const key_range *start_key, const key_range *end_key, bool records_in_range, bool eq_range)
Definition: ha_federated.cc:1263
int update_row(const uchar *old_data, uchar *new_data) override
Update a single row.
Definition: ha_federated.cc:1979
int real_query(const char *query, size_t length)
Definition: ha_federated.cc:2994
void update_auto_increment(void)
Definition: ha_federated.cc:1911
uint max_supported_record_length() const override
Definition: ha_federated.h:171
~ha_federated() override=default
bool insert_dup_update
Definition: ha_federated.h:106
const char * table_type() const override
The following can be called without an open handler.
Definition: ha_federated.h:137
ulong index_flags(uint, uint, bool) const override
Definition: ha_federated.h:168
int execute_simple_query(const char *query, int len)
Definition: ha_federated.cc:3178
void position(const uchar *record) override
Store a reference to current row.
Definition: ha_federated.cc:2543
ha_rows records_in_range(uint inx, key_range *start_key, key_range *end_key) override
Find number of records in a range.
Definition: ha_federated.cc:1542
int rnd_pos(uchar *buf, uchar *pos) override
Definition: ha_federated.cc:2565
int rnd_end() override
Definition: ha_federated.cc:2443
int rnd_next_int(uchar *buf)
Definition: ha_federated.cc:2473
int rnd_init(bool scan) override
rnd_init() can be called two times without rnd_end() in between (it only makes sense if scan=1).
Definition: ha_federated.cc:2398
int info(uint) override
General method to gather info from handler.
Definition: ha_federated.cc:2627
int external_lock(THD *thd, int lock_type) override
Is not invoked for non-transactional temporary tables.
Definition: ha_federated.cc:3111
void free_result()
Definition: ha_federated.cc:3102
int write_row(uchar *buf) override
Write a row.
Definition: ha_federated.cc:1712
uint max_supported_key_parts() const override
Definition: ha_federated.h:175
int read_range_next() override
Read next row between two endpoints.
Definition: ha_federated.cc:2369
bool append_stmt_insert(String *query)
Construct the INSERT statement.
Definition: ha_federated.cc:1640
bool ignore_duplicates
Definition: ha_federated.h:105
THR_LOCK_DATA ** store_lock(THD *thd, THR_LOCK_DATA **to, enum thr_lock_type lock_type) override
Is not invoked for non-transactional temporary tables.
Definition: ha_federated.cc:2865
Prealloced_array< MYSQL_RES *, 4 > results
Array of all stored results we get during a query execution.
Definition: ha_federated.h:100
bool replace_duplicates
Definition: ha_federated.h:105
int remote_error_number
Definition: ha_federated.h:103
uint max_supported_keys() const override
Definition: ha_federated.h:174
int optimize(THD *thd, HA_CHECK_OPT *check_opt) override
Definition: ha_federated.cc:1920
ha_rows estimate_rows_upper_bound() override
Return upper bound of current number of records in the table (max.
Definition: ha_federated.cc:2322
The handler class is the interface for dynamically loadable storage engines.
Definition: handler.h:4548
bool eq_range
Definition: handler.h:4608
A table definition from the master.
Definition: rpl_utility.h:247
#define FEDERATED_QUERY_BUFFER_SIZE
Definition: ha_federated.h:47
#define FEDERATED_MAX_KEY_LENGTH
Definition: ha_federated.h:49
ha_rkey_function
Definition: my_base.h:77
@ HA_READ_AFTER_KEY
Definition: my_base.h:81
ulong key_part_map
Definition: my_base.h:1007
my_off_t ha_rows
Definition: my_base.h:1140
ha_extra_function
Definition: my_base.h:184
#define DBUG_PRINT(keyword, arglist)
Definition: my_dbug.h:180
Some integer typedefs for easier portability.
unsigned long long int ulonglong
Definition: my_inttypes.h:55
unsigned char uchar
Definition: my_inttypes.h:51
static char * query
Definition: myisam_ftdump.cc:46
This file defines the client API to MySQL and also the ABI of the dynamically linked libmysqlclient.
char ** MYSQL_ROW
Definition: mysql.h:142
static int record
Definition: mysqltest.cc:194
Definition: buf0block_hint.cc:29
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:75
Definition: instrumented_condition_variable.h:31
mode
Definition: file_handle.h:59
required string key
Definition: replication_asynchronous_connection_failover.proto:59
#define HA_BINLOG_ROW_CAPABLE
Definition: handler.h:346
#define HA_FILE_BASED
Definition: handler.h:331
#define HA_CAN_INDEX_BLOBS
Definition: handler.h:264
#define HA_MAX_REC_LENGTH
Definition: handler.h:624
#define HA_READ_NEXT
Definition: handler.h:533
#define HA_CAN_REPAIR
Definition: handler.h:376
#define HA_PARTIAL_COLUMN_READ
Definition: handler.h:218
#define HA_PRIMARY_KEY_IN_READ_INDEX
Definition: handler.h:288
#define HA_NO_PREFIX_CHAR_KEYS
Definition: handler.h:308
#define HA_PRIMARY_KEY_REQUIRED_FOR_POSITION
Definition: handler.h:296
#define HA_BINLOG_STMT_CAPABLE
Definition: handler.h:347
#define HA_READ_RANGE
Definition: handler.h:556
#define HA_PRIMARY_KEY_REQUIRED_FOR_DELETE
Definition: handler.h:304
#define HA_NO_TRANSACTIONS
Definition: handler.h:217
#define HA_AUTO_PART_KEY
Definition: handler.h:269
#define HA_NULL_IN_KEY
Definition: handler.h:252
constexpr const unsigned int MAX_KEY
Definition: sql_const.h:45
constexpr const unsigned int MAX_REF_PARTS
Definition: sql_const.h:46
case opt name
Definition: sslopt-case.h:32
Definition: my_sys.h:321
Definition: ha_federated.h:55
char * table
Definition: ha_federated.h:77
char * connect_string
Definition: ha_federated.h:71
int share_key_length
Definition: ha_federated.h:80
char * hostname
Definition: ha_federated.h:72
char * select_query
Definition: ha_federated.h:64
char * database
Definition: ha_federated.h:75
bool parsed
Definition: ha_federated.h:58
char * server_name
Definition: ha_federated.h:68
char * username
Definition: ha_federated.h:73
size_t use_count
Definition: ha_federated.h:84
size_t table_name_length
Definition: ha_federated.h:83
char * password
Definition: ha_federated.h:74
const char * share_key
Definition: ha_federated.h:60
ushort port
Definition: ha_federated.h:81
THR_LOCK lock
Definition: ha_federated.h:86
size_t connect_string_length
Definition: ha_federated.h:83
char * connection_string
Definition: ha_federated.h:69
char * table_name
Definition: ha_federated.h:76
char * sport
Definition: ha_federated.h:79
const char * socket
Definition: ha_federated.h:78
MEM_ROOT mem_root
Definition: ha_federated.h:56
size_t server_name_length
Definition: ha_federated.h:83
mysql_mutex_t mutex
Definition: ha_federated.h:85
char * scheme
Definition: ha_federated.h:70
Definition: handler.h:3766
Struct to hold information about the table that should be created.
Definition: handler.h:3177
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:82
Definition: mysql.h:337
Definition: mysql.h:150
Definition: mysql.h:297
This structure is shared between different table objects.
Definition: table.h:698
Definition: table.h:1403
Definition: thr_lock.h:123
Definition: thr_lock.h:138
handlerton is a singleton structure - one instance per storage engine - to provide access to storage ...
Definition: handler.h:2718
Definition: my_base.h:1124
An instrumented mutex structure.
Definition: mysql_mutex_bits.h:49
Definition: result.h:29
Definition: mysqlslap.cc:239
thr_lock_type
Definition: thr_lock.h:50