MySQL 8.0.30
Source Code Documentation
handler.h
Go to the documentation of this file.
1#ifndef HANDLER_INCLUDED
2#define HANDLER_INCLUDED
3
4/*
5 Copyright (c) 2000, 2022, Oracle and/or its affiliates.
6
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License, version 2.0,
9 as published by the Free Software Foundation.
10
11 This program is also distributed with certain software (including
12 but not limited to OpenSSL) that is licensed under separate terms,
13 as designated in a particular file or component or in included license
14 documentation. The authors of MySQL hereby grant you an additional
15 permission to link the program and your derivative works with the
16 separately licensed software that they have included with MySQL.
17
18 This program is distributed in the hope that it will be useful,
19 but WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 GNU General Public License, version 2.0, for more details.
22
23 You should have received a copy of the GNU General Public License
24 along with this program; if not, write to the Free Software
25 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
26*/
27
28/* Definitions for parameters to do with handler-routines */
29
30#include <fcntl.h>
31#include <float.h>
32#include <string.h>
33#include <sys/types.h>
34#include <time.h>
35#include <algorithm>
36#include <bitset>
37#include <functional>
38#include <map>
39#include <optional>
40#include <random> // std::mt19937
41#include <set>
42#include <string>
43#include <string_view>
44
46#include "ft_global.h" // ft_hints
47#include "lex_string.h"
48#include "m_ctype.h"
49#include "map_helpers.h"
50#include "my_alloc.h"
51#include "my_base.h"
52#include "my_bitmap.h"
53#include "my_checksum.h" // ha_checksum
54#include "my_compiler.h"
55#include "my_dbug.h"
56#include "my_double2ulonglong.h"
57#include "my_inttypes.h"
58#include "my_io.h"
59#include "my_sys.h"
60#include "my_table_map.h"
61#include "my_thread_local.h" // my_errno
63#include "sql/dd/object_id.h" // dd::Object_id
64#include "sql/dd/string_type.h"
65#include "sql/dd/types/object_table.h" // dd::Object_table
66#include "sql/discrete_interval.h" // Discrete_interval
67#include "sql/key.h"
68#include "sql/sql_const.h" // SHOW_COMP_OPTION
69#include "sql/sql_list.h" // SQL_I_List
70#include "sql/sql_plugin_ref.h" // plugin_ref
71#include "thr_lock.h" // thr_lock_type
72#include "typelib.h"
73
74class Alter_info;
75class Create_field;
76class Field;
77class Item;
78class JOIN;
79class Json_dom;
81class Plugin_table;
83class Record_buffer;
84class SE_cost_constants; // see opt_costconstants.h
85class String;
86class THD;
87class handler;
88class partition_info;
90
91namespace dd {
92class Properties;
93} // namespace dd
94struct AccessPath;
95struct JoinHypergraph;
96struct KEY_CACHE;
97struct LEX;
98struct MY_BITMAP;
99struct SAVEPOINT;
100struct TABLE;
101struct TABLE_LIST;
102struct TABLE_SHARE;
103struct Tablespace_options;
104struct handlerton;
105
106typedef struct xid_t XID;
108struct MDL_key;
109
110namespace dd {
111enum class enum_column_types;
112class Table;
113class Tablespace;
114} // namespace dd
115
116constexpr const ha_rows EXTRA_RECORDS{10};
117
118/** Id for identifying Table SDIs */
119constexpr const uint32 SDI_TYPE_TABLE = 1;
120
121/** Id for identifying Tablespace SDIs */
122constexpr const uint32 SDI_TYPE_TABLESPACE = 2;
123
124/** Key to identify a dictionary object */
125struct sdi_key_t {
126 /** Type of Object, For ex: column, index, etc */
128
129 /** Object id which should be unique in tablespsace */
131};
132
133using sdi_container = std::vector<sdi_key_t>;
136};
137
138typedef bool (*qc_engine_callback)(THD *thd, const char *table_key,
139 uint key_length, ulonglong *engine_data);
140
141typedef bool(stat_print_fn)(THD *thd, const char *type, size_t type_len,
142 const char *file, size_t file_len,
143 const char *status, size_t status_len);
144
145class ha_statistics;
147class Unique_on_insert;
148
149extern ulong savepoint_alloc_size;
150
151/// Maps from slot to plugin. May return NULL if plugin has been unloaded.
153/// Returns the size of the array holding pointers to plugins.
154size_t num_hton2plugins();
155
156/**
157 For unit testing.
158 Insert plugin into arbitrary slot in array.
159 Remove plugin from arbitrary slot in array.
160*/
163
164extern const char *ha_row_type[];
165extern const char *tx_isolation_names[];
166extern const char *binlog_format_names[];
168extern ulong total_ha_2pc;
169
170// the following is for checking tables
171
172#define HA_ADMIN_ALREADY_DONE 1
173#define HA_ADMIN_OK 0
174#define HA_ADMIN_NOT_IMPLEMENTED -1
175#define HA_ADMIN_FAILED -2
176#define HA_ADMIN_CORRUPT -3
177#define HA_ADMIN_INTERNAL_ERROR -4
178#define HA_ADMIN_INVALID -5
179#define HA_ADMIN_REJECT -6
180#define HA_ADMIN_TRY_ALTER -7
181#define HA_ADMIN_WRONG_CHECKSUM -8
182#define HA_ADMIN_NOT_BASE_TABLE -9
183#define HA_ADMIN_NEEDS_UPGRADE -10
184#define HA_ADMIN_NEEDS_ALTER -11
185#define HA_ADMIN_NEEDS_CHECK -12
186#define HA_ADMIN_STATS_UPD_ERR -13
187/** User needs to dump and re-create table to fix pre 5.0 decimal types */
188#define HA_ADMIN_NEEDS_DUMP_UPGRADE -14
189
190/**
191 Return values for check_if_supported_inplace_alter().
192
193 @see check_if_supported_inplace_alter() for description of
194 the individual values.
195*/
206
207/* Bits in table_flags() to show what database can do */
208
209#define HA_NO_TRANSACTIONS (1 << 0) /* Doesn't support transactions */
210#define HA_PARTIAL_COLUMN_READ (1 << 1) /* read may not return all columns */
211/*
212 Used to avoid scanning full tables on an index. If this flag is set then
213 the handler always has a primary key (hidden if not defined) and this
214 index is used for scanning rather than a full table scan in all
215 situations. No separate data/index file.
216*/
217#define HA_TABLE_SCAN_ON_INDEX (1 << 2)
218
219/// Not in use.
220#define HA_UNUSED3 (1 << 3)
221
222/*
223 Can the storage engine handle spatial data.
224 Used to check that no spatial attributes are declared unless
225 the storage engine is capable of handling it.
226*/
227#define HA_CAN_GEOMETRY (1 << 4)
228/*
229 Reading keys in random order is as fast as reading keys in sort order
230 (Used by filesort to decide if we should sort key + data or key +
231 pointer-to-row.)
232*/
233#define HA_FAST_KEY_READ (1 << 5)
234/*
235 Set the following flag if we on delete should force all key to be read
236 and on update read all keys that changes
237*/
238#define HA_REQUIRES_KEY_COLUMNS_FOR_DELETE (1 << 6)
239/*
240 Is NULL values allowed in indexes.
241 If this is not allowed then it is not possible to use an index on a
242 NULLable field.
243*/
244#define HA_NULL_IN_KEY (1 << 7)
245/*
246 Tells that we can the position for the conflicting duplicate key
247 record is stored in table->file->dupp_ref. (insert uses rnd_pos() on
248 this to find the duplicated row)
249*/
250#define HA_DUPLICATE_POS (1 << 8)
251#define HA_NO_BLOBS (1 << 9) /* Doesn't support blobs */
252/*
253 Is the storage engine capable of defining an index of a prefix on
254 a BLOB attribute.
255*/
256#define HA_CAN_INDEX_BLOBS (1 << 10)
257/*
258 Auto increment fields can be part of a multi-part key. For second part
259 auto-increment keys, the auto_incrementing is done in handler.cc
260*/
261#define HA_AUTO_PART_KEY (1 << 11)
262/*
263 Can't define a table without primary key (and cannot handle a table
264 with hidden primary key)
265*/
266#define HA_REQUIRE_PRIMARY_KEY (1 << 12)
267/*
268 Does the counter of records after the info call specify an exact
269 value or not. If it does this flag is set.
270*/
271#define HA_STATS_RECORDS_IS_EXACT (1 << 13)
272/// Not in use.
273#define HA_UNUSED14 (1 << 14)
274/*
275 This parameter is set when the handler will also return the primary key
276 when doing read-only-key on another index, i.e., if we get the primary
277 key columns for free when we do an index read (usually, it also implies
278 that HA_PRIMARY_KEY_REQUIRED_FOR_POSITION flag is set).
279*/
280#define HA_PRIMARY_KEY_IN_READ_INDEX (1 << 15)
281/*
282 If HA_PRIMARY_KEY_REQUIRED_FOR_POSITION is set, it means that to position()
283 uses a primary key given by the record argument.
284 Without primary key, we can't call position().
285 If not set, the position is returned as the current rows position
286 regardless of what argument is given.
287*/
288#define HA_PRIMARY_KEY_REQUIRED_FOR_POSITION (1 << 16)
289#define HA_CAN_RTREEKEYS (1 << 17)
290/// Not in use.
291#define HA_UNUSED18
292/*
293 The following is we need to a primary key to delete (and update) a row.
294 If there is no primary key, all columns needs to be read on update and delete
295*/
296#define HA_PRIMARY_KEY_REQUIRED_FOR_DELETE (1 << 19)
297/*
298 Indexes on prefixes of character fields are not allowed.
299*/
300#define HA_NO_PREFIX_CHAR_KEYS (1 << 20)
301/*
302 Does the storage engine support fulltext indexes.
303*/
304#define HA_CAN_FULLTEXT (1 << 21)
305/*
306 Can the HANDLER interface in the MySQL API be used towards this
307 storage engine.
308*/
309#define HA_CAN_SQL_HANDLER (1 << 22)
310/*
311 Set if the storage engine does not support auto increment fields.
312*/
313#define HA_NO_AUTO_INCREMENT (1 << 23)
314/*
315 Supports CHECKSUM option in CREATE TABLE (MyISAM feature).
316*/
317#define HA_HAS_CHECKSUM (1 << 24)
318/*
319 Table data are stored in separate files (for lower_case_table_names).
320 Should file names always be in lower case (used by engines that map
321 table names to file names.
322*/
323#define HA_FILE_BASED (1 << 26)
324#define HA_NO_VARCHAR (1 << 27)
325/*
326 Is the storage engine capable of handling bit fields.
327*/
328#define HA_CAN_BIT_FIELD (1 << 28)
329#define HA_ANY_INDEX_MAY_BE_UNIQUE (1 << 30)
330#define HA_NO_COPY_ON_ALTER (1LL << 31)
331#define HA_COUNT_ROWS_INSTANT (1LL << 32) /* records() gives exact count*/
332/* Has it's own method of binlog logging */
333#define HA_HAS_OWN_BINLOGGING (1LL << 33)
334/*
335 Engine is capable of row-format and statement-format logging,
336 respectively
337*/
338#define HA_BINLOG_ROW_CAPABLE (1LL << 34)
339#define HA_BINLOG_STMT_CAPABLE (1LL << 35)
340/*
341 When a multiple key conflict happens in a REPLACE command mysql
342 expects the conflicts to be reported in the ascending order of
343 key names.
344
345 For e.g.
346
347 CREATE TABLE t1 (a INT, UNIQUE (a), b INT NOT NULL, UNIQUE (b), c INT NOT
348 NULL, INDEX(c));
349
350 REPLACE INTO t1 VALUES (1,1,1),(2,2,2),(2,1,3);
351
352 MySQL expects the conflict with 'a' to be reported before the conflict with
353 'b'.
354
355 If the underlying storage engine does not report the conflicting keys in
356 ascending order, it causes unexpected errors when the REPLACE command is
357 executed.
358
359 This flag helps the underlying SE to inform the server that the keys are not
360 ordered.
361*/
362#define HA_DUPLICATE_KEY_NOT_IN_ORDER (1LL << 36)
363/*
364 Engine supports REPAIR TABLE. Used by CHECK TABLE FOR UPGRADE if an
365 incompatible table is detected. If this flag is set, CHECK TABLE FOR UPGRADE
366 will report ER_TABLE_NEEDS_UPGRADE, otherwise ER_TABLE_NEED_REBUILD.
367*/
368#define HA_CAN_REPAIR (1LL << 37)
369
370/*
371 Set of all binlog flags. Currently only contain the capabilities
372 flags.
373 */
374#define HA_BINLOG_FLAGS (HA_BINLOG_ROW_CAPABLE | HA_BINLOG_STMT_CAPABLE)
375
376/**
377 The handler supports read before write removal optimization
378
379 Read before write removal may be used for storage engines which support
380 write without previous read of the row to be updated. Handler returning
381 this flag must implement start_read_removal() and end_read_removal().
382 The handler may return "fake" rows constructed from the key of the row
383 asked for. This is used to optimize UPDATE and DELETE by reducing the
384 number of round-trips between handler and storage engine.
385
386 Example:
387 UPDATE a=1 WHERE pk IN (@<keys@>)
388
389 @verbatim
390 mysql_update()
391 {
392 if (<conditions for starting read removal>)
393 start_read_removal()
394 -> handler returns true if read removal supported for this table/query
395
396 while(read_record("pk=<key>"))
397 -> handler returns fake row with column "pk" set to <key>
398
399 ha_update_row()
400 -> handler sends write "a=1" for row with "pk=<key>"
401
402 end_read_removal()
403 -> handler returns the number of rows actually written
404 }
405 @endverbatim
406
407 @note This optimization in combination with batching may be used to
408 remove even more round-trips.
409*/
410#define HA_READ_BEFORE_WRITE_REMOVAL (1LL << 38)
411
412/*
413 Engine supports extended fulltext API
414 */
415#define HA_CAN_FULLTEXT_EXT (1LL << 39)
416
417/*
418 Storage engine doesn't synchronize result set with expected table contents.
419 Used by replication slave to check if it is possible to retrieve rows from
420 the table when deciding whether to do a full table scan, index scan or hash
421 scan while applying a row event.
422 */
423#define HA_READ_OUT_OF_SYNC (1LL << 40)
424
425/*
426 Storage engine supports table export using the
427 FLUSH TABLE <table_list> FOR EXPORT statement.
428 */
429#define HA_CAN_EXPORT (1LL << 41)
430
431/*
432 The handler don't want accesses to this table to
433 be const-table optimized
434*/
435#define HA_BLOCK_CONST_TABLE (1LL << 42)
436
437/*
438 Handler supports FULLTEXT hints
439*/
440#define HA_CAN_FULLTEXT_HINTS (1LL << 43)
441
442/**
443 Storage engine doesn't support LOCK TABLE ... READ LOCAL locks
444 but doesn't want to use handler::store_lock() API for upgrading
445 them to LOCK TABLE ... READ locks, for example, because it doesn't
446 use THR_LOCK locks at all.
447*/
448#define HA_NO_READ_LOCAL_LOCK (1LL << 44)
449
450/**
451 A storage engine is compatible with the attachable transaction requirements
452 means that
453
454 - either SE detects the fact that THD::ha_data was reset and starts a new
455 attachable transaction, closes attachable transaction on close_connection
456 and resumes regular (outer) transaction when THD::ha_data is restored;
457
458 - or SE completely ignores THD::ha_data and close_connection like MyISAM
459 does.
460*/
461#define HA_ATTACHABLE_TRX_COMPATIBLE (1LL << 45)
462
463/**
464 Handler supports Generated Columns
465*/
466#define HA_GENERATED_COLUMNS (1LL << 46)
467
468/**
469 Supports index on virtual generated column
470*/
471#define HA_CAN_INDEX_VIRTUAL_GENERATED_COLUMN (1LL << 47)
472
473/**
474 Supports descending indexes
475*/
476#define HA_DESCENDING_INDEX (1LL << 48)
477
478/**
479 Supports partial update of BLOB columns.
480*/
481#define HA_BLOB_PARTIAL_UPDATE (1LL << 49)
482
483/**
484 If this isn't defined, only columns/indexes with Cartesian coordinate systems
485 (projected SRS or SRID 0) is supported. Columns/indexes without SRID
486 restriction is also supported if this isn't defined.
487*/
488#define HA_SUPPORTS_GEOGRAPHIC_GEOMETRY_COLUMN (1LL << 50)
489
490/**
491 Handler supports expressions as DEFAULT for a column.
492*/
493#define HA_SUPPORTS_DEFAULT_EXPRESSION (1LL << 51)
494
495/**
496 Handlers with this flag set do not support UPDATE operations.
497*/
498#define HA_UPDATE_NOT_SUPPORTED (1LL << 52)
499
500/**
501 Handlers with this flag set do not support DELETE operations.
502*/
503#define HA_DELETE_NOT_SUPPORTED (1LL << 53)
504
505/**
506 The storage engine does not support using indexes for access. Indexes can only
507 be used for estimating cost.
508*/
509#define HA_NO_INDEX_ACCESS (1LL << 54)
510
511/**
512 Supports multi-valued index
513*/
514#define HA_MULTI_VALUED_KEY_SUPPORT (1LL << 55)
515
516/*
517 Bits in index_flags(index_number) for what you can do with index.
518 If you do not implement indexes, just return zero here.
519*/
520/*
521 Does the index support read next, this is assumed in the server
522 code and never checked so all indexes must support this.
523 Note that the handler can be used even if it doesn't have any index.
524*/
525#define HA_READ_NEXT 1 /* TODO really use this flag */
526/*
527 Can the index be used to scan backwards (supports ::index_prev).
528*/
529#define HA_READ_PREV 2
530/*
531 Can the index deliver its record in index order. Typically true for
532 all ordered indexes and not true for hash indexes. Used to set keymap
533 part_of_sortkey.
534 This keymap is only used to find indexes usable for resolving an ORDER BY
535 in the query. Thus in most cases index_read will work just fine without
536 order in result production. When this flag is set it is however safe to
537 order all output started by index_read since most engines do this. With
538 read_multi_range calls there is a specific flag setting order or not
539 order so in those cases ordering of index output can be avoided.
540*/
541#define HA_READ_ORDER 4
542/*
543 Specify whether index can handle ranges, typically true for all
544 ordered indexes and not true for hash indexes.
545 Used by optimiser to check if ranges (as key >= 5) can be optimised
546 by index.
547*/
548#define HA_READ_RANGE 8
549/*
550 Can't use part key searches. This is typically true for hash indexes
551 and typically not true for ordered indexes.
552*/
553#define HA_ONLY_WHOLE_INDEX 16
554/*
555 Index does not store NULL values, even if the column is nullable.
556 (KEY::flags may still contain HA_NULL_PART_KEY)
557 If the key has a NULL-value, the handler need to do a full table scan
558 instead of using this key. This is typically true for NDB hash indexes.
559*/
560#define HA_TABLE_SCAN_ON_NULL 32
561/*
562 Does the storage engine support index-only scans on this index.
563 Enables use of HA_EXTRA_KEYREAD and HA_EXTRA_NO_KEYREAD
564 Used to set Key_map keys_for_keyread and to check in optimiser for
565 index-only scans. When doing a read under HA_EXTRA_KEYREAD the handler
566 only have to fill in the columns the key covers. If
567 HA_PRIMARY_KEY_IN_READ_INDEX is set then also the PRIMARY KEY columns
568 must be updated in the row.
569*/
570#define HA_KEYREAD_ONLY 64
571/*
572 Index scan will not return records in rowid order. Not guaranteed to be
573 set for unordered (e.g. HASH) indexes.
574*/
575#define HA_KEY_SCAN_NOT_ROR 128
576#define HA_DO_INDEX_COND_PUSHDOWN 256 /* Supports Index Condition Pushdown */
577
578/* operations for disable/enable indexes */
579#define HA_KEY_SWITCH_NONUNIQ 0
580#define HA_KEY_SWITCH_ALL 1
581#define HA_KEY_SWITCH_NONUNIQ_SAVE 2
582#define HA_KEY_SWITCH_ALL_SAVE 3
583
584/*
585 Use this instead of 0 as the initial value for the slot number of
586 handlerton, so that we can distinguish uninitialized slot number
587 from slot 0.
588*/
589#define HA_SLOT_UNDEF ((uint)-1)
590
591/*
592 Parameters for open() (in register form->filestat)
593 HA_GET_INFO does an implicit HA_ABORT_IF_LOCKED
594*/
595
596#define HA_OPEN_KEYFILE 1
597#define HA_OPEN_RNDFILE 2
598#define HA_GET_INDEX 4
599#define HA_GET_INFO 8 /* do a handler::info() after open */
600#define HA_READ_ONLY 16 /* File opened as readonly */
601/* Try readonly if can't open with read and write */
602#define HA_TRY_READ_ONLY 32
603#define HA_WAIT_IF_LOCKED 64 /* Wait if locked on open */
604#define HA_ABORT_IF_LOCKED 128 /* skip if locked on open.*/
605#define HA_BLOCK_LOCK 256 /* unlock when reading some records */
606#define HA_OPEN_TEMPORARY 512
607
608/* Some key definitions */
609#define HA_KEY_NULL_LENGTH 1
610#define HA_KEY_BLOB_LENGTH 2
611
612#define HA_LEX_CREATE_TMP_TABLE 1
613#define HA_LEX_CREATE_IF_NOT_EXISTS 2
614#define HA_LEX_CREATE_TABLE_LIKE 4
615#define HA_LEX_CREATE_INTERNAL_TMP_TABLE 8
616#define HA_MAX_REC_LENGTH 65535U
617
618/**
619 Options for the START TRANSACTION statement.
620
621 Note that READ ONLY and READ WRITE are logically mutually exclusive.
622 This is enforced by the parser and depended upon by trans_begin().
623
624 We need two flags instead of one in order to differentiate between
625 situation when no READ WRITE/ONLY clause were given and thus transaction
626 is implicitly READ WRITE and the case when READ WRITE clause was used
627 explicitly.
628*/
629
630// WITH CONSISTENT SNAPSHOT option
632// READ ONLY option
634// READ WRITE option
636// HIGH PRIORITY option
638
660 DB_TYPE_PARTITION_DB, // No longer used.
668 /** Performance schema engine. */
672 DB_TYPE_DEFAULT = 127 // Must be last
674
675enum row_type : int {
683 /** Unused. Reserved for future versions. */
686
694
703};
704
706
707/* Bits in used_fields */
708#define HA_CREATE_USED_AUTO (1L << 0)
709#define HA_CREATE_USED_RAID (1L << 1) // RAID is no longer available
710#define HA_CREATE_USED_UNION (1L << 2)
711#define HA_CREATE_USED_INSERT_METHOD (1L << 3)
712#define HA_CREATE_USED_MIN_ROWS (1L << 4)
713#define HA_CREATE_USED_MAX_ROWS (1L << 5)
714#define HA_CREATE_USED_AVG_ROW_LENGTH (1L << 6)
715#define HA_CREATE_USED_PACK_KEYS (1L << 7)
716#define HA_CREATE_USED_CHARSET (1L << 8)
717#define HA_CREATE_USED_DEFAULT_CHARSET (1L << 9)
718#define HA_CREATE_USED_DATADIR (1L << 10)
719#define HA_CREATE_USED_INDEXDIR (1L << 11)
720#define HA_CREATE_USED_ENGINE (1L << 12)
721#define HA_CREATE_USED_CHECKSUM (1L << 13)
722#define HA_CREATE_USED_DELAY_KEY_WRITE (1L << 14)
723#define HA_CREATE_USED_ROW_FORMAT (1L << 15)
724#define HA_CREATE_USED_COMMENT (1L << 16)
725#define HA_CREATE_USED_PASSWORD (1L << 17)
726#define HA_CREATE_USED_CONNECTION (1L << 18)
727#define HA_CREATE_USED_KEY_BLOCK_SIZE (1L << 19)
728/** Unused. Reserved for future versions. */
729#define HA_CREATE_USED_TRANSACTIONAL (1L << 20)
730/** Unused. Reserved for future versions. */
731#define HA_CREATE_USED_PAGE_CHECKSUM (1L << 21)
732/** This is set whenever STATS_PERSISTENT=0|1|default has been
733specified in CREATE/ALTER TABLE. See also HA_OPTION_STATS_PERSISTENT in
734include/my_base.h. It is possible to distinguish whether
735STATS_PERSISTENT=default has been specified or no STATS_PERSISTENT= is
736given at all. */
737#define HA_CREATE_USED_STATS_PERSISTENT (1L << 22)
738/**
739 This is set whenever STATS_AUTO_RECALC=0|1|default has been
740 specified in CREATE/ALTER TABLE. See enum_stats_auto_recalc.
741 It is possible to distinguish whether STATS_AUTO_RECALC=default
742 has been specified or no STATS_AUTO_RECALC= is given at all.
743*/
744#define HA_CREATE_USED_STATS_AUTO_RECALC (1L << 23)
745/**
746 This is set whenever STATS_SAMPLE_PAGES=N|default has been
747 specified in CREATE/ALTER TABLE. It is possible to distinguish whether
748 STATS_SAMPLE_PAGES=default has been specified or no STATS_SAMPLE_PAGES= is
749 given at all.
750*/
751#define HA_CREATE_USED_STATS_SAMPLE_PAGES (1L << 24)
752
753/**
754 This is set whenever a 'TABLESPACE=...' phrase is used on CREATE TABLE
755*/
756#define HA_CREATE_USED_TABLESPACE (1L << 25)
757
758/** COMPRESSION="zlib|lz4|none" used during table create. */
759#define HA_CREATE_USED_COMPRESS (1L << 26)
760
761/** ENCRYPTION="Y" used during table create. */
762#define HA_CREATE_USED_ENCRYPT (1L << 27)
763
764/**
765 CREATE|ALTER SCHEMA|DATABASE|TABLE has an explicit COLLATE clause.
766
767 Implies HA_CREATE_USED_DEFAULT_CHARSET.
768*/
769#define HA_CREATE_USED_DEFAULT_COLLATE (1L << 28)
770
771/** SECONDARY_ENGINE used during table create. */
772#define HA_CREATE_USED_SECONDARY_ENGINE (1L << 29)
773
774/**
775 CREATE|ALTER SCHEMA|DATABASE has an explicit ENCRYPTION clause.
776
777 Implies HA_CREATE_USED_DEFAULT_ENCRYPTION.
778*/
779#define HA_CREATE_USED_DEFAULT_ENCRYPTION (1L << 30)
780
781/**
782 This option is used to convey that the create table should not
783 commit the operation and keep the transaction started.
784*/
785constexpr const uint64_t HA_CREATE_USED_START_TRANSACTION{1ULL << 31};
786
787constexpr const uint64_t HA_CREATE_USED_ENGINE_ATTRIBUTE{1ULL << 32};
788constexpr const uint64_t HA_CREATE_USED_SECONDARY_ENGINE_ATTRIBUTE{1ULL << 33};
789
790/**
791 ALTER SCHEMA|DATABASE has an explicit READ_ONLY clause.
792
793 Implies HA_CREATE_USED_READ_ONLY.
794*/
795constexpr const uint64_t HA_CREATE_USED_READ_ONLY{1ULL << 34};
796
797/**
798 These flags convey that the options AUTOEXTEND_SIZE has been
799 specified in the CREATE TABLE statement
800*/
801constexpr const uint64_t HA_CREATE_USED_AUTOEXTEND_SIZE{1ULL << 35};
802
803/*
804 End of bits used in used_fields
805*/
806
807/*
808 Structure to hold list of database_name.table_name.
809 This is used at both mysqld and storage engine layer.
810*/
812 const char *db;
813 const char *tablename;
814};
815
816#define MAXGTRIDSIZE 64
817#define MAXBQUALSIZE 64
818
819#define COMPATIBLE_DATA_YES 0
820#define COMPATIBLE_DATA_NO 1
821
822/*
823 These structures are used to pass information from a set of SQL commands
824 on add/drop/change tablespace definitions to the proper hton.
825*/
826#define UNDEF_NODEGROUP 65535
827
828// FUTURE: Combine these two enums into one enum class
843
853
854/**
855 Legacy struct for passing tablespace information to SEs.
856
857 FUTURE: Pass all info through dd objects
858 */
860 public:
861 const char *tablespace_name = nullptr;
862 const char *logfile_group_name = nullptr;
866 const char *data_file_name = nullptr;
867 const char *undo_file_name = nullptr;
868 ulonglong extent_size = 1024 * 1024; // Default 1 MByte
869 ulonglong undo_buffer_size = 8 * 1024 * 1024; // Default 8 MByte
870 ulonglong redo_buffer_size = 8 * 1024 * 1024; // Default 8 MByte
871 ulonglong initial_size = 128 * 1024 * 1024; // Default 128 MByte
872 std::optional<ulonglong> autoextend_size; // No autoextension as default
873 ulonglong max_size = 0; // Max size == initial size => no extension
874 ulonglong file_block_size = 0; // 0=default or must be a valid Page Size
877 const char *ts_comment = nullptr;
878 const char *encryption = nullptr;
879
881 return ts_cmd_type == CREATE_TABLESPACE ||
885 }
886
887 /**
888 Proper constructor even for all-public class simplifies initialization and
889 allows members to be const.
890
891 FUTURE: With constructor all members can be made const, and do not need
892 default initializers.
893
894 @param tablespace name of tabelspace (nullptr for logfile group statements)
895 @param logfile_group name of logfile group or nullptr
896 @param cmd main statement type
897 @param alter_tablespace_cmd subcommand type for ALTER TABLESPACE
898 @param datafile tablespace file for CREATE and ALTER ... ADD ...
899 @param undofile only applies to logfile group statements. nullptr otherwise.
900 @param opts options provided by parser
901 */
902 st_alter_tablespace(const char *tablespace, const char *logfile_group,
903 ts_command_type cmd,
904 enum ts_alter_tablespace_type alter_tablespace_cmd,
905 const char *datafile, const char *undofile,
906 const Tablespace_options &opts);
907};
908
909/*
910 Make sure that the order of schema_tables and enum_schema_tables are the same.
911*/
929
932
933/** Clone start operation mode */
935 /** Start a new clone operation */
937
938 /** Re-start a clone operation after failure */
940
941 /** Add a new task to a running clone operation */
943
944 /** Get version for transfer data format */
946
947 /** Max value for clone mode */
950
951/** Clone operation types. */
952enum Ha_clone_type : size_t {
953 /** Caller must block all write operation to the SE. */
955
956 /** For transactional SE, archive redo to support concurrent dml */
958
959 /** For transactional SE, track page changes to support concurrent dml */
961
962 /** For transactional SE, use both page tracking and redo to optimize
963 clone with concurrent dml. Currently supported by Innodb. */
965
966 /** SE supports multiple threads for clone */
968
969 /** SE supports restarting clone after network failure */
971
972 /** Maximum value of clone type */
975
976using Ha_clone_flagset = std::bitset<HA_CLONE_TYPE_MAX>;
977
980
981/** File reference for clone */
983 /** File reference type */
984 enum {
985 /** File handle */
987
988 /** File descriptor */
990
992
993 /** File reference */
994 union {
995 /** File descriptor */
997
998 /** File handle for windows */
1000 };
1001};
1002
1003/* Abstract callback interface to stream data back to the caller. */
1005 protected:
1006 /** Constructor to initialize members. */
1008 : m_hton(),
1009 m_loc_idx(),
1011 m_data_desc(),
1012 m_desc_len(),
1013 m_src_name(),
1014 m_dest_name(),
1016 m_flag() {}
1017
1018 public:
1019 /** Callback providing data from current position of a
1020 file descriptor of specific length.
1021 @param[in] from_file source file to read from
1022 @param[in] len data length
1023 @return error code */
1024 virtual int file_cbk(Ha_clone_file from_file, uint len) = 0;
1025
1026 /** Callback providing data in buffer of specific length.
1027 @param[in] from_buffer source buffer to read from
1028 @param[in] len data length
1029 @return error code */
1030 virtual int buffer_cbk(uchar *from_buffer, uint len) = 0;
1031
1032 /** Callback providing a file descriptor to write data starting
1033 from current position.
1034 @param[in] to_file destination file to write data
1035 @return error code */
1036 virtual int apply_file_cbk(Ha_clone_file to_file) = 0;
1037
1038 /** Callback to get data in buffer.
1039 @param[out] to_buffer data buffer
1040 @param[out] len data length
1041 @return error code */
1042 virtual int apply_buffer_cbk(uchar *&to_buffer, uint &len) = 0;
1043
1044 /** virtual destructor. */
1045 virtual ~Ha_clone_cbk() = default;
1046
1047 /** Set current storage engine handlerton.
1048 @param[in] hton SE handlerton */
1049 void set_hton(handlerton *hton) { m_hton = hton; }
1050
1051 /** Get current storage engine handlerton.
1052 @return SE handlerton */
1053 handlerton *get_hton() { return (m_hton); }
1054
1055 /** Set caller's transfer buffer size. SE can adjust the data chunk size
1056 based on this parameter.
1057 @param[in] size buffer size in bytes */
1059
1060 /** Get caller's transfer buffer size.
1061 @return buffer size in bytes */
1063
1064 /** Set current SE index.
1065 @param[in] idx SE index in locator array */
1066 void set_loc_index(uint idx) { m_loc_idx = idx; }
1067
1068 /** Get current SE index.
1069 @return SE index in locator array */
1071
1072 /** Set data descriptor. SE specific descriptor for the
1073 data transferred by the callbacks.
1074 @param[in] desc serialized data descriptor
1075 @param[in] len length of the descriptor byte stream */
1076 void set_data_desc(const uchar *desc, uint len) {
1077 m_data_desc = desc;
1078 m_desc_len = len;
1079 }
1080
1081 /** Get data descriptor. SE specific descriptor for the
1082 data transferred by the callbacks.
1083 @param[out] lenp length of the descriptor byte stream
1084 @return pointer to the serialized data descriptor */
1085 const uchar *get_data_desc(uint *lenp) {
1086 if (lenp != nullptr) {
1087 *lenp = m_desc_len;
1088 }
1089
1090 return (m_data_desc);
1091 }
1092
1093 /** Get SE source file name. Used for debug printing and error message.
1094 @return null terminated string for source file name */
1095 const char *get_source_name() { return (m_src_name); }
1096
1097 /** Set SE source file name.
1098 @param[in] name null terminated string for source file name */
1099 void set_source_name(const char *name) { m_src_name = name; }
1100
1101 /** Get SE destination file name. Used for debug printing and error message.
1102 @return null terminated string for destination file name */
1103 const char *get_dest_name() { return (m_dest_name); }
1104
1105 /** Set SE destination file name.
1106 @param[in] name null terminated string for destination file name */
1107 void set_dest_name(const char *name) { m_dest_name = name; }
1108
1109 /** Clear all flags set by SE */
1110 void clear_flags() { m_flag = 0; }
1111
1112 /** Mark that ACK is needed for the data transfer before returning
1113 from callback. Set by SE. */
1115
1116 /** Check if ACK is needed for the data transfer
1117 @return true if ACK is needed */
1118 bool is_ack_needed() const { return (m_flag & HA_CLONE_ACK); }
1119
1120 /** Mark that the file descriptor is opened for read/write
1121 with OS buffer cache. For O_DIRECT, the flag is not set. */
1123
1124 /** Check if the file descriptor is opened for read/write with OS
1125 buffer cache. Currently clone avoids using zero copy (sendfile on linux),
1126 if SE is using O_DIRECT. This improves data copy performance.
1127 @return true if O_DIRECT is not used */
1128 bool is_os_buffer_cache() const { return (m_flag & HA_CLONE_FILE_CACHE); }
1129
1130 /** Mark that the file can be transferred with zero copy. */
1132
1133 /** Check if zero copy optimization is suggested. */
1134 bool is_zero_copy() const { return (m_flag & HA_CLONE_ZERO_COPY); }
1135
1136 /** Mark that data needs secure transfer. */
1138
1139 /** Check if data needs secure transfer. */
1140 bool is_secure() const { return (m_flag & HA_CLONE_SECURE); }
1141
1142 /** Set state information and notify state change.
1143 @param[in] estimate estimated bytes for current state. */
1144 void mark_state_change(uint64_t estimate) {
1146 m_state_estimate = estimate;
1147 }
1148
1149 /** Check if SE notified state change. */
1150 bool is_state_change(uint64_t &estimate) {
1151 estimate = m_state_estimate;
1152 return (m_flag & HA_CLONE_STATE_CHANGE);
1153 }
1154
1155 private:
1156 /** Handlerton for the SE */
1158
1159 /** SE index in caller's locator array */
1161
1162 /** Caller's transfer buffer size. */
1164
1165 /** SE's Serialized data descriptor */
1167
1168 /** SE's Serialized descriptor length. */
1170
1171 /** Current source file name */
1172 const char *m_src_name;
1173
1174 /** Current destination file name */
1175 const char *m_dest_name;
1176
1177 /** Estimated bytes to be transferred. */
1179
1180 /** Flag storing data related options */
1182
1183 /** Acknowledgement is needed for the data transfer. */
1184 const int HA_CLONE_ACK = 0x01;
1185
1186 /** Data file is opened for read/write with OS buffer cache. */
1187 const int HA_CLONE_FILE_CACHE = 0x02;
1188
1189 /** Data file can be transferred with zero copy. */
1190 const int HA_CLONE_ZERO_COPY = 0x04;
1191
1192 /** Data needs to be transferred securely over SSL connection. */
1193 const int HA_CLONE_SECURE = 0x08;
1194
1195 /** State change notification by SE. */
1196 const int HA_CLONE_STATE_CHANGE = 0x10;
1197};
1198
1199/**
1200 Column type description for foreign key columns compatibility check.
1201
1202 Contains subset of information from dd::Column class. It is inconvenient
1203 to use dd::Column class directly for such checks because it requires valid
1204 dd::Table object and in some cases we want to produce Ha_fk_column_type
1205 right from column description in Create_field format.
1206*/
1209 /*
1210 Note that both dd::Column::char_length() and length here are really
1211 in bytes.
1212 */
1218};
1219
1220typedef ulonglong my_xid; // this line is the same as in log_event.h
1221/**
1222 Enumeration of possible states for externally coordinated transactions (XA).
1223 */
1225 NOT_FOUND = -1, // Trnasaction not found
1226 PREPARED_IN_SE = 0, // Transaction is prepared in SEs
1227 PREPARED_IN_TC = 1, // Transaction is prepared in SEs and TC
1228 COMMITTED_WITH_ONEPHASE = 2, // Transaction was one-phase committed
1229 COMMITTED = 3, // Transaction was committed
1230 ROLLEDBACK = 4 // Transaction was rolled back
1231};
1232/**
1233 Single occurrence set of XIDs of internally coordinated transactions
1234 found as been committed in the transaction coordinator state.
1235 */
1237 std::unordered_set<my_xid, std::hash<my_xid>, std::equal_to<my_xid>,
1239
1240/**
1241 Class to maintain list of externally coordinated transactions and their
1242 current state at recovery.
1243 */
1245 public:
1246 using pair = std::pair<const XID, enum_ha_recover_xa_state>;
1248 using list = std::map<XID, enum_ha_recover_xa_state, std::less<XID>,
1250 using iterator = std::map<XID, enum_ha_recover_xa_state, std::less<XID>,
1252 using instantiation_tuple = std::tuple<
1253 std::unique_ptr<MEM_ROOT>, std::unique_ptr<Xa_state_list::allocator>,
1254 std::unique_ptr<Xa_state_list::list>, std::unique_ptr<Xa_state_list>>;
1255
1256 /**
1257 Class constructor.
1258
1259 @param populated_by_tc The underlying list of XIDs and transaction
1260 states, after being populated by the transaction
1261 coodinator.
1262 */
1263 Xa_state_list(Xa_state_list::list &populated_by_tc);
1264 virtual ~Xa_state_list() = default;
1265
1266 /**
1267 Searches the underlying map to find an key that corresponds to the
1268 parameter.
1269
1270 @param to_find The XID to find within the underlying map.
1271
1272 @return Ha_recover_states::NOT_FOUND if the transaction wasn't found,
1273 the state of the transaction, otherwise.
1274 */
1275 enum_ha_recover_xa_state find(XID const &to_find);
1276 /**
1277 Adds a transaction and state to the underlying map. If the given XID
1278 already exists in the underlying map, the associated state changes according
1279 to the following rules:
1280
1281 - If the parameter state is `PREPARED_IN_SE` it means that the
1282 transaction didn't reach PREPARED_IN_TC, COMMIT or ROLLBACK for
1283 sure. In that case:
1284 . If other participants state is `COMMITTED`/`ROLLEDBACK`, it would
1285 mean that it's a state inherited from a previous execution with the
1286 same XID and we should set the state to `PREPARED_IN_SE`.
1287 . If other participants state is `PREPARED_IN_TC`/
1288 `COMMITTED_WITH_ONEPHASE` it means that the current participant
1289 didn't reach it but some other did so, keep the state as
1290 `PREPARED_IN_TC`/`COMMITTED_WITH_ONEPHASE`.
1291
1292 - If the parameter state is `PREPARED_IN_TC`, it means that other
1293 participants must have persisted either the PREPARE, the COMMIT or
1294 the ROLLBACK. In that case, keep whatever state is already there and
1295 ensure that is not `PREPARED_IN_SE`.
1296
1297 - If the parameter state is `COMMITTED_WITH_ONEPHASE`, `COMMITTED` or
1298 `ROLLEDBACK`, do nothing, only the active transaction coordinator has
1299 the ability, for now, to set the transaction state to those values.
1300
1301 @param xid The XID to be added (the key).
1302 @param xid The state to be added (the value).
1303
1304 @return The current value of the transaction state if the XID has
1305 already been added, Ha_recover_states::NOT_FOUND otherwise.
1306 */
1308 /**
1309 Factory like method to instantiate all the infra-structure needed to
1310 create an `Xa_state_list`. Since such infra-structuer is dependent on
1311 `MEM_ROOT` and `Mem_root_allocator`, the method returns a tuple
1312 containing unique pointers to all 4 objects needed: MEM_ROOT;
1313 Mem_root_allocator; Xa_state_list::list; Xa_state_list.
1314
1315 @return An std::tuple containing unique pointers to all 4 objects
1316 needed: MEM_ROOT; Mem_root_allocator; Xa_state_list::list;
1317 Xa_state_list.
1318 */
1320
1321 private:
1322 /** The underlying map holding the trx and states*/
1324};
1325
1326/* handlerton methods */
1327
1328/**
1329 close_connection is only called if
1330 thd->ha_data[xxx_hton.slot] is non-zero, so even if you don't need
1331 this storage area - set it to something, so that MySQL would know
1332 this storage engine was accessed in this connection
1333*/
1334typedef int (*close_connection_t)(handlerton *hton, THD *thd);
1335
1336/** Terminate connection/statement notification. */
1337typedef void (*kill_connection_t)(handlerton *hton, THD *thd);
1338
1339/**
1340 Shut down all storage engine background tasks that might access
1341 the data dictionary, before the main shutdown.
1342*/
1343typedef void (*pre_dd_shutdown_t)(handlerton *hton);
1344
1345/**
1346 sv points to a storage area, that was earlier passed
1347 to the savepoint_set call
1348*/
1349typedef int (*savepoint_rollback_t)(handlerton *hton, THD *thd, void *sv);
1350
1351/**
1352 sv points to an uninitialized storage area of requested size
1353 (see savepoint_offset description)
1354*/
1355typedef int (*savepoint_set_t)(handlerton *hton, THD *thd, void *sv);
1356
1357/**
1358 Check if storage engine allows to release metadata locks which were
1359 acquired after the savepoint if rollback to savepoint is done.
1360 @return true - If it is safe to release MDL locks.
1361 false - If it is not.
1362*/
1364 THD *thd);
1365
1366typedef int (*savepoint_release_t)(handlerton *hton, THD *thd, void *sv);
1367
1368/**
1369 'all' is true if it's a real commit, that makes persistent changes
1370 'all' is false if it's not in fact a commit but an end of the
1371 statement that is part of the transaction.
1372 NOTE 'all' is also false in auto-commit mode where 'end of statement'
1373 and 'real commit' mean the same event.
1374*/
1375typedef int (*commit_t)(handlerton *hton, THD *thd, bool all);
1376
1377typedef int (*rollback_t)(handlerton *hton, THD *thd, bool all);
1378
1379typedef int (*prepare_t)(handlerton *hton, THD *thd, bool all);
1380
1381typedef int (*recover_t)(handlerton *hton, XA_recover_txn *xid_list, uint len,
1383/**
1384 Retrieves information about externally coordinated transactions for which
1385 the two-phase prepare was finished and transactions were prepared in the
1386 server TC.
1387 */
1389 Xa_state_list &xa_list);
1390/**
1391 Instructs the storage engine to mark the externally coordinated
1392 transactions held by the THD parameters as prepared in the server TC.
1393 */
1394using set_prepared_in_tc_t = int (*)(handlerton *hton, THD *thd);
1395
1396/** X/Open XA distributed transaction status codes */
1398 /**
1399 normal execution
1400 */
1402
1403 /**
1404 asynchronous operation already outstanding
1405 */
1407
1408 /**
1409 a resource manager error occurred in the transaction branch
1410 */
1412
1413 /**
1414 the XID is not valid
1415 */
1417
1418 /**
1419 invalid arguments were given
1420 */
1422
1423 /**
1424 routine invoked in an improper context
1425 */
1427
1428 /**
1429 resource manager unavailable
1430 */
1432
1433 /**
1434 the XID already exists
1435 */
1437
1438 /**
1439 resource manager doing work outside transaction
1440 */
1441 XAER_OUTSIDE = -9
1443
1445
1447
1448/**
1449 Instructs the storage engine to mark the externally coordinated
1450 transactions identified by the XID parameters as prepared in the server
1451 TC.
1452 */
1454 XID *xid);
1455
1456/**
1457 Create handler object for the table in the storage engine.
1458
1459 @param hton Handlerton object for the storage engine.
1460 @param table TABLE_SHARE for the table, can be NULL if caller
1461 didn't perform full-blown open of table definition.
1462 @param partitioned Indicates whether table is partitioned.
1463 @param mem_root Memory root to be used for allocating handler
1464 object.
1465*/
1466typedef handler *(*create_t)(handlerton *hton, TABLE_SHARE *table,
1467 bool partitioned, MEM_ROOT *mem_root);
1468
1469typedef void (*drop_database_t)(handlerton *hton, char *path);
1470
1471typedef int (*panic_t)(handlerton *hton, enum ha_panic_function flag);
1472
1473typedef int (*start_consistent_snapshot_t)(handlerton *hton, THD *thd);
1474
1475/**
1476 Flush the log(s) of storage engine(s).
1477
1478 @param hton Handlerton of storage engine.
1479 @param binlog_group_flush true if we got invoked by binlog group
1480 commit during flush stage, false in other cases.
1481 @retval false Succeed
1482 @retval true Error
1483*/
1484typedef bool (*flush_logs_t)(handlerton *hton, bool binlog_group_flush);
1485
1486typedef bool (*show_status_t)(handlerton *hton, THD *thd, stat_print_fn *print,
1487 enum ha_stat_type stat);
1488
1489/**
1490 The flag values are defined in sql_partition.h.
1491 If this function is set, then it implies that the handler supports
1492 partitioned tables.
1493 If this function exists, then handler::get_partition_handler must also be
1494 implemented.
1495*/
1497
1498/**
1499 SE specific validation of the tablespace name.
1500
1501 This function will ask the relevant SE whether the submitted tablespace
1502 name is valid.
1503
1504 @param ts_cmd Purpose of usage - is this tablespace DDL?
1505 @param tablespace_name Name of the tablespace.
1506
1507 @return Tablespace name validity.
1508 @retval Whether the tablespace name is valid.
1509*/
1511 const char *tablespace_name);
1512
1513/**
1514 Get the tablespace name from the SE for the given schema and table.
1515
1516 @param thd Thread context.
1517 @param db_name Name of the relevant schema.
1518 @param table_name Name of the relevant table.
1519 @param [out] tablespace_name Name of the tablespace containing the table.
1520
1521 @return Operation status.
1522 @retval == 0 Success.
1523 @retval != 0 Error (handler error code returned).
1524*/
1527 LEX_CSTRING *tablespace_name);
1528
1529/**
1530 Create/drop or alter tablespace in the storage engine.
1531
1532 @param hton Hadlerton of the SE.
1533 @param thd Thread context.
1534 @param ts_info Description of tablespace and specific
1535 operation on it.
1536 @param old_ts_def dd::Tablespace object describing old version
1537 of tablespace.
1538 @param [in,out] new_ts_def dd::Tablespace object describing new version
1539 of tablespace. Engines which support atomic DDL
1540 can adjust this object. The updated information
1541 will be saved to the data-dictionary.
1542
1543 @return Operation status.
1544 @retval == 0 Success.
1545 @retval != 0 Error (handler error code returned).
1546*/
1547typedef int (*alter_tablespace_t)(handlerton *hton, THD *thd,
1548 st_alter_tablespace *ts_info,
1549 const dd::Tablespace *old_ts_def,
1550 dd::Tablespace *new_ts_def);
1551
1552/**
1553 SE interface for getting tablespace extension.
1554 @return Extension of tablespace datafile name.
1555*/
1556typedef const char *(*get_tablespace_filename_ext_t)();
1557
1558/**
1559 Get the tablespace data from SE and insert it into Data dictionary
1560
1561 @param thd Thread context
1562
1563 @return Operation status.
1564 @retval == 0 Success.
1565 @retval != 0 Error (handler error code returned)
1566*/
1567typedef int (*upgrade_tablespace_t)(THD *thd);
1568
1569/**
1570 Get the tablespace data from SE and insert it into Data dictionary
1571
1572 @param[in] tablespace tablespace object
1573
1574 @return Operation status.
1575 @retval == 0 Success.
1576 @retval != 0 Error (handler error code returned)
1577*/
1578typedef bool (*upgrade_space_version_t)(dd::Tablespace *tablespace);
1579
1580/**
1581 Finish upgrade process inside storage engines.
1582 This includes resetting flags to indicate upgrade process
1583 and cleanup after upgrade.
1584
1585 @param thd Thread context
1586 @param failed_upgrade True if the upgrade failed.
1587
1588 @return Operation status.
1589 @retval == 0 Success.
1590 @retval != 0 Error (handler error code returned)
1591*/
1592typedef int (*finish_upgrade_t)(THD *thd, bool failed_upgrade);
1593
1594/**
1595 Upgrade logs after the checkpoint from where upgrade
1596 process can only roll forward.
1597
1598 @param thd Thread context
1599
1600 @return Operation status.
1601 @retval == 0 Success.
1602 @retval != 0 Error (handler error code returned)
1603*/
1604typedef int (*upgrade_logs_t)(THD *thd);
1605
1613};
1614
1615/**
1616 Get the tablespace type from the SE.
1617
1618 @param[in] space tablespace object
1619 @param[out] space_type type of space
1620
1621 @return Operation status.
1622 @retval false on success and true for failure.
1623*/
1624typedef bool (*get_tablespace_type_t)(const dd::Tablespace &space,
1625 Tablespace_type *space_type);
1626
1627/**
1628 Get the tablespace type given the name, from the SE.
1629
1630 @param[in] tablespace_name tablespace name
1631 @param[out] space_type type of space
1632
1633 @return Operation status.
1634 @retval false on success and true for failure.
1635*/
1636typedef bool (*get_tablespace_type_by_name_t)(const char *tablespace_name,
1637 Tablespace_type *space_type);
1638
1639typedef int (*fill_is_table_t)(handlerton *hton, THD *thd, TABLE_LIST *tables,
1640 class Item *cond, enum enum_schema_tables);
1641
1642typedef int (*binlog_func_t)(handlerton *hton, THD *thd, enum_binlog_func fn,
1643 void *arg);
1644
1645typedef void (*binlog_log_query_t)(handlerton *hton, THD *thd,
1646 enum_binlog_command binlog_command,
1647 const char *query, uint query_length,
1648 const char *db, const char *table_name);
1649
1650typedef void (*acl_notify_t)(THD *thd,
1651 const class Acl_change_notification *notice);
1652
1653typedef int (*discover_t)(handlerton *hton, THD *thd, const char *db,
1654 const char *name, uchar **frmblob, size_t *frmlen);
1655
1656typedef int (*find_files_t)(handlerton *hton, THD *thd, const char *db,
1657 const char *path, const char *wild, bool dir,
1658 List<LEX_STRING> *files);
1659
1660typedef int (*table_exists_in_engine_t)(handlerton *hton, THD *thd,
1661 const char *db, const char *name);
1662
1663/**
1664 Let storage engine inspect the query Accesspath and pick whatever
1665 it like for being pushed down to the engine. (Join, conditions, ..)
1666
1667 The handler implementation should itself keep track of what it 'pushed',
1668 such that later calls to the handlers access methods should
1669 activate the pushed parts of the execution plan on the storage
1670 engines.
1671
1672 @param thd Thread context
1673 @param query The AccessPath for the entire query.
1674 @param join The JOIN to be pushed
1675
1676 @returns
1677 0 on success
1678 error otherwise
1679*/
1680using push_to_engine_t = int (*)(THD *thd, AccessPath *query, JOIN *);
1681
1682/**
1683 Check if the given db.tablename is a system table for this SE.
1684
1685 @param db Database name to check.
1686 @param table_name table name to check.
1687 @param is_sql_layer_system_table if the supplied db.table_name is a SQL
1688 layer system table.
1689
1690 @see example_is_supported_system_table in ha_example.cc
1691
1692 is_sql_layer_system_table is supplied to make more efficient
1693 checks possible for SEs that support all SQL layer tables.
1694
1695 This interface is optional, so every SE need not implement it.
1696*/
1697typedef bool (*is_supported_system_table_t)(const char *db,
1698 const char *table_name,
1699 bool is_sql_layer_system_table);
1700
1701/**
1702 Create SDI in a tablespace. This API should be used when upgrading
1703 a tablespace with no SDI or after invoking sdi_drop().
1704 @param[in] tablespace tablespace object
1705 @retval false success
1706 @retval true failure
1707*/
1708typedef bool (*sdi_create_t)(dd::Tablespace *tablespace);
1709
1710/**
1711 Drop SDI in a tablespace. This API should be used only when
1712 SDI is corrupted.
1713 @param[in] tablespace tablespace object
1714 @retval false success
1715 @retval true failure
1716*/
1717typedef bool (*sdi_drop_t)(dd::Tablespace *tablespace);
1718
1719/**
1720 Get the SDI keys in a tablespace into vector.
1721 @param[in] tablespace tablespace object
1722 @param[in,out] vector vector of SDI Keys
1723 @retval false success
1724 @retval true failure
1725*/
1726typedef bool (*sdi_get_keys_t)(const dd::Tablespace &tablespace,
1728
1729/**
1730 Retrieve SDI for a given SDI key.
1731
1732 Since the caller of this api will not know the SDI length, SDI retrieval
1733 should be done in the following way.
1734
1735 i. Allocate initial memory of some size (Lets say 64KB)
1736 ii. Pass the allocated memory to the below api.
1737 iii. If passed buffer is sufficient, sdi_get_by_id() copies the sdi
1738 to the buffer passed and returns success, else sdi_len is modified
1739 with the actual length of the SDI (and returns false on failure).
1740 For genuine errors, sdi_len is returned as UINT64_MAX
1741 iv. If sdi_len != UINT64_MAX, retry the call after allocating the memory
1742 of sdi_len
1743 v. Free the memory after using SDI (responsibility of caller)
1744
1745 @param[in] tablespace tablespace object
1746 @param[in] sdi_key SDI key to uniquely identify SDI obj
1747 @param[in,out] sdi SDI retrieved from tablespace
1748 A non-null pointer must be passed in
1749 @param[in,out] sdi_len in: length of the memory allocated
1750 out: actual length of SDI
1751 @retval false success
1752 @retval true failure
1753*/
1754typedef bool (*sdi_get_t)(const dd::Tablespace &tablespace,
1755 const sdi_key_t *sdi_key, void *sdi, uint64 *sdi_len);
1756
1757/**
1758 Insert/Update SDI for a given SDI key.
1759 @param[in] hton handlerton object
1760 @param[in] tablespace tablespace object
1761 @param[in] table table object
1762 @param[in] sdi_key SDI key to uniquely identify SDI obj
1763 @param[in] sdi SDI to write into the tablespace
1764 @param[in] sdi_len length of SDI BLOB returned
1765 @retval false success
1766 @retval true failure, my_error() should be called
1767 by SE
1768*/
1769typedef bool (*sdi_set_t)(handlerton *hton, const dd::Tablespace &tablespace,
1770 const dd::Table *table, const sdi_key_t *sdi_key,
1771 const void *sdi, uint64 sdi_len);
1772
1773/**
1774 Delete SDI for a given SDI key.
1775 @param[in] tablespace tablespace object
1776 @param[in] table table object
1777 @param[in] sdi_key SDI key to uniquely identify SDI obj
1778 @retval false success
1779 @retval true failure, my_error() should be called
1780 by SE
1781*/
1782typedef bool (*sdi_delete_t)(const dd::Tablespace &tablespace,
1783 const dd::Table *table, const sdi_key_t *sdi_key);
1784
1785/**
1786 Check if the DDSE is started in a way that leaves thd DD being read only.
1787
1788 @retval true The data dictionary can only be read.
1789 @retval false The data dictionary can be read and written.
1790 */
1791typedef bool (*is_dict_readonly_t)();
1792
1793/**
1794 Drop all temporary tables which have been left from previous server
1795 run belonging to this SE. Used on server start-up.
1796
1797 @param[in] hton Handlerton for storage engine.
1798 @param[in] thd Thread context.
1799 @param[in,out] files List of files in directories for temporary files
1800 which match tmp_file_prefix and thus can belong to
1801 temporary tables (but not necessarily in this SE).
1802 It is recommended to remove file from the list if
1803 SE recognizes it as belonging to temporary table
1804 in this SE and deletes it.
1805*/
1806typedef bool (*rm_tmp_tables_t)(handlerton *hton, THD *thd,
1807 List<LEX_STRING> *files);
1808
1809/**
1810 Retrieve cost constants to be used for this storage engine.
1811
1812 A storage engine that wants to provide its own cost constants to
1813 be used in the optimizer cost model, should implement this function.
1814 The server will call this function to get a cost constant object
1815 that will be used for tables stored in this storage engine instead
1816 of using the default cost constants.
1817
1818 Life cycle for the cost constant object: The storage engine must
1819 allocate the cost constant object on the heap. After the function
1820 returns, the server takes over the ownership of this object.
1821 The server will eventually delete the object by calling delete.
1822
1823 @note In the initial version the storage_category parameter will
1824 not be used. The only valid value this will have is DEFAULT_STORAGE_CLASS
1825 (see declaration in opt_costconstants.h).
1826
1827 @param storage_category the storage type that the cost constants will
1828 be used for
1829
1830 @return a pointer to the cost constant object, if NULL is returned
1831 the default cost constants will be used
1832*/
1833typedef SE_cost_constants *(*get_cost_constants_t)(uint storage_category);
1834
1835/**
1836 @param[in,out] thd pointer to THD
1837 @param[in] new_trx_arg pointer to replacement transaction
1838 @param[out] ptr_trx_arg double pointer to being replaced transaction
1839
1840 Associated with THD engine's native transaction is replaced
1841 with @c new_trx_arg. The old value is returned through a buffer if non-null
1842 pointer is provided with @c ptr_trx_arg.
1843 The method is adapted by XA start and XA prepare handlers to
1844 handle XA transaction that is logged as two parts by slave applier.
1845
1846 This interface concerns engines that are aware of XA transaction.
1847*/
1848typedef void (*replace_native_transaction_in_thd_t)(THD *thd, void *new_trx_arg,
1849 void **ptr_trx_arg);
1850
1851/** Mode for initializing the data dictionary. */
1853 DICT_INIT_CREATE_FILES, ///< Create all required SE files
1854 DICT_INIT_CHECK_FILES, ///< Verify existence of expected files
1855 DICT_INIT_UPGRADE_57_FILES, ///< Used for upgrade from mysql-5.7
1856 DICT_INIT_IGNORE_FILES ///< Don't care about files at all
1858
1859/**
1860 Initialize the SE for being used to store the DD tables. Create
1861 the required files according to the dict_init_mode. Create strings
1862 representing the required DDSE tables, i.e., tables that the DDSE
1863 expects to exist in the DD, and add them to the appropriate out
1864 parameter.
1865
1866 @note There are two variants of this function type, one is to be
1867 used by the DDSE, and has a different type of output parameters
1868 because the SQL layer needs more information about the DDSE tables
1869 in order to support upgrade.
1870
1871 @param dict_init_mode How to initialize files
1872 @param version Target DD version if a new
1873 server is being installed.
1874 0 if restarting an existing
1875 server.
1876 @param [out] DDSE_tables List of SQL DDL statements
1877 for creating DD tables that
1878 are needed by the DDSE.
1879 @param [out] DDSE_tablespaces List of meta data for predefined
1880 tablespaces created by the DDSE.
1881
1882 @retval true An error occurred.
1883 @retval false Success - no errors.
1884 */
1885
1886typedef bool (*dict_init_t)(dict_init_mode_t dict_init_mode, uint version,
1887 List<const Plugin_table> *DDSE_tables,
1888 List<const Plugin_tablespace> *DDSE_tablespaces);
1889
1890typedef bool (*ddse_dict_init_t)(
1891 dict_init_mode_t dict_init_mode, uint version,
1892 List<const dd::Object_table> *DDSE_tables,
1893 List<const Plugin_tablespace> *DDSE_tablespaces);
1894
1895/**
1896 Initialize the set of hard coded DD table ids.
1897*/
1898typedef void (*dict_register_dd_table_id_t)(dd::Object_id hard_coded_tables);
1899
1900/**
1901 Invalidate an entry in the local dictionary cache.
1902
1903 Needed during bootstrap to make sure the contents in the DDSE
1904 dictionary cache is in sync with the global DD.
1905
1906 @param schema_name Schema name.
1907 @param table_name Table name.
1908 */
1909
1910typedef void (*dict_cache_reset_t)(const char *schema_name,
1911 const char *table_name);
1912
1913/**
1914 Invalidate all table and tablespace entries in the local dictionary cache.
1915
1916 Needed for recovery during server restart.
1917 */
1918
1920
1921/** Mode for data dictionary recovery. */
1923 DICT_RECOVERY_INITIALIZE_SERVER, ///< First start of a new server
1924 DICT_RECOVERY_INITIALIZE_TABLESPACES, ///< First start, create tablespaces
1925 DICT_RECOVERY_RESTART_SERVER ///< Restart of an existing server
1927
1928/**
1929 Do recovery in the DDSE as part of initializing the data dictionary.
1930 The dict_recovery_mode indicates what kind of recovery should be
1931 done.
1932
1933 @param dict_recovery_mode How to do recovery
1934 @param version Target DD version if a new
1935 server is being installed.
1936 Actual DD version if restarting
1937 an existing server.
1938
1939 @retval true An error occurred.
1940 @retval false Success - no errors.
1941 */
1942
1943typedef bool (*dict_recover_t)(dict_recovery_mode_t dict_recovery_mode,
1944 uint version);
1945
1946/**
1947 Get the server version id stored in the header of the
1948 dictionary tablespace.
1949
1950 @param [out] version Version number from the DD
1951 tablespace header.
1952
1953 @retval Operation outcome, false if no error, otherwise true.
1954*/
1956
1957/**
1958 Store the current server version number into the
1959 header of the dictionary tablespace.
1960
1961 @retval Operation outcome, false if no error, otherwise true.
1962*/
1964
1965/**
1966 Notify/get permission from storage engine before acquisition or after
1967 release of exclusive metadata lock on object represented by key.
1968
1969 @param thd Thread context.
1970 @param mdl_key MDL key identifying object on which exclusive
1971 lock is to be acquired/was released.
1972 @param notification_type Indicates whether this is pre-acquire or
1973 post-release notification.
1974 @param victimized 'true' if locking failed as we were selected
1975 as a victim in order to avoid possible deadlocks.
1976
1977 @note Notification is done only for objects from TABLESPACE, SCHEMA,
1978 TABLE, FUNCTION, PROCEDURE, TRIGGER and EVENT namespaces.
1979
1980 @note Problems during notification are to be reported as warnings, MDL
1981 subsystem will report generic error if pre-acquire notification
1982 fails/SE refuses lock acquisition.
1983 @note Return value is ignored/error is not reported in case of
1984 post-release notification.
1985
1986 @note In some cases post-release notification might happen even if
1987 there were no prior pre-acquire notification. For example,
1988 when SE was loaded after exclusive lock acquisition, or when
1989 we need notify SEs which permitted lock acquisition that it
1990 didn't happen because one of SEs didn't allow it (in such case
1991 we will do post-release notification for all SEs for simplicity).
1992
1993 @return False - if notification was successful/lock can be acquired,
1994 True - if it has failed/lock should not be acquired.
1995*/
1996typedef bool (*notify_exclusive_mdl_t)(THD *thd, const MDL_key *mdl_key,
1997 ha_notification_type notification_type,
1998 bool *victimized);
1999
2000/**
2001 Notify/get permission from storage engine before or after execution of
2002 ALTER TABLE operation on the table identified by the MDL key.
2003
2004 @param thd Thread context.
2005 @param mdl_key MDL key identifying table which is going to be
2006 or was ALTERed.
2007 @param notification_type Indicates whether this is pre-ALTER TABLE or
2008 post-ALTER TABLE notification.
2009
2010 @note This hook is necessary because for ALTER TABLE upgrade to X
2011 metadata lock happens fairly late during the execution process,
2012 so it can be expensive to abort ALTER TABLE operation at this
2013 stage by returning failure from notify_exclusive_mdl() hook.
2014
2015 @note This hook follows the same error reporting convention as
2016 @see notify_exclusive_mdl().
2017
2018 @note Similarly to notify_exclusive_mdl() in some cases post-ALTER
2019 notification might happen even if there were no prior pre-ALTER
2020 notification.
2021
2022 @note Post-ALTER notification can happen before post-release notification
2023 for exclusive metadata lock acquired by this ALTER TABLE.
2024
2025 @return False - if notification was successful/ALTER TABLE can proceed.
2026 True - if it has failed/ALTER TABLE should be aborted.
2027*/
2028typedef bool (*notify_alter_table_t)(THD *thd, const MDL_key *mdl_key,
2029 ha_notification_type notification_type);
2030
2031/**
2032 @brief
2033 Initiate master key rotation
2034
2035 @returns false on success,
2036 true on failure
2037*/
2039
2040/**
2041 @brief
2042 Enable or Disable SE write ahead logging.
2043
2044 @param[in] thd server thread handle
2045 @param[in] enable enable/disable redo logging
2046
2047 @return true iff failed.
2048*/
2049typedef bool (*redo_log_set_state_t)(THD *thd, bool enable);
2050
2051/**
2052 @brief
2053 Retrieve ha_statistics from SE.
2054
2055 @param db_name Name of schema
2056 @param table_name Name of table
2057 @param se_private_id SE private id of the table.
2058 @param ts_se_private_data Tablespace SE private data.
2059 @param tbl_se_private_data Table SE private data.
2060 @param flags Type of statistics to retrieve.
2061 @param[out] stats Contains statistics read from SE.
2062
2063 @note Handlers that implement this callback/API should adhere
2064 to servers expectation that, the implementation would invoke
2065 my_error() before returning 'true'/failure from this function.
2066
2067 @returns false on success,
2068 true on failure
2069*/
2071 const char *db_name, const char *table_name, dd::Object_id se_private_id,
2072 const dd::Properties &ts_se_private_data,
2073 const dd::Properties &tbl_se_private_data, uint flags,
2075
2076/**
2077 @brief
2078 Retrieve index column cardinality from SE.
2079
2080 @param db_name Name of schema
2081 @param table_name Name of table
2082 @param index_name Name of index
2083 @param index_ordinal_position Position of index.
2084 @param column_ordinal_position Position of column in index.
2085 @param se_private_id SE private id of the table.
2086 @param[out] cardinality cardinality being returned by SE.
2087
2088 @note Handlers that implement this callback/API should adhere
2089 to servers expectation that, the implementation would invoke
2090 my_error() before returning 'true'/failure from this function.
2091
2092 @returns false on success,
2093 true on failure
2094*/
2096 const char *db_name, const char *table_name, const char *index_name,
2097 uint index_ordinal_position, uint column_ordinal_position,
2098 dd::Object_id se_private_id, ulonglong *cardinality);
2099
2100/**
2101 Retrieve ha_tablespace_statistics from SE.
2102
2103 @param tablespace_name Tablespace_name
2104 @param file_name Tablespace file name.
2105 @param ts_se_private_data Tablespace SE private data.
2106 @param[out] stats Contains tablespace
2107 statistics read from SE.
2108
2109 @note Handlers that implement this callback/API should adhere
2110 to servers expectation that, the implementation would invoke
2111 my_error() before returning 'true'/failure from this function.
2112
2113 @returns false on success, true on failure
2114*/
2116 const char *tablespace_name, const char *file_name,
2117 const dd::Properties &ts_se_private_data, ha_tablespace_statistics *stats);
2118
2119/* Database physical clone interfaces */
2120
2121/** Get capability flags for clone operation
2122@param[out] flags capability flag */
2124
2125/** Begin copy from source database
2126@param[in] hton handlerton for SE
2127@param[in] thd server thread handle
2128@param[in,out] loc locator
2129@param[in,out] loc_len locator length
2130@param[out] task_id task identifier
2131@param[in] type clone type
2132@param[in] mode mode for starting clone
2133@return error code */
2134using Clone_begin_t = int (*)(handlerton *hton, THD *thd, const uchar *&loc,
2135 uint &loc_len, uint &task_id, Ha_clone_type type,
2137
2138/** Copy data from source database in chunks via callback
2139@param[in] hton handlerton for SE
2140@param[in] thd server thread handle
2141@param[in] loc locator
2142@param[in] loc_len locator length in bytes
2143@param[in] task_id task identifier
2144@param[in] cbk callback interface for sending data
2145@return error code */
2146using Clone_copy_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2147 uint loc_len, uint task_id, Ha_clone_cbk *cbk);
2148
2149/** Acknowledge data transfer to source database
2150@param[in] hton handlerton for SE
2151@param[in] thd server thread handle
2152@param[in] loc locator
2153@param[in] loc_len locator length in bytes
2154@param[in] task_id task identifier
2155@param[in] in_err inform any error occurred
2156@param[in] cbk callback interface
2157@return error code */
2158using Clone_ack_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2159 uint loc_len, uint task_id, int in_err,
2160 Ha_clone_cbk *cbk);
2161
2162/** End copy from source database
2163@param[in] hton handlerton for SE
2164@param[in] thd server thread handle
2165@param[in] loc locator
2166@param[in] loc_len locator length in bytes
2167@param[in] task_id task identifier
2168@param[in] in_err error code when ending after error
2169@return error code */
2170using Clone_end_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2171 uint loc_len, uint task_id, int in_err);
2172
2173/** Begin apply to destination database
2174@param[in] hton handlerton for SE
2175@param[in] thd server thread handle
2176@param[in,out] loc locator
2177@param[in,out] loc_len locator length
2178@param[in] task_id task identifier
2179@param[in] mode mode for starting clone
2180@param[in] data_dir target data directory
2181@return error code */
2182using Clone_apply_begin_t = int (*)(handlerton *hton, THD *thd,
2183 const uchar *&loc, uint &loc_len,
2184 uint &task_id, Ha_clone_mode mode,
2185 const char *data_dir);
2186
2187/** Apply data to destination database in chunks via callback
2188@param[in] hton handlerton for SE
2189@param[in] thd server thread handle
2190@param[in] loc locator
2191@param[in] loc_len locator length in bytes
2192@param[in] task_id task identifier
2193@param[in] in_err inform any error occurred
2194@param[in] cbk callback interface for receiving data
2195@return error code */
2196using Clone_apply_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2197 uint loc_len, uint task_id, int in_err,
2198 Ha_clone_cbk *cbk);
2199
2200/** End apply to destination database
2201@param[in] hton handlerton for SE
2202@param[in] thd server thread handle
2203@param[in] loc locator
2204@param[in] loc_len locator length in bytes
2205@param[in] task_id task identifier
2206@param[in] in_err error code when ending after error
2207@return error code */
2208using Clone_apply_end_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2209 uint loc_len, uint task_id, int in_err);
2210
2212 /* Get clone capabilities of an SE */
2214
2215 /* Interfaces to copy data. */
2220
2221 /* Interfaces to apply data. */
2225};
2226
2227/**
2228 Perform post-commit/rollback cleanup after DDL statement (e.g. in
2229 case of DROP TABLES really remove table files from disk).
2230
2231 @note This hook will be invoked after DDL commit or rollback only
2232 for storage engines supporting atomic DDL.
2233
2234 @note Problems during execution of this method should be reported to
2235 error log and as warnings/notes to user. Since this method is
2236 called after successful commit of the statement we can't fail
2237 statement with error.
2238*/
2239typedef void (*post_ddl_t)(THD *thd);
2240
2241/**
2242 Perform SE-specific cleanup after recovery of transactions.
2243
2244 @note Particularly SEs supporting atomic DDL can use this call
2245 to perform post-DDL actions for DDL statements which were
2246 committed or rolled back during recovery stage.
2247*/
2248typedef void (*post_recover_t)(void);
2249
2250/**
2251 Lock a handlerton (resource) log to collect log information.
2252*/
2253
2254typedef bool (*lock_hton_log_t)(handlerton *hton);
2255
2256/**
2257 Unlock a handlerton (resource) log after collecting log information.
2258*/
2259
2260typedef bool (*unlock_hton_log_t)(handlerton *hton);
2261
2262/**
2263 Collect a handlerton (resource) log information.
2264*/
2265
2266typedef bool (*collect_hton_log_info_t)(handlerton *hton, Json_dom *json);
2267
2268/**
2269 Check SE considers types of child and parent columns in foreign key
2270 to be compatible.
2271
2272 @param child_column_type Child column type description.
2273 @param parent_column_type Parent column type description.
2274 @param check_charsets Indicates whether we need to check
2275 that charsets of string columns
2276 match. Which is true in most cases.
2277
2278 @returns True if types are compatible, False if not.
2279*/
2280
2282 const Ha_fk_column_type *child_column_type,
2283 const Ha_fk_column_type *parent_column_type, bool check_charsets);
2284
2285typedef bool (*is_reserved_db_name_t)(handlerton *hton, const char *name);
2286
2287/**
2288 Prepare the secondary engine for executing a statement. This function is
2289 called right after the secondary engine TABLE objects have been opened by
2290 open_secondary_engine_tables(), before the statement is optimized and
2291 executed. Secondary engines will typically create a context object in this
2292 function, which they can use to store state that is needed during the
2293 optimization and execution phases.
2294
2295 @param thd thread context
2296 @param lex the statement to execute
2297 @return true on error, false on success
2298*/
2299using prepare_secondary_engine_t = bool (*)(THD *thd, LEX *lex);
2300
2301/**
2302 Optimize a statement for execution on a secondary storage engine. This
2303 function is called when the optimization of a statement has completed, just
2304 before the statement is executed. Secondary engines can use this function to
2305 apply engine-specific optimizations to the execution plan. They can also
2306 reject executing the query by raising an error, in which case the query will
2307 be reprepared and executed by the primary storage engine.
2308
2309 @param thd thread context
2310 @param lex the statement being optimized
2311 @return true on error, false on success
2312*/
2313using optimize_secondary_engine_t = bool (*)(THD *thd, LEX *lex);
2314
2315/**
2316 Compares the cost of two join plans in the secondary storage engine. The cost
2317 of the current candidate is compared with the cost of the best plan seen so
2318 far.
2319
2320 @param thd thread context
2321 @param join the candidate plan to evaluate
2322 @param optimizer_cost the cost estimate calculated by the optimizer
2323 @param[out] use_best_so_far true if the optimizer should stop searching for
2324 a better plan and use the best plan it has seen so far
2325 @param[out] cheaper true if the candidate is the best plan seen so far for
2326 this JOIN (must be true if it is the first plan seen),
2327 false otherwise
2328 @param[out] secondary_engine_cost the cost estimated by the secondary engine
2329
2330 @return false on success, or true if an error has been raised
2331*/
2332using compare_secondary_engine_cost_t = bool (*)(THD *thd, const JOIN &join,
2333 double optimizer_cost,
2334 bool *use_best_so_far,
2335 bool *cheaper,
2336 double *secondary_engine_cost);
2337
2338/**
2339 Evaluates the cost of executing the given access path in this secondary
2340 storage engine, and potentially modifies the cost estimates that are in the
2341 access path. This function is only called from the hypergraph join optimizer.
2342
2343 The function is called on every access path that the join optimizer might
2344 compare to an alternative access path. This includes both paths that represent
2345 complete execution plans and paths that represent partial plans. It is not
2346 guaranteed to be called on every child path. For example, if GROUP BY is done
2347 by sorting first and then aggregating the sorted results, the function will
2348 only be called on the aggregation path, and not on the sort path, because only
2349 the aggregation path will be compared to other paths.
2350
2351 The secondary engine is allowed to modify the estimates in the access path to
2352 better match the costs of the access path in the secondary engine. It can
2353 change any of the following AccessPath members:
2354
2355 - init_once_cost
2356 - init_cost
2357 - cost
2358 - cost_before_filter
2359 - num_output_rows
2360 - num_output_rows_before_filter
2361 - secondary_engine_data
2362
2363 Any other members should be left unchanged. The AccessPath must be in an
2364 internally consistent state when the function returns, and satisfy invariants
2365 expected by the hypergraph join optimizer, such as:
2366
2367 - init_cost <= cost_before_filter <= cost
2368 - num_output_rows <= num_output_rows_before_filter
2369
2370 The secondary engine can also reject an access path altogether, by returning
2371 true, in which case the join optimizer will not use that path in the final
2372 plan. Since the secondary engine can reject any partial or complete plan, it
2373 is possible that the join optimizer does not find any valid plan that is
2374 accepted. In this case, the join optimizer will raise an error.
2375
2376 If the secondary encounters an error when evaluating the cost of the path, it
2377 can signal an error by calling my_error() and return true, in which case the
2378 join optimizer will not suggest any plan for the query.
2379
2380 @param thd The thread context.
2381 @param hypergraph The hypergraph that represents the search space.
2382 @param[in,out] access_path The AccessPath to evaluate.
2383
2384 @retval false on success.
2385 @retval true if the plan is to be rejected, or if an error was raised.
2386*/
2388 THD *thd, const JoinHypergraph &hypergraph, AccessPath *access_path);
2389
2390// Capabilities (bit flags) for secondary engines.
2391using SecondaryEngineFlags = uint64_t;
2395
2396 // If this flag is set, aggregation (GROUP BY and DISTINCT) do not require
2397 // ordered inputs and create unordered outputs. This is typically the case
2398 // if they are implemented using hash-based techniques.
2400};
2401
2402/// Creates an empty bitmap of access path types. This is the base
2403/// case for the function template with the same name below.
2404inline constexpr SecondaryEngineFlags MakeSecondaryEngineFlags() { return 0; }
2405
2406/// Creates a bitmap representing a set of access path types.
2407template <typename... Args>
2409 SecondaryEngineFlag flag1, Args... rest) {
2410 return (uint64_t{1} << static_cast<int>(flag1)) |
2411 MakeSecondaryEngineFlags(rest...);
2412}
2413
2414// FIXME: Temporary workaround to enable storage engine plugins to use the
2415// before_commit hook. Remove after WL#11320 has been completed.
2416typedef void (*se_before_commit_t)(void *arg);
2417
2418// FIXME: Temporary workaround to enable storage engine plugins to use the
2419// after_commit hook. Remove after WL#11320 has been completed.
2420typedef void (*se_after_commit_t)(void *arg);
2421
2422// FIXME: Temporary workaround to enable storage engine plugins to use the
2423// before_rollback hook. Remove after WL#11320 has been completed.
2424typedef void (*se_before_rollback_t)(void *arg);
2425
2426/*
2427 Page Tracking : interfaces to handlerton functions which starts/stops page
2428 tracking, and purges/fetches page tracking information.
2429*/
2430
2431/**
2432 Start page tracking.
2433
2434 @param[out] start_id SE specific sequence number [LSN for InnoDB]
2435 indicating when the tracking was started
2436
2437 @return Operation status.
2438 @retval 0 Success
2439 @retval other ER_* mysql error. Get error details from THD.
2440*/
2441using page_track_start_t = int (*)(uint64_t *start_id);
2442
2443/**
2444 Stop page tracking.
2445
2446 @param[out] stop_id SE specific sequence number [LSN for InnoDB]
2447 indicating when the tracking was stopped
2448
2449 @return Operation status.
2450 @retval 0 Success
2451 @retval other ER_* mysql error. Get error details from THD.
2452*/
2453using page_track_stop_t = int (*)(uint64_t *stop_id);
2454
2455/**
2456 Purge page tracking data.
2457
2458 @param[in,out] purge_id SE specific sequence number [LSN for InnoDB]
2459 initially indicating till where the data needs to be purged and finally
2460 updated to until where it was actually purged
2461
2462 @return Operation status.
2463 @retval 0 Success
2464 @retval other ER_* mysql error. Get error details from THD.
2465*/
2466using page_track_purge_t = int (*)(uint64_t *purge_id);
2467
2468/**
2469 Fetch tracked pages.
2470
2471 @param[in] cbk_func callback function return page IDs
2472 @param[in] cbk_ctx caller's context for callback
2473 @param[in,out] start_id SE specific sequence number [LSN for InnoDB] from
2474 where the pages tracked would be returned.
2475 @note The range might get expanded and the actual start_id used for the
2476 querying will be updated.
2477 @param[in,out] stop_id SE specific sequence number [LSN for InnoDB]
2478 until where the pages tracked would be returned.
2479 @note The range might get expanded and the actual stop_id used for the
2480 querying will be updated.
2481 @param[out] buffer allocated buffer to copy page IDs
2482 @param[in] buffer_len length of buffer in bytes
2483
2484 @return Operation status.
2485 @retval 0 Success
2486 @retval other ER_* mysql error. Get error details from THD.
2487*/
2489 void *cbk_ctx, uint64_t *start_id,
2490 uint64_t *stop_id,
2491 unsigned char *buffer,
2492 size_t buffer_len);
2493
2494/**
2495 Fetch approximate number of tracked pages in the given range.
2496
2497 @param[in,out] start_id SE specific sequence number [LSN for InnoDB] from
2498 where the pages tracked would be returned.
2499 @note the range might get expanded and the actual start_id used for the
2500 querying will be updated.
2501 @param[in,out] stop_id SE specific sequence number [LSN for InnoDB]
2502 until where the pages tracked would be returned.
2503 @note the range might get expanded and the actual stop_id used for the
2504 querying will be updated.
2505 @param[out] num_pages number of pages tracked
2506
2507 @return Operation status.
2508 @retval 0 Success
2509 @retval other ER_* mysql error. Get error details from THD.
2510*/
2511using page_track_get_num_page_ids_t = int (*)(uint64_t *start_id,
2512 uint64_t *stop_id,
2513 uint64_t *num_pages);
2514
2515/** Fetch the status of the page tracking system.
2516@param[out] status vector of a pair of (ID, bool) where ID is the
2517start/stop point and bool is true if the ID is a start point else false */
2519 void (*)(std::vector<std::pair<uint64_t, bool>> &status);
2520
2521/** Page track interface */
2529};
2530
2531/**
2532 handlerton is a singleton structure - one instance per storage engine -
2533 to provide access to storage engine functionality that works on the
2534 "global" level (unlike handler class that works on a per-table basis).
2535
2536 usually handlerton instance is defined statically in ha_xxx.cc as
2537
2538 static handlerton { ... } xxx_hton;
2539
2540 savepoint_*, prepare, recover, and *_by_xid pointers can be 0.
2541*/
2543 /**
2544 Historical marker for if the engine is available or not.
2545 */
2547
2548 /**
2549 Historical number used for frm file to determine the correct storage engine.
2550 This is going away and new engines will just use "name" for this.
2551 */
2553 /**
2554 Each storage engine has it's own memory area (actually a pointer)
2555 in the thd, for storing per-connection information.
2556 It is accessed as
2557
2558 thd->ha_data[xxx_hton.slot]
2559
2560 slot number is initialized by MySQL after xxx_init() is called.
2561 */
2563 /**
2564 To store per-savepoint data storage engine is provided with an area
2565 of a requested size (0 is ok here).
2566 savepoint_offset must be initialized statically to the size of
2567 the needed memory to store per-savepoint information.
2568 After xxx_init it is changed to be an offset to savepoint storage
2569 area and need not be used by storage engine.
2570 see binlog_hton and binlog_savepoint_set/rollback for an example.
2571 */
2573
2574 /* handlerton methods */
2575
2620
2621 /** Global handler flags. */
2623
2624 /*
2625 Those handlerton functions below are properly initialized at handler
2626 init.
2627 */
2628
2637
2638 /*
2639 APIs for retrieving Serialized Dictionary Information by tablespace id
2640 */
2641
2648
2649 /**
2650 Null-ended array of file extensions that exist for the storage engine.
2651 Used by frm_error() and the default handler::rename_table and delete_table
2652 methods in handler.cc.
2653
2654 For engines that have two file name extensions (separate meta/index file
2655 and data file), the order of elements is relevant. First element of engine
2656 file name extensions array should be meta/index file extension. Second
2657 element - data file extension. This order is assumed by
2658 prepare_for_repair() when REPAIR TABLE ... USE_FRM is issued.
2659
2660 For engines that don't have files, file_extensions is NULL.
2661
2662 Currently, the following alternatives are used:
2663 - file_extensions == NULL;
2664 - file_extensions[0] != NULL, file_extensions[1] == NULL;
2665 - file_extensions[0] != NULL, file_extensions[1] != NULL,
2666 file_extensions[2] == NULL;
2667 */
2668 const char **file_extensions;
2669
2678
2682
2685
2686 /** Clone data transfer interfaces */
2688
2689 /** Flag for Engine License. */
2691 /** Location for engines to keep personal structures. */
2692 void *data;
2693
2694 /*
2695 Log_resource functions that must be supported by storage engines
2696 with relevant log information to be collected.
2697 */
2701
2702 /** Flags describing details of foreign key support by storage engine. */
2704
2706
2707 /**
2708 Suffix for auto-generated foreign key names for tables using this storage
2709 engine. If such suffix is specified by SE then its generated foreign key
2710 names follow (table name)(SE-specific FK name suffix)(FK number) pattern.
2711 Length of such suffix should not exceed MAX_FK_NAME_SUFFIX_LENGTH bytes.
2712 If no suffix is specified then FK_NAME_DEFAULT_SUFFIX is used as
2713 default.
2714 */
2716
2717 /**
2718 Pointer to a function that prepares a secondary engine for executing a
2719 statement.
2720
2721 @see prepare_secondary_engine_t for function signature.
2722 */
2724
2725 /**
2726 Pointer to a function that optimizes the current statement for
2727 execution on the secondary storage engine represented by this
2728 handlerton.
2729
2730 @see optimize_secondary_engine_t for function signature.
2731 */
2733
2734 /**
2735 Pointer to a function that estimates the cost of executing a join in a
2736 secondary storage engine.
2737
2738 @see compare_secondary_engine_cost_t for function signature.
2739 */
2741
2742 /// Bitmap which contains the supported join types and other flags
2743 /// for a secondary storage engine when used with the hypergraph join
2744 /// optimizer. If it is empty, it means that the secondary engine
2745 /// does not support the hypergraph join optimizer.
2747
2748 /// Pointer to a function that evaluates the cost of executing an access path
2749 /// in a secondary storage engine.
2750 ///
2751 /// @see secondary_engine_modify_access_path_cost_t for function signature.
2754
2758
2759 /** Page tracking interface */
2761};
2762
2763/* Possible flags of a handlerton (there can be 32 of them) */
2764#define HTON_NO_FLAGS 0
2765#define HTON_CLOSE_CURSORS_AT_COMMIT (1 << 0)
2766#define HTON_ALTER_NOT_SUPPORTED (1 << 1) // Engine does not support alter
2767#define HTON_CAN_RECREATE (1 << 2) // Delete all is used for truncate
2768#define HTON_HIDDEN (1 << 3) // Engine does not appear in lists
2769/*
2770 Bit 4 was occupied by BDB-specific HTON_FLUSH_AFTER_RENAME flag and is no
2771 longer used.
2772*/
2773#define HTON_NOT_USER_SELECTABLE (1 << 5)
2774#define HTON_TEMPORARY_NOT_SUPPORTED \
2775 (1 << 6) // Having temporary tables not supported
2776#define HTON_SUPPORT_LOG_TABLES (1 << 7) // Engine supports log tables
2777#define HTON_NO_PARTITION (1 << 8) // You can not partition these tables
2778
2779/*
2780 This flag should be set when deciding that the engine does not allow row based
2781 binary logging (RBL) optimizations.
2782
2783 Currently, setting this flag, means that table's read/write_set will be left
2784 untouched when logging changes to tables in this engine. In practice this
2785 means that the server will not mess around with table->write_set and/or
2786 table->read_set when using RBL and deciding whether to log full or minimal
2787 rows.
2788
2789 It's valuable for instance for virtual tables, eg: Performance Schema which
2790 have no meaning for replication.
2791*/
2792#define HTON_NO_BINLOG_ROW_OPT (1 << 9)
2793
2794/**
2795 Engine supports extended keys. The flag allows to
2796 use 'extended key' feature if the engine is able to
2797 do it (has primary key values in the secondary key).
2798 Note that handler flag HA_PRIMARY_KEY_IN_READ_INDEX is
2799 actually partial case of HTON_SUPPORTS_EXTENDED_KEYS.
2800*/
2801
2802#define HTON_SUPPORTS_EXTENDED_KEYS (1 << 10)
2803
2804// Engine support foreign key constraint.
2805
2806#define HTON_SUPPORTS_FOREIGN_KEYS (1 << 11)
2807
2808/**
2809 Engine supports atomic DDL. That is rollback of transaction for DDL
2810 statement will also rollback all changes in SE, commit of transaction
2811 of DDL statement will make it durable.
2812*/
2813
2814#define HTON_SUPPORTS_ATOMIC_DDL (1 << 12)
2815
2816/* Engine supports packed keys. */
2817#define HTON_SUPPORTS_PACKED_KEYS (1 << 13)
2818
2819/** Engine is a secondary storage engine. */
2820#define HTON_IS_SECONDARY_ENGINE (1 << 14)
2821
2822/** Engine supports secondary storage engines. */
2823#define HTON_SUPPORTS_SECONDARY_ENGINE (1 << 15)
2824
2825/** Engine supports table or tablespace encryption . */
2826#define HTON_SUPPORTS_TABLE_ENCRYPTION (1 << 16)
2827
2829 1 << 17};
2830
2831/** Engine supports Generated invisible primary key. */
2832constexpr const decltype(
2834
2835inline bool ddl_is_atomic(const handlerton *hton) {
2836 return (hton->flags & HTON_SUPPORTS_ATOMIC_DDL) != 0;
2837}
2838
2839/* Bits for handlerton::foreign_keys_flags bitmap. */
2840
2841/**
2842 Engine supports both unique and non-unique parent keys for
2843 foreign keys which contain full foreign key as its prefix.
2844
2845 Storage engines which support foreign keys but do not have
2846 this flag set are assumed to support only parent keys which
2847 are primary/unique and contain exactly the same columns as
2848 the foreign key, possibly, in different order.
2849*/
2850
2852
2853/**
2854 Storage engine supports hash keys as supporting keys for foreign
2855 keys. Hash key should contain all foreign key columns and only
2856 them (although in any order).
2857
2858 Storage engines which support foreign keys but do not have this
2859 flag set are assumed to not allow hash keys as supporting keys.
2860*/
2861
2863
2864/**
2865 Storage engine supports non-hash keys which have common prefix
2866 with the foreign key as supporting keys for it. If there are
2867 several such keys, one which shares biggest prefix with FK is
2868 chosen.
2869
2870 Storage engines which support foreign keys but do not have this
2871 flag set are assumed to require that supporting key contains full
2872 foreign key as its prefix.
2873*/
2874
2876
2877/**
2878 Storage engine does not support using the same key for both parent
2879 and supporting key, but requires the two to be different.
2880*/
2881
2883 (1 << 3);
2884
2885/**
2886 Engine takes into account hidden part of key (coming from primary key)
2887 when determines if it can serve as parent key for a foreign key.
2888
2889 Implies HTON_FKS_WITH_PREFIX_PARENT_KEYS and is related to
2890 HTON_SUPPORTS_EXTENDED_KEYS.
2891*/
2892
2894
2895/**
2896 Maximum possible length of SE-specific suffixes for auto-generated
2897 foreign key names.
2898*/
2899static const size_t MAX_FK_NAME_SUFFIX_LENGTH = 16;
2900
2901/**
2902 Suffix for auto-generated foreign key names for tables in SE's which
2903 don't specify own suffix. I.e. for foreign keys on tables in such
2904 SE's generated names follow (table name)FK_NAME_DEFAULT_SUFFIX(FK number)
2905 pattern.
2906*/
2908
2915
2921
2922/* struct to hold information about the table that should be created */
2926 bool schema_read_only{false};
2928 const char *password{nullptr};
2929 const char *tablespace{nullptr};
2930 LEX_STRING comment{nullptr, 0};
2931
2932 /**
2933 Algorithm (and possible options) to be used for InnoDB's transparent
2934 page compression. If this attribute is set then it is hint to the
2935 storage engine to try and compress the data using the specified algorithm
2936 where possible. Note: this value is interpreted by the storage engine only.
2937 and ignored by the Server layer. */
2938
2940
2941 /**
2942 This attribute is used for InnoDB's transparent page encryption.
2943 If this attribute is set then it is hint to the storage engine to encrypt
2944 the data. Note: this value is interpreted by the storage engine only.
2945 and ignored by the Server layer. */
2946
2948
2949 /**
2950 * Secondary engine of the table.
2951 * Is nullptr if no secondary engine defined.
2952 */
2954
2955 const char *data_file_name{nullptr};
2956 const char *index_file_name{nullptr};
2957 const char *alias{nullptr};
2963 uint64_t used_fields{0};
2964 // Can only be 1,2,4,8 or 16, but use uint32_t since that how it is
2965 // represented in InnoDB
2966 std::uint32_t key_block_size{0};
2967 uint stats_sample_pages{0}; /* number of pages to sample during
2968 stats estimation, if used, otherwise 0. */
2972 /**
2973 Row type of the table definition.
2974
2975 Defaults to ROW_TYPE_DEFAULT for all non-ALTER statements.
2976 For ALTER TABLE defaults to ROW_TYPE_NOT_USED (means "keep the current").
2977
2978 Can be changed either explicitly by the parser.
2979 If nothing specified inherits the value of the original table (if present).
2980 */
2982 uint null_bits{0}; /* NULL bits at start of record */
2983 uint options{0}; /* OR of HA_CREATE_ options */
2985 ha_storage_media storage_media{HA_SM_DEFAULT}; /* DEFAULT, DISK or MEMORY */
2986
2987 /*
2988 A flag to indicate if this table should be marked as a hidden table in
2989 the data dictionary. One use case is to mark the temporary tables
2990 created by ALTER to be marked as hidden.
2991 */
2992 bool m_hidden{false};
2993
2994 /*
2995 A flag to indicate if this table should be created but not committed at
2996 the end of statement.
2997 */
2999
3002
3004
3006
3007 /**
3008 Fill HA_CREATE_INFO to be used by ALTER as well as upgrade code.
3009 This function separates code from mysql_prepare_alter_table() to be
3010 used by upgrade code as well to reduce code duplication.
3011 For ALTER code path, this lets new create options override the old
3012 ones.
3013
3014 @param[in] share TABLE_SHARE object
3015 @param[in] used_fields If a given create option is not flagged, old
3016 value be copied from the TABLE_SHARE.
3017 */
3018
3020 uint64_t used_fields);
3021};
3022
3023/**
3024 Structure describing changes to an index to be caused by ALTER TABLE.
3025*/
3026
3027struct KEY_PAIR {
3028 /**
3029 Pointer to KEY object describing old version of index in
3030 TABLE::key_info array for TABLE instance representing old
3031 version of table.
3032 */
3034 /**
3035 Pointer to KEY object describing new version of index in
3036 Alter_inplace_info::key_info_buffer array.
3037 */
3039};
3040
3041/**
3042 In-place alter handler context.
3043
3044 This is a superclass intended to be subclassed by individual handlers
3045 in order to store handler unique context between in-place alter API calls.
3046
3047 The handler is responsible for creating the object. This can be done
3048 as early as during check_if_supported_inplace_alter().
3049
3050 The SQL layer is responsible for destroying the object.
3051
3052 @see Alter_inplace_info
3053*/
3054
3056 public:
3058
3060 [[maybe_unused]]) {}
3061 virtual ~inplace_alter_handler_ctx() = default;
3062};
3063
3064/**
3065 Class describing changes to be done by ALTER TABLE.
3066 Instance of this class is passed to storage engine in order
3067 to determine if this ALTER TABLE can be done using in-place
3068 algorithm. It is also used for executing the ALTER TABLE
3069 using in-place algorithm.
3070*/
3071
3073 public:
3074 /**
3075 Bits to show in detail what operations the storage engine is
3076 to execute.
3077
3078 All these operations are supported as in-place operations by the
3079 SQL layer. This means that operations that by their nature must
3080 be performed by copying the table to a temporary table, will not
3081 have their own flags here (e.g. ALTER TABLE FORCE, ALTER TABLE
3082 ENGINE).
3083
3084 We generally try to specify handler flags only if there are real
3085 changes. But in cases when it is cumbersome to determine if some
3086 attribute has really changed we might choose to set flag
3087 pessimistically, for example, relying on parser output only.
3088 */
3090
3091 // Add non-unique, non-primary index
3092 static const HA_ALTER_FLAGS ADD_INDEX = 1ULL << 0;
3093
3094 // Drop non-unique, non-primary index
3095 static const HA_ALTER_FLAGS DROP_INDEX = 1ULL << 1;
3096
3097 // Add unique, non-primary index
3098 static const HA_ALTER_FLAGS ADD_UNIQUE_INDEX = 1ULL << 2;
3099
3100 // Drop unique, non-primary index
3101 static const HA_ALTER_FLAGS DROP_UNIQUE_INDEX = 1ULL << 3;
3102
3103 // Add primary index
3104 static const HA_ALTER_FLAGS ADD_PK_INDEX = 1ULL << 4;
3105
3106 // Drop primary index
3107 static const HA_ALTER_FLAGS DROP_PK_INDEX = 1ULL << 5;
3108
3109 // Add column
3110
3111 // Virtual generated column
3112 static const HA_ALTER_FLAGS ADD_VIRTUAL_COLUMN = 1ULL << 6;
3113 // Stored base (non-generated) column
3114 static const HA_ALTER_FLAGS ADD_STORED_BASE_COLUMN = 1ULL << 7;
3115 // Stored generated column
3117 // Add generic column (convenience constant).
3120
3121 // Drop column
3122 static const HA_ALTER_FLAGS DROP_VIRTUAL_COLUMN = 1ULL << 9;
3123 static const HA_ALTER_FLAGS DROP_STORED_COLUMN = 1ULL << 10;
3126
3127 // Rename column
3128 static const HA_ALTER_FLAGS ALTER_COLUMN_NAME = 1ULL << 11;
3129
3130 // Change column datatype
3132 static const HA_ALTER_FLAGS ALTER_STORED_COLUMN_TYPE = 1ULL << 13;
3133
3134 /**
3135 Change column datatype in such way that new type has compatible
3136 packed representation with old type, so it is theoretically
3137 possible to perform change by only updating data dictionary
3138 without changing table rows.
3139 */
3141
3142 /// A virtual column has changed its position
3144
3145 /// A stored column has changed its position (disregarding virtual columns)
3147
3148 // Change column from NOT NULL to NULL
3149 static const HA_ALTER_FLAGS ALTER_COLUMN_NULLABLE = 1ULL << 17;
3150
3151 // Change column from NULL to NOT NULL
3153
3154 // Set or remove default column value
3155 static const HA_ALTER_FLAGS ALTER_COLUMN_DEFAULT = 1ULL << 19;
3156
3157 // Change column generation expression
3158 static const HA_ALTER_FLAGS ALTER_VIRTUAL_GCOL_EXPR = 1ULL << 20;
3159 static const HA_ALTER_FLAGS ALTER_STORED_GCOL_EXPR = 1ULL << 21;
3160
3161 // Add foreign key
3162 static const HA_ALTER_FLAGS ADD_FOREIGN_KEY = 1ULL << 22;
3163
3164 // Drop foreign key
3165 static const HA_ALTER_FLAGS DROP_FOREIGN_KEY = 1ULL << 23;
3166
3167 // table_options changed, see HA_CREATE_INFO::used_fields for details.
3168 static const HA_ALTER_FLAGS CHANGE_CREATE_OPTION = 1ULL << 24;
3169
3170 // Table is renamed
3171 static const HA_ALTER_FLAGS ALTER_RENAME = 1ULL << 25;
3172
3173 // Change the storage type of column
3175
3176 // Change the column format of column
3178
3179 // Add partition
3180 static const HA_ALTER_FLAGS ADD_PARTITION = 1ULL << 28;
3181
3182 // Drop partition
3183 static const HA_ALTER_FLAGS DROP_PARTITION = 1ULL << 29;
3184
3185 // Changing partition options
3186 static const HA_ALTER_FLAGS ALTER_PARTITION = 1ULL << 30;
3187
3188 // Coalesce partition
3189 static const HA_ALTER_FLAGS COALESCE_PARTITION = 1ULL << 31;
3190
3191 // Reorganize partition ... into
3192 static const HA_ALTER_FLAGS REORGANIZE_PARTITION = 1ULL << 32;
3193
3194 // Reorganize partition
3195 static const HA_ALTER_FLAGS ALTER_TABLE_REORG = 1ULL << 33;
3196
3197 // Remove partitioning
3199
3200 // Partition operation with ALL keyword
3201 static const HA_ALTER_FLAGS ALTER_ALL_PARTITION = 1ULL << 35;
3202
3203 /**
3204 Rename index. Note that we set this flag only if there are no other
3205 changes to the index being renamed. Also for simplicity we don't
3206 detect renaming of indexes which is done by dropping index and then
3207 re-creating index with identical definition under different name.
3208 */
3209 static const HA_ALTER_FLAGS RENAME_INDEX = 1ULL << 36;
3210
3211 /**
3212 Recreate the table for ALTER TABLE FORCE, ALTER TABLE ENGINE
3213 and OPTIMIZE TABLE operations.
3214 */
3215 static const HA_ALTER_FLAGS RECREATE_TABLE = 1ULL << 37;
3216
3217 // Add spatial index
3218 static const HA_ALTER_FLAGS ADD_SPATIAL_INDEX = 1ULL << 38;
3219
3220 // Alter index comment
3221 static const HA_ALTER_FLAGS ALTER_INDEX_COMMENT = 1ULL << 39;
3222
3223 // New/changed virtual generated column require validation
3224 static const HA_ALTER_FLAGS VALIDATE_VIRTUAL_COLUMN = 1ULL << 40;
3225
3226 /**
3227 Change index option in a way which is likely not to require index
3228 recreation. For example, change COMMENT or KEY::is_algorithm_explicit
3229 flag (without change of index algorithm itself).
3230 */
3231 static const HA_ALTER_FLAGS CHANGE_INDEX_OPTION = 1LL << 41;
3232
3233 // Rebuild partition
3234 static const HA_ALTER_FLAGS ALTER_REBUILD_PARTITION = 1ULL << 42;
3235
3236 /**
3237 Change in index length such that it does not require index rebuild.
3238 For example, change in index length due to column expansion like
3239 varchar(X) changed to varchar(X + N).
3240 */
3242
3243 /**
3244 Change to one of columns on which virtual generated column depends,
3245 so its values require re-evaluation.
3246 */
3247 static const HA_ALTER_FLAGS VIRTUAL_GCOL_REEVAL = 1ULL << 44;
3248
3249 /**
3250 Change to one of columns on which stored generated column depends,
3251 so its values require re-evaluation.
3252 */
3253 static const HA_ALTER_FLAGS STORED_GCOL_REEVAL = 1ULL << 45;
3254
3255 // Add check constraint.
3256 static const HA_ALTER_FLAGS ADD_CHECK_CONSTRAINT = 1ULL << 46;
3257
3258 // Drop check constraint.
3259 static const HA_ALTER_FLAGS DROP_CHECK_CONSTRAINT = 1ULL << 47;
3260
3261 // Suspend check constraint.
3262 static const HA_ALTER_FLAGS SUSPEND_CHECK_CONSTRAINT = 1ULL << 48;
3263
3264 // Alter column visibility.
3265 static const HA_ALTER_FLAGS ALTER_COLUMN_VISIBILITY = 1ULL << 49;
3266
3267 /**
3268 Create options (like MAX_ROWS) for the new version of table.
3269
3270 @note The referenced instance of HA_CREATE_INFO object was already
3271 used to create new .FRM file for table being altered. So it
3272 has been processed by mysql_prepare_create_table() already.
3273 For example, this means that it has HA_OPTION_PACK_RECORD
3274 flag in HA_CREATE_INFO::table_options member correctly set.
3275 */
3277
3278 /**
3279 Alter options, fields and keys for the new version of table.
3280
3281 @note The referenced instance of Alter_info object was already
3282 used to create new .FRM file for table being altered. So it
3283 has been processed by mysql_prepare_create_table() already.
3284 In particular, this means that in Create_field objects for
3285 fields which were present in some form in the old version
3286 of table, Create_field::field member points to corresponding
3287 Field instance for old version of table.
3288 */
3290
3291 /**
3292 Indicates whether operation should fail if table is non-empty.
3293 Storage engines should not suggest/allow execution of such operations
3294 using INSTANT algorithm since check whether table is empty done from
3295 SQL-layer is not "instant". Also SEs might choose different algorithm for
3296 ALTER TABLE execution knowing that it will be allowed to proceed only if
3297 table is empty.
3298
3299 Unlike for Alter_table_ctx::error_if_not_empty, we use bool for this flag
3300 and not bitmap, since SEs are really interested in the fact that ALTER
3301 will fail if table is not empty and not in exact reason behind this fact,
3302 and because we want to avoid extra dependency between Alter_table_ctx and
3303 Alter_inplace_info.
3304 */
3306
3307 /**
3308 Array of KEYs for new version of table - including KEYs to be added.
3309
3310 @note Currently this array is produced as result of
3311 mysql_prepare_create_table() call.
3312 This means that it follows different convention for
3313 KEY_PART_INFO::fieldnr values than objects in TABLE::key_info
3314 array.
3315
3316 @todo This is mainly due to the fact that we need to keep compatibility
3317 with removed handler::add_index() call. We plan to switch to
3318 TABLE::key_info numbering later.
3319
3320 KEYs are sorted - see sort_keys().
3321 */
3323
3324 /** Size of key_info_buffer array. */
3326
3327 /** Size of index_drop_buffer array. */
3329
3330 /**
3331 Array of pointers to KEYs to be dropped belonging to the TABLE instance
3332 for the old version of the table.
3333 */
3335
3336 /** Size of index_add_buffer array. */
3338
3339 /**
3340 Array of indexes into key_info_buffer for KEYs to be added,
3341 sorted in increasing order.
3342 */
3344
3345 /** Size of index_rename_buffer array. */
3347
3348 /** Size of index_rename_buffer array. */
3350
3351 /**
3352 Array of KEY_PAIR objects describing indexes being renamed.
3353 For each index renamed it contains object with KEY_PAIR::old_key
3354 pointing to KEY object belonging to the TABLE instance for old
3355 version of table representing old version of index and with
3356 KEY_PAIR::new_key pointing to KEY object for new version of
3357 index in key_info_buffer member.
3358 */
3361
3362 /** Number of virtual columns to be added. */
3364
3365 /** number of virtual columns to be dropped. */
3367
3368 /**
3369 Context information to allow handlers to keep context between in-place
3370 alter API calls.
3371
3372 @see inplace_alter_handler_ctx for information about object lifecycle.
3373 */
3375
3376 /**
3377 If the table uses several handlers, like ha_partition uses one handler
3378 per partition, this contains a Null terminated array of ctx pointers
3379 that should all be committed together.
3380 Or NULL if only handler_ctx should be committed.
3381 Set to NULL if the low level handler::commit_inplace_alter_table uses it,
3382 to signal to the main handler that everything was committed as atomically.
3383
3384 @see inplace_alter_handler_ctx for information about object lifecycle.
3385 */
3387
3388 /**
3389 Flags describing in detail which operations the storage engine is to
3390 execute.
3391 */
3393
3394 /**
3395 Partition_info taking into account the partition changes to be performed.
3396 Contains all partitions which are present in the old version of the table
3397 with partitions to be dropped or changed marked as such + all partitions
3398 to be added in the new version of table marked as such.
3399 */
3401
3402 /** true for online operation (LOCK=NONE) */
3404
3405 /**
3406 Can be set by handler along with handler_ctx. The difference is that
3407 this flag can be used to store SE-specific in-place ALTER context in cases
3408 when constructing full-blown inplace_alter_handler_ctx descendant is
3409 inconvenient.
3410 */
3412
3413 /**
3414 Can be set by handler to describe why a given operation cannot be done
3415 in-place (HA_ALTER_INPLACE_NOT_SUPPORTED) or why it cannot be done
3416 online (HA_ALTER_INPLACE_NO_LOCK or HA_ALTER_INPLACE_NO_LOCK_AFTER_PREPARE)
3417 If set, it will be used with ER_ALTER_OPERATION_NOT_SUPPORTED_REASON if
3418 results from handler::check_if_supported_inplace_alter() doesn't match
3419 requirements set by user. If not set, the more generic
3420 ER_ALTER_OPERATION_NOT_SUPPORTED will be used.
3421
3422 Please set to a properly localized string, for example using
3423 my_get_err_msg(), so that the error message as a whole is localized.
3424 */
3426
3428 Alter_info *alter_info_arg, bool error_if_not_empty_arg,
3429 KEY *key_info_arg, uint key_count_arg,
3430 partition_info *modified_part_info_arg)
3431 : create_info(create_info_arg),
3432 alter_info(alter_info_arg),
3433 error_if_not_empty(error_if_not_empty_arg),
3434 key_info_buffer(key_info_arg),
3435 key_count(key_count_arg),
3438 index_add_count(0),
3447 handler_flags(0),
3448 modified_part_info(modified_part_info_arg),
3449 online(false),
3452
3454
3455 /**
3456 Used after check_if_supported_inplace_alter() to report
3457 error if the result does not match the LOCK/ALGORITHM
3458 requirements set by the user.
3459
3460 @param not_supported Part of statement that was not supported.
3461 @param try_instead Suggestion as to what the user should
3462 replace not_supported with.
3463 */
3464 void report_unsupported_error(const char *not_supported,
3465 const char *try_instead);
3466
3467 /** Add old and new version of key to array of indexes to be renamed. */
3468 void add_renamed_key(KEY *old_key, KEY *new_key) {
3470 key_pair->old_key = old_key;
3471 key_pair->new_key = new_key;
3472 DBUG_PRINT("info",
3473 ("index renamed: '%s' to '%s'", old_key->name, new_key->name));
3474 }
3475
3476 void add_altered_index_visibility(KEY *old_key, KEY *new_key) {
3477 KEY_PAIR *key_pair =
3479 key_pair->old_key = old_key;
3480 key_pair->new_key = new_key;
3481 DBUG_PRINT("info", ("index had visibility altered: %i to %i",
3482 old_key->is_visible, new_key->is_visible));
3483 }
3484
3485 /**
3486 Add old and new version of modified key to arrays of indexes to
3487 be dropped and added (correspondingly).
3488 */
3489 void add_modified_key(KEY *old_key, KEY *new_key) {
3492 DBUG_PRINT("info", ("index changed: '%s'", old_key->name));
3493 }
3494
3495 /** Drop key to array of indexes to be dropped. */
3496 void add_dropped_key(KEY *old_key) {
3498 DBUG_PRINT("info", ("index dropped: '%s'", old_key->name));
3499 }
3500
3501 /** Add key to array of indexes to be added. */
3502 void add_added_key(KEY *new_key) {
3504 DBUG_PRINT("info", ("index added: '%s'", new_key->name));
3505 }
3506};
3507
3509 uint flags{0}; /* isam layer flags (e.g. for myisamchk) */
3510 uint sql_flags{0}; /* sql layer flags - for something myisamchk cannot do */
3511 KEY_CACHE *key_cache; /* new key cache when changing key cache */
3512};
3513
3514/*
3515 This is a buffer area that the handler can use to store rows.
3516 'end_of_used_area' should be kept updated after calls to
3517 read-functions so that other parts of the code can use the
3518 remaining area (until next read calls is issued).
3519*/
3520
3522 uchar *buffer; /* Buffer one can start using */
3523 uchar *buffer_end; /* End of buffer */
3524 uchar *end_of_used_area; /* End of area that was used by handler */
3525};
3526
3527typedef void *range_seq_t;
3528
3530 /*
3531 Initialize the traversal of range sequence
3532
3533 SYNOPSIS
3534 init()
3535 init_params The seq_init_param parameter
3536 n_ranges The number of ranges obtained
3537 flags A combination of HA_MRR_SINGLE_POINT, HA_MRR_FIXED_KEY
3538
3539 RETURN
3540 An opaque value to be used as RANGE_SEQ_IF::next() parameter
3541 */
3542 range_seq_t (*init)(void *init_params, uint n_ranges, uint flags);
3543
3544 /*
3545 Get the next range in the range sequence
3546
3547 SYNOPSIS
3548 next()
3549 seq The value returned by RANGE_SEQ_IF::init()
3550 range OUT Information about the next range
3551
3552 RETURN
3553 0 - Ok, the range structure filled with info about the next range
3554 1 - No more ranges
3555 */
3557
3558 /*
3559 Check whether range_info orders to skip the next record
3560
3561 SYNOPSIS
3562 skip_record()
3563 seq The value returned by RANGE_SEQ_IF::init()
3564 range_info Information about the next range
3565 (Ignored if MRR_NO_ASSOCIATION is set)
3566 rowid Rowid of the record to be checked (ignored if set to 0)
3567
3568 RETURN
3569 1 - Record with this range_info and/or this rowid shall be filtered
3570 out from the stream of records returned by ha_multi_range_read_next()
3571 0 - The record shall be left in the stream
3572 */
3573 bool (*skip_record)(range_seq_t seq, char *range_info, uchar *rowid);
3574};
3575
3576/**
3577 Used to store optimizer cost estimates.
3578
3579 The class consists of PODs only: default operator=, copy constructor
3580 and destructor are used.
3581 */
3583 private:
3584 double io_cost; ///< cost of I/O operations
3585 double cpu_cost; ///< cost of CPU operations
3586 double import_cost; ///< cost of remote operations
3587 double mem_cost; ///< memory used (bytes)
3588
3589 public:
3591
3592 /// Returns sum of time-consuming costs, i.e., not counting memory cost
3593 double total_cost() const { return io_cost + cpu_cost + import_cost; }
3594 double get_io_cost() const { return io_cost; }
3595 double get_cpu_cost() const { return cpu_cost; }
3596 double get_import_cost() const { return import_cost; }
3597 double get_mem_cost() const { return mem_cost; }
3598
3599 /**
3600 Whether or not all costs in the object are zero
3601
3602 @return true if all costs are zero, false otherwise
3603 */
3604 bool is_zero() const {
3605 return !(io_cost || cpu_cost || import_cost || mem_cost);
3606 }
3607 /**
3608 Whether or not the total cost is the maximal double
3609
3610 @return true if total cost is the maximal double, false otherwise
3611 */
3612 bool is_max_cost() const { return io_cost == DBL_MAX; }
3613 /// Reset all costs to zero
3615 /// Set current cost to the maximal double
3617 reset();
3618 io_cost = DBL_MAX;
3619 }
3620
3621 /// Multiply io, cpu and import costs by parameter
3622 void multiply(double m) {
3623 assert(!is_max_cost());
3624
3625 io_cost *= m;
3626 cpu_cost *= m;
3627 import_cost *= m;
3628 /* Don't multiply mem_cost */
3629 }
3630
3632 assert(!is_max_cost() && !other.is_max_cost());
3633
3634 io_cost += other.io_cost;
3635 cpu_cost += other.cpu_cost;
3636 import_cost += other.import_cost;
3637 mem_cost += other.mem_cost;
3638
3639 return *this;
3640 }
3641
3643 Cost_estimate result = *this;
3644 result += other;
3645
3646 return result;
3647 }
3648
3651
3652 assert(!other.is_max_cost());
3653
3654 result.io_cost = io_cost - other.io_cost;
3655 result.cpu_cost = cpu_cost - other.cpu_cost;
3656 result.import_cost = import_cost - other.import_cost;
3657 result.mem_cost = mem_cost - other.mem_cost;
3658 return result;
3659 }
3660
3661 bool operator>(const Cost_estimate &other) const {
3662 return total_cost() > other.total_cost() ? true : false;
3663 }
3664
3665 bool operator<(const Cost_estimate &other) const {
3666 return other > *this ? true : false;
3667 }
3668
3669 /// Add to IO cost
3670 void add_io(double add_io_cost) {
3671 assert(!is_max_cost());
3672 io_cost += add_io_cost;
3673 }
3674
3675 /// Add to CPU cost
3676 void add_cpu(double add_cpu_cost) {
3677 assert(!is_max_cost());
3678 cpu_cost += add_cpu_cost;
3679 }
3680
3681 /// Add to import cost
3682 void add_import(double add_import_cost) {
3683 assert(!is_max_cost());
3684 import_cost += add_import_cost;
3685 }
3686
3687 /// Add to memory cost
3688 void add_mem(double add_mem_cost) {
3689 assert(!is_max_cost());
3690 mem_cost += add_mem_cost;
3691 }
3692};
3693
3694void get_sweep_read_cost(TABLE *table, ha_rows nrows, bool interrupted,
3695 Cost_estimate *cost);
3696
3697/*
3698 The below two are not used (and not handled) in this milestone of this WL
3699 entry because there seems to be no use for them at this stage of
3700 implementation.
3701*/
3702#define HA_MRR_SINGLE_POINT 1
3703#define HA_MRR_FIXED_KEY 2
3704
3705/*
3706 Indicates that RANGE_SEQ_IF::next(&range) doesn't need to fill in the
3707 'range' parameter.
3708*/
3709#define HA_MRR_NO_ASSOCIATION 4
3710
3711/*
3712 The MRR user will provide ranges in key order, and MRR implementation
3713 must return rows in key order.
3714 Passing this flag to multi_read_range_init() may cause the
3715 default MRR handler to be used even if HA_MRR_USE_DEFAULT_IMPL
3716 was not specified.
3717 (If the native MRR impl. can not provide SORTED result)
3718*/
3719#define HA_MRR_SORTED 8
3720
3721/* MRR implementation doesn't have to retrieve full records */
3722#define HA_MRR_INDEX_ONLY 16
3723
3724/*
3725 The passed memory buffer is of maximum possible size, the caller can't
3726 assume larger buffer.
3727*/
3728#define HA_MRR_LIMITS 32
3729
3730/*
3731 Flag set <=> default MRR implementation is used
3732 (The choice is made by **_info[_const]() function which may set this
3733 flag. SQL layer remembers the flag value and then passes it to
3734 multi_read_range_init().
3735*/
3736#define HA_MRR_USE_DEFAULT_IMPL 64
3737
3738/*
3739 Used only as parameter to multi_range_read_info():
3740 Flag set <=> the caller guarantees that the bounds of the scanned ranges
3741 will not have NULL values.
3742*/
3743#define HA_MRR_NO_NULL_ENDPOINTS 128
3744
3745/*
3746 Set by the MRR implementation to signal that it will natively
3747 produced sorted result if multi_range_read_init() is called with
3748 the HA_MRR_SORTED flag - Else multi_range_read_init(HA_MRR_SORTED)
3749 will revert to use the default MRR implementation.
3750*/
3751#define HA_MRR_SUPPORT_SORTED 256
3752
3754 public:
3755 ulonglong data_file_length; /* Length off data file */
3756 ulonglong max_data_file_length; /* Length off data file */
3759 ulonglong delete_length; /* Free bytes */
3761 /*
3762 The number of records in the table.
3763 0 - means the table has exactly 0 rows
3764 other - if (table_flags() & HA_STATS_RECORDS_IS_EXACT)
3765 the value is the exact number of records in the table
3766 else
3767 it is an estimate
3768 */
3770 ha_rows deleted; /* Deleted records */
3771 ulong mean_rec_length; /* physical reclength */
3772 /* TODO: create_time should be retrieved from the new DD. Remove this. */
3773 time_t create_time; /* When table was created */
3776 uint block_size; /* index block size */
3777
3778 /*
3779 number of buffer bytes that native mrr implementation needs,
3780 */
3782
3783 /**
3784 Estimate for how much of the table that is available in a memory
3785 buffer. Valid range is [0..1]. If it has the special value
3786 IN_MEMORY_ESTIMATE_UNKNOWN (defined in structs.h), it means that
3787 the storage engine has not supplied any value for it.
3788 */
3790
3792 : data_file_length(0),
3795 delete_length(0),
3797 records(0),
3798 deleted(0),
3799 mean_rec_length(0),
3800 create_time(0),
3801 check_time(0),
3802 update_time(0),
3803 block_size(0),
3805};
3806
3807/**
3808 Calculates length of key.
3809
3810 Given a key index and a map of key parts return length of buffer used by key
3811 parts.
3812
3813 @param table Table containing the key
3814 @param key Key index
3815 @param keypart_map which key parts that is used
3816
3817 @return Length of used key parts.
3818*/
3819uint calculate_key_len(TABLE *table, uint key, key_part_map keypart_map);
3820/*
3821 bitmap with first N+1 bits set
3822 (keypart_map for a key prefix of [0..N] keyparts)
3823*/
3824#define make_keypart_map(N) (((key_part_map)2 << (N)) - 1)
3825/*
3826 bitmap with first N bits set
3827 (keypart_map for a key prefix of [0..N-1] keyparts)
3828*/
3829#define make_prev_keypart_map(N) (((key_part_map)1 << (N)) - 1)
3830
3831/** Base class to be used by handlers different shares */
3833 public:
3834 Handler_share() = default;
3835 virtual ~Handler_share() = default;
3836};
3837
3838/**
3839 Wrapper for struct ft_hints.
3840*/
3841
3843 private:
3845
3846 public:
3847 explicit Ft_hints(uint ft_flags) {
3848 hints.flags = ft_flags;
3850 hints.op_value = 0.0;
3852 }
3853
3854 /**
3855 Set comparison operation type and and value for master MATCH function.
3856
3857 @param type comparison operation type
3858 @param value comparison operation value
3859 */
3860 void set_hint_op(enum ft_operation type, double value) {
3861 hints.op_type = type;
3862 hints.op_value = value;
3863 }
3864
3865 /**
3866 Set Ft_hints flag.
3867
3868 @param ft_flag Ft_hints flag
3869 */
3870 void set_hint_flag(uint ft_flag) { hints.flags |= ft_flag; }
3871
3872 /**
3873 Set Ft_hints limit.
3874
3875 @param ft_limit limit
3876 */
3877 void set_hint_limit(ha_rows ft_limit) { hints.limit = ft_limit; }
3878
3879 /**
3880 Get Ft_hints limit.
3881
3882 @return Ft_hints limit
3883 */
3884 ha_rows get_limit() const { return hints.limit; }
3885
3886 /**
3887 Get Ft_hints operation value.
3888
3889 @return operation value
3890 */
3891 double get_op_value() const { return hints.op_value; }
3892
3893 /**
3894 Get Ft_hints operation type.
3895
3896 @return operation type
3897 */
3898 enum ft_operation get_op_type() const { return hints.op_type; }
3899
3900 /**
3901 Get Ft_hints flags.
3902
3903 @return Ft_hints flags
3904 */
3905 uint get_flags() const { return hints.flags; }
3906
3907 /**
3908 Get ft_hints struct.
3909
3910 @return pointer to ft_hints struct
3911 */
3913 return &hints;
3914 }
3915};
3916
3917/**
3918 The handler class is the interface for dynamically loadable
3919 storage engines. Do not add ifdefs and take care when adding or
3920 changing virtual functions to avoid vtable confusion
3921
3922 Functions in this class accept and return table columns data. Two data
3923 representation formats are used:
3924 1. TableRecordFormat - Used to pass [partial] table records to/from
3925 storage engine
3926
3927 2. KeyTupleFormat - used to pass index search tuples (aka "keys") to
3928 storage engine. See opt_range.cc for description of this format.
3929
3930 TableRecordFormat
3931 =================
3932 [Warning: this description is work in progress and may be incomplete]
3933 The table record is stored in a fixed-size buffer:
3934
3935 record: null_bytes, column1_data, column2_data, ...
3936
3937 The offsets of the parts of the buffer are also fixed: every column has
3938 an offset to its column{i}_data, and if it is nullable it also has its own
3939 bit in null_bytes.
3940
3941 The record buffer only includes data about columns that are marked in the
3942 relevant column set (table->read_set and/or table->write_set, depending on
3943 the situation).
3944 <not-sure>It could be that it is required that null bits of non-present
3945 columns are set to 1</not-sure>
3946
3947 VARIOUS EXCEPTIONS AND SPECIAL CASES
3948
3949 If the table has no nullable columns, then null_bytes is still
3950 present, its length is one byte <not-sure> which must be set to 0xFF
3951 at all times. </not-sure>
3952
3953 If the table has columns of type BIT, then certain bits from those columns
3954 may be stored in null_bytes as well. Grep around for Field_bit for
3955 details.
3956
3957 For blob columns (see Field_blob), the record buffer stores length of the
3958 data, following by memory pointer to the blob data. The pointer is owned
3959 by the storage engine and is valid until the next operation.
3960
3961 If a blob column has NULL value, then its length and blob data pointer
3962 must be set to 0.
3963
3964
3965 Overview of main modules of the handler API
3966 ===========================================
3967 The overview below was copied from the storage/partition/ha_partition.h when
3968 support for non-native partitioning was removed.
3969
3970 -------------------------------------------------------------------------
3971 MODULE create/delete handler object
3972 -------------------------------------------------------------------------
3973 Object create/delete method. Normally called when a table object
3974 exists.
3975
3976 -------------------------------------------------------------------------
3977 MODULE meta data changes
3978 -------------------------------------------------------------------------
3979 Meta data routines to CREATE, DROP, RENAME table are often used at
3980 ALTER TABLE (update_create_info used from ALTER TABLE and SHOW ..).
3981
3982 Methods:
3983 delete_table()
3984 rename_table()
3985 create()
3986 update_create_info()
3987
3988 -------------------------------------------------------------------------
3989 MODULE open/close object
3990 -------------------------------------------------------------------------
3991 Open and close handler object to ensure all underlying files and
3992 objects allocated and deallocated for query handling is handled
3993 properly.
3994
3995 A handler object is opened as part of its initialisation and before
3996 being used for normal queries (not before meta-data changes always.
3997 If the object was opened it will also be closed before being deleted.
3998
3999 Methods:
4000 open()
4001 close()
4002
4003 -------------------------------------------------------------------------
4004 MODULE start/end statement
4005 -------------------------------------------------------------------------
4006 This module contains methods that are used to understand start/end of
4007 statements, transaction boundaries, and aid for proper concurrency
4008 control.
4009
4010 Methods:
4011 store_lock()
4012 external_lock()
4013 start_stmt()
4014 lock_count()
4015 unlock_row()
4016 was_semi_consistent_read()
4017 try_semi_consistent_read()
4018
4019 -------------------------------------------------------------------------
4020 MODULE change record
4021 -------------------------------------------------------------------------
4022 This part of the handler interface is used to change the records
4023 after INSERT, DELETE, UPDATE, REPLACE method calls but also other
4024 special meta-data operations as ALTER TABLE, LOAD DATA, TRUNCATE.
4025
4026 These methods are used for insert (write_row), update (update_row)
4027 and delete (delete_row). All methods to change data always work on
4028 one row at a time. update_row and delete_row also contains the old
4029 row.
4030 delete_all_rows will delete all rows in the table in one call as a
4031 special optimization for DELETE from table;
4032
4033 Bulk inserts are supported if all underlying handlers support it.
4034 start_bulk_insert and end_bulk_insert is called before and after a
4035 number of calls to write_row.
4036
4037 Methods:
4038 write_row()
4039 update_row()
4040 delete_row()
4041 delete_all_rows()
4042 start_bulk_insert()
4043 end_bulk_insert()
4044
4045 -------------------------------------------------------------------------
4046 MODULE full table scan
4047 -------------------------------------------------------------------------
4048 This module is used for the most basic access method for any table
4049 handler. This is to fetch all data through a full table scan. No
4050 indexes are needed to implement this part.
4051 It contains one method to start the scan (rnd_init) that can also be
4052 called multiple times (typical in a nested loop join). Then proceeding
4053 to the next record (rnd_next) and closing the scan (rnd_end).
4054 To remember a record for later access there is a method (position)
4055 and there is a method used to retrieve the record based on the stored
4056 position.
4057 The position can be a file position, a primary key, a ROWID dependent
4058 on the handler below.
4059
4060 All functions that retrieve records and are callable through the
4061 handler interface must indicate whether a record is present after the call
4062 or not. Record found is indicated by returning 0 and setting table status
4063 to "has row". Record not found is indicated by returning a non-zero value
4064 and setting table status to "no row".
4065 @see TABLE::set_found_row() and TABLE::set_no_row().
4066 By enforcing these rules in the handler interface, storage handler functions
4067 need not set any status in struct TABLE. These notes also apply to module
4068 index scan, documented below.
4069
4070 Methods:
4071
4072 rnd_init()
4073 rnd_end()
4074 rnd_next()
4075 rnd_pos()
4076 rnd_pos_by_record()
4077 position()
4078
4079 -------------------------------------------------------------------------
4080 MODULE index scan
4081 -------------------------------------------------------------------------
4082 This part of the handler interface is used to perform access through
4083 indexes. The interface is defined as a scan interface but the handler
4084 can also use key lookup if the index is a unique index or a primary
4085 key index.
4086 Index scans are mostly useful for SELECT queries but are an important
4087 part also of UPDATE, DELETE, REPLACE and CREATE TABLE table AS SELECT
4088 and so forth.
4089 Naturally an index is needed for an index scan and indexes can either
4090 be ordered, hash based. Some ordered indexes can return data in order
4091 but not necessarily all of them.
4092 There are many flags that define the behavior of indexes in the
4093 various handlers. These methods are found in the optimizer module.
4094
4095 index_read is called to start a scan of an index. The find_flag defines
4096 the semantics of the scan. These flags are defined in
4097 include/my_base.h
4098 index_read_idx is the same but also initializes index before calling doing
4099 the same thing as index_read. Thus it is similar to index_init followed
4100 by index_read. This is also how we implement it.
4101
4102 index_read/index_read_idx does also return the first row. Thus for
4103 key lookups, the index_read will be the only call to the handler in
4104 the index scan.
4105
4106 index_init initializes an index before using it and index_end does
4107 any end processing needed.
4108
4109 Methods:
4110 index_read_map()
4111 index_init()
4112 index_end()
4113 index_read_idx_map()
4114 index_next()
4115 index_prev()
4116 index_first()
4117 index_last()
4118 index_next_same()
4119 index_read_last_map()
4120 read_range_first()
4121 read_range_next()
4122
4123 -------------------------------------------------------------------------
4124 MODULE information calls
4125 -------------------------------------------------------------------------
4126 This calls are used to inform the handler of specifics of the ongoing
4127 scans and other actions. Most of these are used for optimisation
4128 purposes.
4129
4130 Methods:
4131 info()
4132 get_dynamic_partition_info
4133 extra()
4134 extra_opt()
4135 reset()
4136
4137 -------------------------------------------------------------------------
4138 MODULE optimizer support
4139 -------------------------------------------------------------------------
4140 NOTE:
4141 One important part of the public handler interface that is not depicted in
4142 the methods is the attribute records which is defined in the base class.
4143 This is looked upon directly and is set by calling info(HA_STATUS_INFO) ?
4144
4145 Methods:
4146 min_rows_for_estimate()
4147 get_biggest_used_partition()
4148 scan_time()
4149 read_time()
4150 records_in_range()
4151 estimate_rows_upper_bound()
4152 records()
4153
4154 -------------------------------------------------------------------------
4155 MODULE print messages
4156 -------------------------------------------------------------------------
4157 This module contains various methods that returns text messages for
4158 table types, index type and error messages.
4159
4160 Methods:
4161 table_type()
4162 get_row_type()
4163 print_error()
4164 get_error_message()
4165
4166 -------------------------------------------------------------------------
4167 MODULE handler characteristics
4168 -------------------------------------------------------------------------
4169 This module contains a number of methods defining limitations and
4170 characteristics of the handler (see also documentation regarding the
4171 individual flags).
4172
4173 Methods:
4174 table_flags()
4175 index_flags()
4176 min_of_the_max_uint()
4177 max_supported_record_length()
4178 max_supported_keys()
4179 max_supported_key_parts()
4180 max_supported_key_length()
4181 max_supported_key_part_length()
4182 low_byte_first()
4183 extra_rec_buf_length()
4184 min_record_length(uint options)
4185 primary_key_is_clustered()
4186 ha_key_alg get_default_index_algorithm()
4187 is_index_algorithm_supported()
4188
4189 -------------------------------------------------------------------------
4190 MODULE compare records
4191 -------------------------------------------------------------------------
4192 cmp_ref checks if two references are the same. For most handlers this is
4193 a simple memcmp of the reference. However some handlers use primary key
4194 as reference and this can be the same even if memcmp says they are
4195 different. This is due to character sets and end spaces and so forth.
4196
4197 Methods:
4198 cmp_ref()
4199
4200 -------------------------------------------------------------------------
4201 MODULE auto increment
4202 -------------------------------------------------------------------------
4203 This module is used to handle the support of auto increments.
4204
4205 This variable in the handler is used as part of the handler interface
4206 It is maintained by the parent handler object and should not be
4207 touched by child handler objects (see handler.cc for its use).
4208
4209 Methods:
4210 get_auto_increment()
4211 release_auto_increment()
4212
4213 -------------------------------------------------------------------------
4214 MODULE initialize handler for HANDLER call
4215 -------------------------------------------------------------------------
4216 This method is a special InnoDB method called before a HANDLER query.
4217
4218 Methods:
4219 init_table_handle_for_HANDLER()
4220
4221 -------------------------------------------------------------------------
4222 MODULE fulltext index
4223 -------------------------------------------------------------------------
4224 Fulltext index support.
4225
4226 Methods:
4227 ft_init_ext_with_hints()
4228 ft_init()
4229 ft_init_ext()
4230 ft_read()
4231
4232 -------------------------------------------------------------------------
4233 MODULE in-place ALTER TABLE
4234 -------------------------------------------------------------------------
4235 Methods for in-place ALTER TABLE support (implemented by InnoDB and NDB).
4236
4237 Methods:
4238 check_if_supported_inplace_alter()
4239 prepare_inplace_alter_table()
4240 inplace_alter_table()
4241 commit_inplace_alter_table()
4242 notify_table_changed()
4243
4244 -------------------------------------------------------------------------
4245 MODULE tablespace support
4246 -------------------------------------------------------------------------
4247 Methods:
4248 discard_or_import_tablespace()
4249
4250 -------------------------------------------------------------------------
4251 MODULE administrative DDL
4252 -------------------------------------------------------------------------
4253 Methods:
4254 optimize()
4255 analyze()
4256 check()
4257 repair()
4258 check_and_repair()
4259 auto_repair()
4260 is_crashed()
4261 check_for_upgrade()
4262 checksum()
4263 assign_to_keycache()
4264
4265 -------------------------------------------------------------------------
4266 MODULE enable/disable indexes
4267 -------------------------------------------------------------------------
4268 Enable/Disable Indexes are only supported by HEAP and MyISAM.
4269
4270 Methods:
4271 disable_indexes()
4272 enable_indexes()
4273 indexes_are_disabled()
4274
4275 -------------------------------------------------------------------------
4276 MODULE append_create_info
4277 -------------------------------------------------------------------------
4278 Only used by MyISAM MERGE tables.
4279
4280 Methods:
4281 append_create_info()
4282
4283 -------------------------------------------------------------------------
4284 MODULE partitioning specific handler API
4285 -------------------------------------------------------------------------
4286 Methods:
4287 get_partition_handler()
4288*/
4289
4290class handler {
4291 friend class Partition_handler;
4292
4293 public:
4295
4296 protected:
4297 TABLE_SHARE *table_share; /* The table definition */
4298 TABLE *table; /* The current open table */
4299 Table_flags cached_table_flags{0}; /* Set on init() and open() */
4300
4302
4303 public:
4304 handlerton *ht; /* storage engine of this handler */
4305 /** Pointer to current row */
4307 /** Pointer to duplicate row */
4309
4311
4312 /* MultiRangeRead-related members: */
4313 range_seq_t mrr_iter; /* Iterator to traverse the range sequence */
4314 RANGE_SEQ_IF mrr_funcs; /* Range sequence traversal functions */
4315 HANDLER_BUFFER *multi_range_buffer; /* MRR buffer info */
4316 uint ranges_in_seq; /* Total number of ranges in the traversed sequence */
4317 /* true <=> source MRR ranges and the output are ordered */
4319
4320 /* true <=> we're currently traversing a range in mrr_cur_range. */
4322 /* Current range (the one we're now returning rows from) */
4324
4325 /*
4326 The direction of the current range or index scan. This is used by
4327 the ICP implementation to determine if it has reached the end
4328 of the current range.
4329 */
4331
4332 private:
4333 Record_buffer *m_record_buffer = nullptr; ///< Buffer for multi-row reads.
4334 /*
4335 Storage space for the end range value. Should only be accessed using
4336 the end_range pointer. The content is invalid when end_range is NULL.
4337 */
4341
4342 /**
4343 Pointer to the handler of the table in the primary storage engine,
4344 if this handler represents a table in a secondary storage engine.
4345 */
4347
4348 protected:
4351 /*
4352 true <=> the engine guarantees that returned records are within the range
4353 being scanned.
4354 */
4356
4357 public:
4358 /**
4359 End value for a range scan. If this is NULL the range scan has no
4360 end value. Should also be NULL when there is no ongoing range scan.
4361 Used by the read_range() functions and also evaluated by pushed
4362 index conditions.
4363 */
4365 /**
4366 Flag which tells if #end_range contains a virtual generated column.
4367 The content is invalid when #end_range is @c nullptr.
4368 */
4370 uint errkey; /* Last dup key */
4373 /** Length of ref (1-8 or the clustered key length) */
4376 enum { NONE = 0, INDEX, RND, SAMPLING } inited;
4377 bool implicit_emptied; /* Can be !=0 only if HEAP */
4379
4381 uint pushed_idx_cond_keyno; /* The index which the above condition is for */
4382
4383 /**
4384 next_insert_id is the next value which should be inserted into the
4385 auto_increment column: in a inserting-multi-row statement (like INSERT
4386 SELECT), for the first row where the autoinc value is not specified by the
4387 statement, get_auto_increment() called and asked to generate a value,
4388 next_insert_id is set to the next value, then for all other rows
4389 next_insert_id is used (and increased each time) without calling
4390 get_auto_increment().
4391 */
4393 /**
4394 insert id for the current row (*autogenerated*; if not
4395 autogenerated, it's 0).
4396 At first successful insertion, this variable is stored into
4397 THD::first_successful_insert_id_in_cur_stmt.
4398 */
4400 /**
4401 Interval returned by get_auto_increment() and being consumed by the
4402 inserter.
4403 */
4405 /**
4406 Number of reserved auto-increment intervals. Serves as a heuristic
4407 when we have no estimation of how many records the statement will insert:
4408 the more intervals we have reserved, the bigger the next one. Reset in
4409 handler::ha_release_auto_increment().
4410 */
4412
4413 /**
4414 Instrumented table associated with this handler.
4415 */
4417
4420
4421 private:
4422 /** Internal state of the batch instrumentation. */
4424 /** Batch mode not used. */
4426 /** Batch mode used, before first table io. */
4428 /** Batch mode used, after first table io. */
4431 /**
4432 Batch mode state.
4433 @sa start_psi_batch_mode.
4434 @sa end_psi_batch_mode.
4435 */
4437 /**
4438 The number of rows in the batch.
4439 @sa start_psi_batch_mode.
4440 @sa end_psi_batch_mode.
4441 */
4443 /**
4444 The current event in a batch.
4445 @sa start_psi_batch_mode.
4446 @sa end_psi_batch_mode.
4447 */
4449 /**
4450 Storage for the event in a batch.
4451 @sa start_psi_batch_mode.
4452 @sa end_psi_batch_mode.
4453 */
4455
4456 public:
4457 void unbind_psi();
4458 void rebind_psi();
4459 /**
4460 Put the handler in 'batch' mode when collecting
4461 table io instrumented events.
4462 When operating in batch mode:
4463 - a single start event is generated in the performance schema.
4464 - all table io performed between @c start_psi_batch_mode
4465 and @c end_psi_batch_mode is not instrumented:
4466 the number of rows affected is counted instead in @c m_psi_numrows.
4467 - a single end event is generated in the performance schema
4468 when the batch mode ends with @c end_psi_batch_mode.
4469 */
4470 void start_psi_batch_mode();
4471 /** End a batch started with @c start_psi_batch_mode. */
4472 void end_psi_batch_mode();
4473 /**
4474 If a PSI batch was started, turn if off.
4475 @returns true if it was started.
4476 */
4478 bool rc = m_psi_batch_mode;
4479 if (rc) end_psi_batch_mode();
4480 return rc;
4481 }
4482
4483 private:
4484 /**
4485 The lock type set by when calling::ha_external_lock(). This is
4486 propagated down to the storage engine. The reason for also storing
4487 it here, is that when doing MRR we need to create/clone a second handler
4488 object. This cloned handler object needs to know about the lock_type used.
4489 */
4491 /**
4492 Pointer where to store/retrieve the Handler_share pointer.
4493 For non partitioned handlers this is &TABLE_SHARE::ha_share.
4494 */
4496
4497 /**
4498 Some non-virtual ha_* functions, responsible for reading rows,
4499 like ha_rnd_pos(), must ensure that virtual generated columns are
4500 calculated before they return. For that, they should set this
4501 member to true at their start, and check it before they return: if
4502 the member is still true, it means they should calculate; if it's
4503 false, it means the calculation has been done by some called
4504 lower-level function and does not need to be re-done (which is why
4505 we need this status flag: to avoid redundant calculations, for
4506 performance).
4507
4508 Note that when updating generated fields, the NULL row status in
4509 the underlying TABLE objects matter, so be sure to reset them if needed!
4510 */
4512
4513 /* Filter row ids to weed out duplicates when multi-valued index is used */
4515
4516 public:
4517 handler(handlerton *ht_arg, TABLE_SHARE *share_arg)
4518 : table_share(share_arg),
4519 table(nullptr),
4521 ht(ht_arg),
4522 ref(nullptr),
4528 ref_length(sizeof(my_off_t)),
4530 inited(NONE),
4531 implicit_emptied(false),
4535 next_insert_id(0),
4538 m_psi(nullptr),
4540 m_psi_numrows(0),
4542 m_lock_type(F_UNLCK),
4545 m_unique(nullptr) {
4546 DBUG_PRINT("info", ("handler created F_UNLCK %d F_RDLCK %d F_WRLCK %d",
4547 F_UNLCK, F_RDLCK, F_WRLCK));
4548 }
4549
4550 virtual ~handler(void) {
4551 assert(m_psi == nullptr);
4553 assert(m_psi_locker == nullptr);
4554 assert(m_lock_type == F_UNLCK);
4555 assert(inited == NONE);
4556 }
4557
4558 /**
4559 Return extra handler specific text for EXPLAIN.
4560 */
4561 virtual std::string explain_extra() const { return ""; }
4562
4563 /*
4564 @todo reorganize functions, make proper public/protected/private qualifiers
4565 */
4566 virtual handler *clone(const char *name, MEM_ROOT *mem_root);
4567 /** This is called after create to allow us to set up cached variables */
4569 /* ha_ methods: public wrappers for private virtual API */
4570
4571 /**
4572 Set a record buffer that the storage engine can use for multi-row reads.
4573 The buffer has to be provided prior to the first read from an index or a
4574 table.
4575
4576 @param buffer the buffer to use for multi-row reads
4577 */
4579
4580 /**
4581 Get the record buffer that was set with ha_set_record_buffer().
4582
4583 @return the buffer to use for multi-row reads, or nullptr if there is none
4584 */
4586
4587 /**
4588 Does this handler want to get a Record_buffer for multi-row reads
4589 via the ha_set_record_buffer() function? And if so, what is the
4590 maximum number of records to allocate space for in the buffer?
4591
4592 Storage engines that support using a Record_buffer should override
4593 handler::is_record_buffer_wanted().
4594
4595 @param[out] max_rows gets set to the maximum number of records to
4596 allocate space for in the buffer if the function
4597 returns true
4598
4599 @retval true if the handler would like a Record_buffer
4600 @retval false if the handler does not want a Record_buffer
4601 */
4602 bool ha_is_record_buffer_wanted(ha_rows *const max_rows) const {
4603 return is_record_buffer_wanted(max_rows);
4604 }
4605
4606 int ha_open(TABLE *table, const char *name, int mode, int test_if_locked,
4607 const dd::Table *table_def);
4608 int ha_close(void);
4609 int ha_index_init(uint idx, bool sorted);
4610 int ha_index_end();
4611 int ha_rnd_init(bool scan);
4612 int ha_rnd_end();
4613 int ha_rnd_next(uchar *buf);
4614 // See the comment on m_update_generated_read_fields.
4615 int ha_rnd_pos(uchar *buf, uchar *pos);
4616 int ha_index_read_map(uchar *buf, const uchar *key, key_part_map keypart_map,
4617 enum ha_rkey_function find_flag);
4619 key_part_map keypart_map);
4620 int ha_index_read_idx_map(uchar *buf, uint index, const uchar *key,
4621 key_part_map keypart_map,
4622 enum ha_rkey_function find_flag);
4623 int ha_index_next(uchar *buf);
4624 int ha_index_prev(uchar *buf);
4625 int ha_index_first(uchar *buf);
4626 int ha_index_last(uchar *buf);
4627 int ha_index_next_same(uchar *buf, const uchar *key, uint keylen);
4628 int ha_reset();
4629 /* this is necessary in many places, e.g. in HANDLER command */
4631 return inited == INDEX ? ha_index_end() : inited == RND ? ha_rnd_end() : 0;
4632 }
4633 /**
4634 The cached_table_flags is set at ha_open and ha_external_lock
4635 */
4637 /**
4638 These functions represent the public interface to *users* of the
4639 handler class, hence they are *not* virtual. For the inheritance
4640 interface, see the (private) functions write_row(), update_row(),
4641 and delete_row() below.
4642 */
4643 int ha_external_lock(THD *thd, int lock_type);
4644 int ha_write_row(uchar *buf);
4645 /**
4646 Update the current row.
4647
4648 @param old_data the old contents of the row
4649 @param new_data the new contents of the row
4650 @return error status (zero on success, HA_ERR_* error code on error)
4651 */
4652 int ha_update_row(const uchar *old_data, uchar *new_data);
4653 int ha_delete_row(const uchar *buf);
4655
4656 int ha_check_for_upgrade(HA_CHECK_OPT *check_opt);
4657 /** to be actually called to get 'check()' functionality*/
4658 int ha_check(THD *thd, HA_CHECK_OPT *check_opt);
4659 int ha_repair(THD *thd, HA_CHECK_OPT *check_opt);
4660 void ha_start_bulk_insert(ha_rows rows);
4661 int ha_end_bulk_insert();
4662 int ha_bulk_update_row(const uchar *old_data, uchar *new_data,
4663 uint *dup_key_found);
4664 int ha_delete_all_rows();
4666 int ha_optimize(THD *thd, HA_CHECK_OPT *check_opt);
4667 int ha_analyze(THD *thd, HA_CHECK_OPT *check_opt);
4668 bool ha_check_and_repair(THD *thd);
4672 int ha_rename_table(const char *from, const char *to,
4673 const dd::Table *from_table_def, dd::Table *to_table_def);
4674 int ha_delete_table(const char *name, const dd::Table *table_def);
4675 void ha_drop_table(const char *name);
4676
4677 int ha_create(const char *name, TABLE *form, HA_CREATE_INFO *info,
4679
4680 int ha_load_table(const TABLE &table);
4681
4682 int ha_unload_table(const char *db_name, const char *table_name,
4683 bool error_if_not_loaded);
4684
4685 /**
4686 Initializes a parallel scan. It creates a parallel_scan_ctx that has to
4687 be used across all parallel_scan methods. Also, gets the number of
4688 threads that would be spawned for parallel scan.
4689 @param[out] scan_ctx The parallel scan context.
4690 @param[out] num_threads Number of threads used for the scan.
4691 @param[in] use_reserved_threads true if reserved threads are to be used
4692 if we exhaust the max cap of number of
4693 parallel read threads that can be
4694 spawned at a time
4695 @return error code
4696 @retval 0 on success
4697 */
4698 virtual int parallel_scan_init(void *&scan_ctx [[maybe_unused]],
4699 size_t *num_threads [[maybe_unused]],
4700 bool use_reserved_threads [[maybe_unused]]) {
4701 return 0;
4702 }
4703
4704 /**
4705 This callback is called by each parallel load thread at the beginning of
4706 the parallel load for the adapter scan.
4707 @param cookie The cookie for this thread
4708 @param ncols Number of columns in each row
4709 @param row_len The size of a row in bytes
4710 @param col_offsets An array of size ncols, where each element represents
4711 the offset of a column in the row data. The memory of
4712 this array belongs to the caller and will be free-ed
4713 after the pload_end_cbk call.
4714 @param null_byte_offsets An array of size ncols, where each element
4715 represents the offset of a column in the row data. The
4716 memory of this array belongs to the caller and will be
4717 free-ed after the pload_end_cbk call.
4718 @param null_bitmasks An array of size ncols, where each element
4719 represents the bitmask required to get the null bit. The
4720 memory of this array belongs to the caller and will be
4721 free-ed after the pload_end_cbk call.
4722 */
4723 using Load_init_cbk = std::function<bool(
4724 void *cookie, ulong ncols, ulong row_len, const ulong *col_offsets,
4725 const ulong *null_byte_offsets, const ulong *null_bitmasks)>;
4726
4727 /**
4728 This callback is called by each parallel load thread when processing
4729 of rows is required for the adapter scan.
4730 @param[in] cookie The cookie for this thread
4731 @param[in] nrows The nrows that are available
4732 @param[in] rowdata The mysql-in-memory row data buffer. This is a
4733 memory buffer for nrows records. The length of each record is fixed and
4734 communicated via Load_init_cbk
4735 @param[in] partition_id Partition id if it's a partitioned table, else
4736 std::numeric_limits<uint64_t>::max()
4737 @returns true if there is an error, false otherwise.
4738 */
4739 using Load_cbk = std::function<bool(void *cookie, uint nrows, void *rowdata,
4740 uint64_t partition_id)>;
4741
4742 /**
4743 This callback is called by each parallel load thread when processing
4744 of rows has ended for the adapter scan.
4745 @param[in] cookie The cookie for this thread
4746 */
4747 using Load_end_cbk = std::function<void(void *cookie)>;
4748
4749 /**
4750 Run the parallel read of data.
4751 @param[in] scan_ctx Scan context of the parallel read.
4752 @param[in,out] thread_ctxs Caller thread contexts.
4753 @param[in] init_fn Callback called by each parallel load
4754 thread at the beginning of the parallel load.
4755 @param[in] load_fn Callback called by each parallel load
4756 thread when processing of rows is required.
4757 @param[in] end_fn Callback called by each parallel load
4758 thread when processing of rows has ended.
4759 @return error code
4760 @retval 0 on success
4761 */
4762 virtual int parallel_scan(void *scan_ctx [[maybe_unused]],
4763 void **thread_ctxs [[maybe_unused]],
4764 Load_init_cbk init_fn [[maybe_unused]],
4765 Load_cbk load_fn [[maybe_unused]],
4766 Load_end_cbk end_fn [[maybe_unused]]) {
4767 return 0;
4768 }
4769
4770 /**
4771 End of the parallel scan.
4772 @param[in] scan_ctx A scan context created by parallel_scan_init.
4773 */
4774 virtual void parallel_scan_end(void *scan_ctx [[maybe_unused]]) { return; }
4775
4776 /**
4777 Submit a dd::Table object representing a core DD table having
4778 hardcoded data to be filled in by the DDSE. This function can be
4779 used for retrieving the hard coded SE private data for the
4780 mysql.dd_properties table, before creating or opening it, or for
4781 retrieving the hard coded SE private data for a core table,
4782 before creating or opening them.
4783
4784 @param dd_table [in,out] A dd::Table object representing
4785 a core DD table.
4786 @param reset Reset counters.
4787
4788 @retval true An error occurred.
4789 @retval false Success - no errors.
4790 */
4791
4792 bool ha_get_se_private_data(dd::Table *dd_table, bool reset);
4793
4796 virtual void print_error(int error, myf errflag);
4797 virtual bool get_error_message(int error, String *buf);
4798 uint get_dup_key(int error);
4799 /**
4800 Retrieves the names of the table and the key for which there was a
4801 duplicate entry in the case of HA_ERR_FOREIGN_DUPLICATE_KEY.
4802
4803 If any of the table or key name is not available this method will return
4804 false and will not change any of child_table_name or child_key_name.
4805
4806 @param [out] child_table_name Table name
4807 @param [in] child_table_name_len Table name buffer size
4808 @param [out] child_key_name Key name
4809 @param [in] child_key_name_len Key name buffer size
4810
4811 @retval true table and key names were available
4812 and were written into the corresponding
4813 out parameters.
4814 @retval false table and key names were not available,
4815 the out parameters were not touched.
4816 */
4817 virtual bool get_foreign_dup_key(char *child_table_name,
4818 uint child_table_name_len,
4819 char *child_key_name,
4820 uint child_key_name_len);
4821 /**
4822 Change the internal TABLE_SHARE pointer.
4823
4824 @param table_arg TABLE object
4825 @param share New share to use
4826
4827 @note Is used in error handling in ha_delete_table.
4828 */
4829
4830 virtual void change_table_ptr(TABLE *table_arg, TABLE_SHARE *share) {
4831 table = table_arg;
4832 table_share = share;
4833 }
4834 const TABLE_SHARE *get_table_share() const { return table_share; }
4835
4836 /* Estimates calculation */
4837
4838 /**
4839 @deprecated This function is deprecated and will be removed in a future
4840 version. Use table_scan_cost() instead.
4841 */
4842
4843 virtual double scan_time() {
4844 return ulonglong2double(stats.data_file_length) / IO_SIZE + 2;
4845 }
4846
4847 /**
4848 The cost of reading a set of ranges from the table using an index
4849 to access it.
4850
4851 @deprecated This function is deprecated and will be removed in a future
4852 version. Use read_cost() instead.
4853
4854 @param index The index number.
4855 @param ranges The number of ranges to be read.
4856 @param rows Total number of rows to be read.
4857
4858 This method can be used to calculate the total cost of scanning a table
4859 using an index by calling it using read_time(index, 1, table_size).
4860 */
4861
4862 virtual double read_time(uint index [[maybe_unused]], uint ranges,
4863 ha_rows rows) {
4864 return rows2double(ranges + rows);
4865 }
4866
4867 /**
4868 @deprecated This function is deprecated and will be removed in a future
4869 version. Use index_scan_cost() instead.
4870 */
4871
4872 virtual double index_only_read_time(uint keynr, double records);
4873
4874 /**
4875 Cost estimate for doing a complete table scan.
4876
4877 @note For this version it is recommended that storage engines continue
4878 to override scan_time() instead of this function.
4879
4880 @returns the estimated cost
4881 */
4882
4884
4885 /**
4886 Cost estimate for reading a number of ranges from an index.
4887
4888 The cost estimate will only include the cost of reading data that
4889 is contained in the index. If the records need to be read, use
4890 read_cost() instead.
4891
4892 @note The ranges parameter is currently ignored and is not taken
4893 into account in the cost estimate.
4894
4895 @note For this version it is recommended that storage engines continue
4896 to override index_only_read_time() instead of this function.
4897
4898 @param index the index number
4899 @param ranges the number of ranges to be read
4900 @param rows total number of rows to be read
4901
4902 @returns the estimated cost
4903 */
4904
4905 virtual Cost_estimate index_scan_cost(uint index, double ranges, double rows);
4906
4907 /**
4908 Cost estimate for reading a set of ranges from the table using an index
4909 to access it.
4910
4911 @note For this version it is recommended that storage engines continue
4912 to override read_time() instead of this function.
4913
4914 @param index the index number
4915 @param ranges the number of ranges to be read
4916 @param rows total number of rows to be read
4917
4918 @returns the estimated cost
4919 */
4920
4921 virtual Cost_estimate read_cost(uint index, double ranges, double rows);
4922
4923 /**
4924 Cost estimate for doing a number of non-sequentially accesses
4925 against the storage engine. Such accesses can be either number
4926 of rows to read, or number of disk pages to access.
4927 Each handler implementation is free to interpret that as best
4928 suited, depending on what is the dominating cost for that
4929 storage engine.
4930
4931 This method is mainly provided as a temporary workaround for
4932 bug#33317872, where we fix problems caused by calling
4933 Cost_model::page_read_cost() directly from the optimizer.
4934 That should be avoided, as it introduced assumption about all
4935 storage engines being disk-page based, and having a 'page' cost.
4936 Furthermore, this page cost was even compared against read_cost(),
4937 which was computed with an entirely different algorithm, and thus
4938 could not be compared.
4939
4940 The default implementation still call Cost_model::page_read_cost(),
4941 thus behaving just as before. However, handler implementation may
4942 override it to call handler::read_cost() instead(), which probably
4943 will be more correct. (If a page_read_cost should be included
4944 in the cost estimate, that should preferable be done inside
4945 each read_cost() implementation)
4946
4947 Longer term we should consider to remove all page_read_cost()
4948 usage from the optimizer itself, making this method obsolete.
4949
4950 @param index the index number
4951 @param reads the number of accesses being made
4952
4953 @returns the estimated cost
4954 */
4955 virtual double page_read_cost(uint index, double reads);
4956
4957 /**
4958 Provide an upper cost-limit of doing a specified number of
4959 seek-and-read key lookups. This need to be comparable and
4960 calculated with the same 'metric' as page_read_cost.
4961
4962 @param reads the number of rows read in the 'worst' case.
4963
4964 @returns the estimated cost
4965 */
4966 virtual double worst_seek_times(double reads);
4967
4968 /**
4969 Return an estimate on the amount of memory the storage engine will
4970 use for caching data in memory. If this is unknown or the storage
4971 engine does not cache data in memory -1 is returned.
4972 */
4973 virtual longlong get_memory_buffer_size() const { return -1; }
4974
4975 /**
4976 Return an estimate of how much of the table that is currently stored
4977 in main memory.
4978
4979 This estimate should be the fraction of the table that currently
4980 is available in a main memory buffer. The estimate should be in the
4981 range from 0.0 (nothing in memory) to 1.0 (entire table in memory).
4982
4983 @return The fraction of the table in main memory buffer
4984 */
4985
4986 double table_in_memory_estimate() const;
4987
4988 /**
4989 Return an estimate of how much of the index that is currently stored
4990 in main memory.
4991
4992 This estimate should be the fraction of the index that currently
4993 is available in a main memory buffer. The estimate should be in the
4994 range from 0.0 (nothing in memory) to 1.0 (entire index in memory).
4995
4996 @param keyno the index to get an estimate for
4997
4998 @return The fraction of the index in main memory buffer
4999 */
5000
5001 double index_in_memory_estimate(uint keyno) const;
5002
5003 /**
5004 Initialize sampling.
5005
5006 @param[out] scan_ctx A scan context created by this method that has to be
5007 used in sample_next
5008 @param[in] sampling_percentage percentage of records that need to be
5009 sampled
5010 @param[in] sampling_seed random seed that the random generator will
5011 use
5012 @param[in] sampling_method sampling method to be used; currently only
5013 SYSTEM sampling is supported
5014 @param[in] tablesample true if the sampling is for tablesample
5015
5016 @return 0 for success, else one of the HA_xxx values in case of error.
5017 */
5018 int ha_sample_init(void *&scan_ctx, double sampling_percentage,
5019 int sampling_seed, enum_sampling_method sampling_method,
5020 const bool tablesample);
5021
5022 /**
5023 Get the next record for sampling.
5024
5025 @param[in] scan_ctx Scan context of the sampling
5026 @param[in] buf buffer to place the read record
5027
5028 @return 0 for success, else one of the HA_xxx values in case of error.
5029 */
5030 int ha_sample_next(void *scan_ctx, uchar *buf);
5031
5032 /**
5033 End sampling.
5034
5035 @param[in] scan_ctx Scan context of the sampling
5036
5037 @return 0 for success, else one of the HA_xxx values in case of error.
5038 */
5039 int ha_sample_end(void *scan_ctx);
5040
5041 private:
5043
5044 /**
5045 Make a guesstimate for how much of a table or index is in a memory
5046 buffer in the case where the storage engine has not provided any
5047 estimate for this.
5048
5049 @param table_index_size size of the table or index