MySQL 8.0.32
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;
101class Table_ref;
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
932enum ha_ddl_type : int {
938
939/** Clone start operation mode */
941 /** Start a new clone operation */
943
944 /** Re-start a clone operation after failure */
946
947 /** Add a new task to a running clone operation */
949
950 /** Get version for transfer data format */
952
953 /** Max value for clone mode */
956
957/** Clone operation types. */
958enum Ha_clone_type : size_t {
959 /** Caller must block all write operation to the SE. */
961
962 /** For transactional SE, archive redo to support concurrent dml */
964
965 /** For transactional SE, track page changes to support concurrent dml */
967
968 /** For transactional SE, use both page tracking and redo to optimize
969 clone with concurrent dml. Currently supported by Innodb. */
971
972 /** SE supports multiple threads for clone */
974
975 /** SE supports restarting clone after network failure */
977
978 /** Maximum value of clone type */
981
982using Ha_clone_flagset = std::bitset<HA_CLONE_TYPE_MAX>;
983
986
987/** File reference for clone */
989 /** File reference type */
990 enum {
991 /** File handle */
993
994 /** File descriptor */
996
998
999 /** File reference */
1000 union {
1001 /** File descriptor */
1003
1004 /** File handle for windows */
1006 };
1007};
1008
1009/* Abstract callback interface to stream data back to the caller. */
1011 protected:
1012 /** Constructor to initialize members. */
1014 : m_hton(),
1015 m_loc_idx(),
1017 m_data_desc(),
1018 m_desc_len(),
1019 m_src_name(),
1020 m_dest_name(),
1022 m_flag() {}
1023
1024 public:
1025 /** Callback providing data from current position of a
1026 file descriptor of specific length.
1027 @param[in] from_file source file to read from
1028 @param[in] len data length
1029 @return error code */
1030 virtual int file_cbk(Ha_clone_file from_file, uint len) = 0;
1031
1032 /** Callback providing data in buffer of specific length.
1033 @param[in] from_buffer source buffer to read from
1034 @param[in] len data length
1035 @return error code */
1036 virtual int buffer_cbk(uchar *from_buffer, uint len) = 0;
1037
1038 /** Callback providing a file descriptor to write data starting
1039 from current position.
1040 @param[in] to_file destination file to write data
1041 @return error code */
1042 virtual int apply_file_cbk(Ha_clone_file to_file) = 0;
1043
1044 /** Callback to get data in buffer.
1045 @param[out] to_buffer data buffer
1046 @param[out] len data length
1047 @return error code */
1048 virtual int apply_buffer_cbk(uchar *&to_buffer, uint &len) = 0;
1049
1050 /** virtual destructor. */
1051 virtual ~Ha_clone_cbk() = default;
1052
1053 /** Set current storage engine handlerton.
1054 @param[in] hton SE handlerton */
1055 void set_hton(handlerton *hton) { m_hton = hton; }
1056
1057 /** Get current storage engine handlerton.
1058 @return SE handlerton */
1059 handlerton *get_hton() { return (m_hton); }
1060
1061 /** Set caller's transfer buffer size. SE can adjust the data chunk size
1062 based on this parameter.
1063 @param[in] size buffer size in bytes */
1065
1066 /** Get caller's transfer buffer size.
1067 @return buffer size in bytes */
1069
1070 /** Set current SE index.
1071 @param[in] idx SE index in locator array */
1072 void set_loc_index(uint idx) { m_loc_idx = idx; }
1073
1074 /** Get current SE index.
1075 @return SE index in locator array */
1077
1078 /** Set data descriptor. SE specific descriptor for the
1079 data transferred by the callbacks.
1080 @param[in] desc serialized data descriptor
1081 @param[in] len length of the descriptor byte stream */
1082 void set_data_desc(const uchar *desc, uint len) {
1083 m_data_desc = desc;
1084 m_desc_len = len;
1085 }
1086
1087 /** Get data descriptor. SE specific descriptor for the
1088 data transferred by the callbacks.
1089 @param[out] lenp length of the descriptor byte stream
1090 @return pointer to the serialized data descriptor */
1091 const uchar *get_data_desc(uint *lenp) {
1092 if (lenp != nullptr) {
1093 *lenp = m_desc_len;
1094 }
1095
1096 return (m_data_desc);
1097 }
1098
1099 /** Get SE source file name. Used for debug printing and error message.
1100 @return null terminated string for source file name */
1101 const char *get_source_name() { return (m_src_name); }
1102
1103 /** Set SE source file name.
1104 @param[in] name null terminated string for source file name */
1105 void set_source_name(const char *name) { m_src_name = name; }
1106
1107 /** Get SE destination file name. Used for debug printing and error message.
1108 @return null terminated string for destination file name */
1109 const char *get_dest_name() { return (m_dest_name); }
1110
1111 /** Set SE destination file name.
1112 @param[in] name null terminated string for destination file name */
1113 void set_dest_name(const char *name) { m_dest_name = name; }
1114
1115 /** Clear all flags set by SE */
1116 void clear_flags() { m_flag = 0; }
1117
1118 /** Mark that ACK is needed for the data transfer before returning
1119 from callback. Set by SE. */
1121
1122 /** Check if ACK is needed for the data transfer
1123 @return true if ACK is needed */
1124 bool is_ack_needed() const { return (m_flag & HA_CLONE_ACK); }
1125
1126 /** Mark that the file descriptor is opened for read/write
1127 with OS buffer cache. For O_DIRECT, the flag is not set. */
1129
1130 /** Check if the file descriptor is opened for read/write with OS
1131 buffer cache. Currently clone avoids using zero copy (sendfile on linux),
1132 if SE is using O_DIRECT. This improves data copy performance.
1133 @return true if O_DIRECT is not used */
1134 bool is_os_buffer_cache() const { return (m_flag & HA_CLONE_FILE_CACHE); }
1135
1136 /** Mark that the file can be transferred with zero copy. */
1138
1139 /** Check if zero copy optimization is suggested. */
1140 bool is_zero_copy() const { return (m_flag & HA_CLONE_ZERO_COPY); }
1141
1142 /** Mark that data needs secure transfer. */
1144
1145 /** Check if data needs secure transfer. */
1146 bool is_secure() const { return (m_flag & HA_CLONE_SECURE); }
1147
1148 /** Set state information and notify state change.
1149 @param[in] estimate estimated bytes for current state. */
1150 void mark_state_change(uint64_t estimate) {
1152 m_state_estimate = estimate;
1153 }
1154
1155 /** Check if SE notified state change. */
1156 bool is_state_change(uint64_t &estimate) {
1157 estimate = m_state_estimate;
1158 return (m_flag & HA_CLONE_STATE_CHANGE);
1159 }
1160
1161 private:
1162 /** Handlerton for the SE */
1164
1165 /** SE index in caller's locator array */
1167
1168 /** Caller's transfer buffer size. */
1170
1171 /** SE's Serialized data descriptor */
1173
1174 /** SE's Serialized descriptor length. */
1176
1177 /** Current source file name */
1178 const char *m_src_name;
1179
1180 /** Current destination file name */
1181 const char *m_dest_name;
1182
1183 /** Estimated bytes to be transferred. */
1185
1186 /** Flag storing data related options */
1188
1189 /** Acknowledgement is needed for the data transfer. */
1190 const int HA_CLONE_ACK = 0x01;
1191
1192 /** Data file is opened for read/write with OS buffer cache. */
1193 const int HA_CLONE_FILE_CACHE = 0x02;
1194
1195 /** Data file can be transferred with zero copy. */
1196 const int HA_CLONE_ZERO_COPY = 0x04;
1197
1198 /** Data needs to be transferred securely over SSL connection. */
1199 const int HA_CLONE_SECURE = 0x08;
1200
1201 /** State change notification by SE. */
1202 const int HA_CLONE_STATE_CHANGE = 0x10;
1203};
1204
1205/**
1206 Column type description for foreign key columns compatibility check.
1207
1208 Contains subset of information from dd::Column class. It is inconvenient
1209 to use dd::Column class directly for such checks because it requires valid
1210 dd::Table object and in some cases we want to produce Ha_fk_column_type
1211 right from column description in Create_field format.
1212*/
1215 /*
1216 Note that both dd::Column::char_length() and length here are really
1217 in bytes.
1218 */
1224};
1225
1226typedef ulonglong my_xid; // this line is the same as in log_event.h
1227/**
1228 Enumeration of possible states for externally coordinated transactions (XA).
1229 */
1231 NOT_FOUND = -1, // Trnasaction not found
1232 PREPARED_IN_SE = 0, // Transaction is prepared in SEs
1233 PREPARED_IN_TC = 1, // Transaction is prepared in SEs and TC
1234 COMMITTED_WITH_ONEPHASE = 2, // Transaction was one-phase committed
1235 COMMITTED = 3, // Transaction was committed
1236 ROLLEDBACK = 4 // Transaction was rolled back
1237};
1238/**
1239 Single occurrence set of XIDs of internally coordinated transactions
1240 found as been committed in the transaction coordinator state.
1241 */
1243 std::unordered_set<my_xid, std::hash<my_xid>, std::equal_to<my_xid>,
1245
1246/**
1247 Class to maintain list of externally coordinated transactions and their
1248 current state at recovery.
1249 */
1251 public:
1252 using pair = std::pair<const XID, enum_ha_recover_xa_state>;
1254 using list = std::map<XID, enum_ha_recover_xa_state, std::less<XID>,
1256 using iterator = std::map<XID, enum_ha_recover_xa_state, std::less<XID>,
1258 using instantiation_tuple = std::tuple<
1259 std::unique_ptr<MEM_ROOT>, std::unique_ptr<Xa_state_list::allocator>,
1260 std::unique_ptr<Xa_state_list::list>, std::unique_ptr<Xa_state_list>>;
1261
1262 /**
1263 Class constructor.
1264
1265 @param populated_by_tc The underlying list of XIDs and transaction
1266 states, after being populated by the transaction
1267 coodinator.
1268 */
1269 Xa_state_list(Xa_state_list::list &populated_by_tc);
1270 virtual ~Xa_state_list() = default;
1271
1272 /**
1273 Searches the underlying map to find an key that corresponds to the
1274 parameter.
1275
1276 @param to_find The XID to find within the underlying map.
1277
1278 @return Ha_recover_states::NOT_FOUND if the transaction wasn't found,
1279 the state of the transaction, otherwise.
1280 */
1281 enum_ha_recover_xa_state find(XID const &to_find);
1282 /**
1283 Adds a transaction and state to the underlying map. If the given XID
1284 already exists in the underlying map, the associated state changes according
1285 to the following rules:
1286
1287 - If the parameter state is `PREPARED_IN_SE` it means that the
1288 transaction didn't reach PREPARED_IN_TC, COMMIT or ROLLBACK for
1289 sure. In that case:
1290 . If other participants state is `COMMITTED`/`ROLLEDBACK`, it would
1291 mean that it's a state inherited from a previous execution with the
1292 same XID and we should set the state to `PREPARED_IN_SE`.
1293 . If other participants state is `PREPARED_IN_TC`/
1294 `COMMITTED_WITH_ONEPHASE` it means that the current participant
1295 didn't reach it but some other did so, keep the state as
1296 `PREPARED_IN_TC`/`COMMITTED_WITH_ONEPHASE`.
1297
1298 - If the parameter state is `PREPARED_IN_TC`, it means that other
1299 participants must have persisted either the PREPARE, the COMMIT or
1300 the ROLLBACK. In that case, keep whatever state is already there and
1301 ensure that is not `PREPARED_IN_SE`.
1302
1303 - If the parameter state is `COMMITTED_WITH_ONEPHASE`, `COMMITTED` or
1304 `ROLLEDBACK`, do nothing, only the active transaction coordinator has
1305 the ability, for now, to set the transaction state to those values.
1306
1307 @param xid The XID to be added (the key).
1308 @param xid The state to be added (the value).
1309
1310 @return The current value of the transaction state if the XID has
1311 already been added, Ha_recover_states::NOT_FOUND otherwise.
1312 */
1314 /**
1315 Factory like method to instantiate all the infra-structure needed to
1316 create an `Xa_state_list`. Since such infra-structuer is dependent on
1317 `MEM_ROOT` and `Mem_root_allocator`, the method returns a tuple
1318 containing unique pointers to all 4 objects needed: MEM_ROOT;
1319 Mem_root_allocator; Xa_state_list::list; Xa_state_list.
1320
1321 @return An std::tuple containing unique pointers to all 4 objects
1322 needed: MEM_ROOT; Mem_root_allocator; Xa_state_list::list;
1323 Xa_state_list.
1324 */
1326
1327 private:
1328 /** The underlying map holding the trx and states*/
1330};
1331
1332/* handlerton methods */
1333
1334/**
1335 close_connection is only called if
1336 thd->ha_data[xxx_hton.slot] is non-zero, so even if you don't need
1337 this storage area - set it to something, so that MySQL would know
1338 this storage engine was accessed in this connection
1339*/
1340typedef int (*close_connection_t)(handlerton *hton, THD *thd);
1341
1342/** Terminate connection/statement notification. */
1343typedef void (*kill_connection_t)(handlerton *hton, THD *thd);
1344
1345/**
1346 Shut down all storage engine background tasks that might access
1347 the data dictionary, before the main shutdown.
1348*/
1349typedef void (*pre_dd_shutdown_t)(handlerton *hton);
1350
1351/**
1352 sv points to a storage area, that was earlier passed
1353 to the savepoint_set call
1354*/
1355typedef int (*savepoint_rollback_t)(handlerton *hton, THD *thd, void *sv);
1356
1357/**
1358 sv points to an uninitialized storage area of requested size
1359 (see savepoint_offset description)
1360*/
1361typedef int (*savepoint_set_t)(handlerton *hton, THD *thd, void *sv);
1362
1363/**
1364 Check if storage engine allows to release metadata locks which were
1365 acquired after the savepoint if rollback to savepoint is done.
1366 @return true - If it is safe to release MDL locks.
1367 false - If it is not.
1368*/
1370 THD *thd);
1371
1372typedef int (*savepoint_release_t)(handlerton *hton, THD *thd, void *sv);
1373
1374/**
1375 'all' is true if it's a real commit, that makes persistent changes
1376 'all' is false if it's not in fact a commit but an end of the
1377 statement that is part of the transaction.
1378 NOTE 'all' is also false in auto-commit mode where 'end of statement'
1379 and 'real commit' mean the same event.
1380*/
1381typedef int (*commit_t)(handlerton *hton, THD *thd, bool all);
1382
1383typedef int (*rollback_t)(handlerton *hton, THD *thd, bool all);
1384
1385typedef int (*prepare_t)(handlerton *hton, THD *thd, bool all);
1386
1387typedef int (*recover_t)(handlerton *hton, XA_recover_txn *xid_list, uint len,
1389/**
1390 Retrieves information about externally coordinated transactions for which
1391 the two-phase prepare was finished and transactions were prepared in the
1392 server TC.
1393 */
1395 Xa_state_list &xa_list);
1396/**
1397 Instructs the storage engine to mark the externally coordinated
1398 transactions held by the THD parameters as prepared in the server TC.
1399 */
1400using set_prepared_in_tc_t = int (*)(handlerton *hton, THD *thd);
1401
1402/** X/Open XA distributed transaction status codes */
1404 /**
1405 normal execution
1406 */
1408
1409 /**
1410 asynchronous operation already outstanding
1411 */
1413
1414 /**
1415 a resource manager error occurred in the transaction branch
1416 */
1418
1419 /**
1420 the XID is not valid
1421 */
1423
1424 /**
1425 invalid arguments were given
1426 */
1428
1429 /**
1430 routine invoked in an improper context
1431 */
1433
1434 /**
1435 resource manager unavailable
1436 */
1438
1439 /**
1440 the XID already exists
1441 */
1443
1444 /**
1445 resource manager doing work outside transaction
1446 */
1447 XAER_OUTSIDE = -9
1449
1451
1453
1454/**
1455 Instructs the storage engine to mark the externally coordinated
1456 transactions identified by the XID parameters as prepared in the server
1457 TC.
1458 */
1460 XID *xid);
1461
1462/**
1463 Create handler object for the table in the storage engine.
1464
1465 @param hton Handlerton object for the storage engine.
1466 @param table TABLE_SHARE for the table, can be NULL if caller
1467 didn't perform full-blown open of table definition.
1468 @param partitioned Indicates whether table is partitioned.
1469 @param mem_root Memory root to be used for allocating handler
1470 object.
1471*/
1472typedef handler *(*create_t)(handlerton *hton, TABLE_SHARE *table,
1473 bool partitioned, MEM_ROOT *mem_root);
1474
1475typedef void (*drop_database_t)(handlerton *hton, char *path);
1476
1477typedef int (*panic_t)(handlerton *hton, enum ha_panic_function flag);
1478
1479typedef int (*start_consistent_snapshot_t)(handlerton *hton, THD *thd);
1480
1481/**
1482 Flush the log(s) of storage engine(s).
1483
1484 @param hton Handlerton of storage engine.
1485 @param binlog_group_flush true if we got invoked by binlog group
1486 commit during flush stage, false in other cases.
1487 @retval false Succeed
1488 @retval true Error
1489*/
1490typedef bool (*flush_logs_t)(handlerton *hton, bool binlog_group_flush);
1491
1492typedef bool (*show_status_t)(handlerton *hton, THD *thd, stat_print_fn *print,
1493 enum ha_stat_type stat);
1494
1495/**
1496 The flag values are defined in sql_partition.h.
1497 If this function is set, then it implies that the handler supports
1498 partitioned tables.
1499 If this function exists, then handler::get_partition_handler must also be
1500 implemented.
1501*/
1503
1504/**
1505 SE specific validation of the tablespace name.
1506
1507 This function will ask the relevant SE whether the submitted tablespace
1508 name is valid.
1509
1510 @param ts_cmd Purpose of usage - is this tablespace DDL?
1511 @param tablespace_name Name of the tablespace.
1512
1513 @return Tablespace name validity.
1514 @retval Whether the tablespace name is valid.
1515*/
1517 const char *tablespace_name);
1518
1519/**
1520 Get the tablespace name from the SE for the given schema and table.
1521
1522 @param thd Thread context.
1523 @param db_name Name of the relevant schema.
1524 @param table_name Name of the relevant table.
1525 @param [out] tablespace_name Name of the tablespace containing the table.
1526
1527 @return Operation status.
1528 @retval == 0 Success.
1529 @retval != 0 Error (handler error code returned).
1530*/
1533 LEX_CSTRING *tablespace_name);
1534
1535/**
1536 Create/drop or alter tablespace in the storage engine.
1537
1538 @param hton Hadlerton of the SE.
1539 @param thd Thread context.
1540 @param ts_info Description of tablespace and specific
1541 operation on it.
1542 @param old_ts_def dd::Tablespace object describing old version
1543 of tablespace.
1544 @param [in,out] new_ts_def dd::Tablespace object describing new version
1545 of tablespace. Engines which support atomic DDL
1546 can adjust this object. The updated information
1547 will be saved to the data-dictionary.
1548
1549 @return Operation status.
1550 @retval == 0 Success.
1551 @retval != 0 Error (handler error code returned).
1552*/
1553typedef int (*alter_tablespace_t)(handlerton *hton, THD *thd,
1554 st_alter_tablespace *ts_info,
1555 const dd::Tablespace *old_ts_def,
1556 dd::Tablespace *new_ts_def);
1557
1558/**
1559 SE interface for getting tablespace extension.
1560 @return Extension of tablespace datafile name.
1561*/
1562typedef const char *(*get_tablespace_filename_ext_t)();
1563
1564/**
1565 Get the tablespace data from SE and insert it into Data dictionary
1566
1567 @param thd Thread context
1568
1569 @return Operation status.
1570 @retval == 0 Success.
1571 @retval != 0 Error (handler error code returned)
1572*/
1573typedef int (*upgrade_tablespace_t)(THD *thd);
1574
1575/**
1576 Get the tablespace data from SE and insert it into Data dictionary
1577
1578 @param[in] tablespace tablespace object
1579
1580 @return Operation status.
1581 @retval == 0 Success.
1582 @retval != 0 Error (handler error code returned)
1583*/
1584typedef bool (*upgrade_space_version_t)(dd::Tablespace *tablespace);
1585
1586/**
1587 Finish upgrade process inside storage engines.
1588 This includes resetting flags to indicate upgrade process
1589 and cleanup after upgrade.
1590
1591 @param thd Thread context
1592 @param failed_upgrade True if the upgrade failed.
1593
1594 @return Operation status.
1595 @retval == 0 Success.
1596 @retval != 0 Error (handler error code returned)
1597*/
1598typedef int (*finish_upgrade_t)(THD *thd, bool failed_upgrade);
1599
1600/**
1601 Upgrade logs after the checkpoint from where upgrade
1602 process can only roll forward.
1603
1604 @param thd Thread context
1605
1606 @return Operation status.
1607 @retval == 0 Success.
1608 @retval != 0 Error (handler error code returned)
1609*/
1610typedef int (*upgrade_logs_t)(THD *thd);
1611
1619};
1620
1621/**
1622 Get the tablespace type from the SE.
1623
1624 @param[in] space tablespace object
1625 @param[out] space_type type of space
1626
1627 @return Operation status.
1628 @retval false on success and true for failure.
1629*/
1630typedef bool (*get_tablespace_type_t)(const dd::Tablespace &space,
1631 Tablespace_type *space_type);
1632
1633/**
1634 Get the tablespace type given the name, from the SE.
1635
1636 @param[in] tablespace_name tablespace name
1637 @param[out] space_type type of space
1638
1639 @return Operation status.
1640 @retval false on success and true for failure.
1641*/
1642typedef bool (*get_tablespace_type_by_name_t)(const char *tablespace_name,
1643 Tablespace_type *space_type);
1644
1645typedef int (*fill_is_table_t)(handlerton *hton, THD *thd, Table_ref *tables,
1646 class Item *cond, enum enum_schema_tables);
1647
1648typedef int (*binlog_func_t)(handlerton *hton, THD *thd, enum_binlog_func fn,
1649 void *arg);
1650
1651typedef void (*binlog_log_query_t)(handlerton *hton, THD *thd,
1652 enum_binlog_command binlog_command,
1653 const char *query, uint query_length,
1654 const char *db, const char *table_name);
1655
1656typedef void (*acl_notify_t)(THD *thd,
1657 const class Acl_change_notification *notice);
1658
1659typedef int (*discover_t)(handlerton *hton, THD *thd, const char *db,
1660 const char *name, uchar **frmblob, size_t *frmlen);
1661
1662typedef int (*find_files_t)(handlerton *hton, THD *thd, const char *db,
1663 const char *path, const char *wild, bool dir,
1664 List<LEX_STRING> *files);
1665
1666typedef int (*table_exists_in_engine_t)(handlerton *hton, THD *thd,
1667 const char *db, const char *name);
1668
1669/**
1670 Let storage engine inspect the query Accesspath and pick whatever
1671 it like for being pushed down to the engine. (Join, conditions, ..)
1672
1673 The handler implementation should itself keep track of what it 'pushed',
1674 such that later calls to the handlers access methods should
1675 activate the pushed parts of the execution plan on the storage
1676 engines.
1677
1678 @param thd Thread context
1679 @param query The AccessPath for the entire query.
1680 @param join The JOIN to be pushed
1681
1682 @returns
1683 0 on success
1684 error otherwise
1685*/
1686using push_to_engine_t = int (*)(THD *thd, AccessPath *query, JOIN *);
1687
1688/**
1689 Check if the given db.tablename is a system table for this SE.
1690
1691 @param db Database name to check.
1692 @param table_name table name to check.
1693 @param is_sql_layer_system_table if the supplied db.table_name is a SQL
1694 layer system table.
1695
1696 @see example_is_supported_system_table in ha_example.cc
1697
1698 is_sql_layer_system_table is supplied to make more efficient
1699 checks possible for SEs that support all SQL layer tables.
1700
1701 This interface is optional, so every SE need not implement it.
1702*/
1703typedef bool (*is_supported_system_table_t)(const char *db,
1704 const char *table_name,
1705 bool is_sql_layer_system_table);
1706
1707/**
1708 Create SDI in a tablespace. This API should be used when upgrading
1709 a tablespace with no SDI or after invoking sdi_drop().
1710 @param[in] tablespace tablespace object
1711 @retval false success
1712 @retval true failure
1713*/
1714typedef bool (*sdi_create_t)(dd::Tablespace *tablespace);
1715
1716/**
1717 Drop SDI in a tablespace. This API should be used only when
1718 SDI is corrupted.
1719 @param[in] tablespace tablespace object
1720 @retval false success
1721 @retval true failure
1722*/
1723typedef bool (*sdi_drop_t)(dd::Tablespace *tablespace);
1724
1725/**
1726 Get the SDI keys in a tablespace into vector.
1727 @param[in] tablespace tablespace object
1728 @param[in,out] vector vector of SDI Keys
1729 @retval false success
1730 @retval true failure
1731*/
1732typedef bool (*sdi_get_keys_t)(const dd::Tablespace &tablespace,
1734
1735/**
1736 Retrieve SDI for a given SDI key.
1737
1738 Since the caller of this api will not know the SDI length, SDI retrieval
1739 should be done in the following way.
1740
1741 i. Allocate initial memory of some size (Lets say 64KB)
1742 ii. Pass the allocated memory to the below api.
1743 iii. If passed buffer is sufficient, sdi_get_by_id() copies the sdi
1744 to the buffer passed and returns success, else sdi_len is modified
1745 with the actual length of the SDI (and returns false on failure).
1746 For genuine errors, sdi_len is returned as UINT64_MAX
1747 iv. If sdi_len != UINT64_MAX, retry the call after allocating the memory
1748 of sdi_len
1749 v. Free the memory after using SDI (responsibility of caller)
1750
1751 @param[in] tablespace tablespace object
1752 @param[in] sdi_key SDI key to uniquely identify SDI obj
1753 @param[in,out] sdi SDI retrieved from tablespace
1754 A non-null pointer must be passed in
1755 @param[in,out] sdi_len in: length of the memory allocated
1756 out: actual length of SDI
1757 @retval false success
1758 @retval true failure
1759*/
1760typedef bool (*sdi_get_t)(const dd::Tablespace &tablespace,
1761 const sdi_key_t *sdi_key, void *sdi, uint64 *sdi_len);
1762
1763/**
1764 Insert/Update SDI for a given SDI key.
1765 @param[in] hton handlerton object
1766 @param[in] tablespace tablespace object
1767 @param[in] table table object
1768 @param[in] sdi_key SDI key to uniquely identify SDI obj
1769 @param[in] sdi SDI to write into the tablespace
1770 @param[in] sdi_len length of SDI BLOB returned
1771 @retval false success
1772 @retval true failure, my_error() should be called
1773 by SE
1774*/
1775typedef bool (*sdi_set_t)(handlerton *hton, const dd::Tablespace &tablespace,
1776 const dd::Table *table, const sdi_key_t *sdi_key,
1777 const void *sdi, uint64 sdi_len);
1778
1779/**
1780 Delete SDI for a given SDI key.
1781 @param[in] tablespace tablespace object
1782 @param[in] table table object
1783 @param[in] sdi_key SDI key to uniquely identify SDI obj
1784 @retval false success
1785 @retval true failure, my_error() should be called
1786 by SE
1787*/
1788typedef bool (*sdi_delete_t)(const dd::Tablespace &tablespace,
1789 const dd::Table *table, const sdi_key_t *sdi_key);
1790
1791/**
1792 Check if the DDSE is started in a way that leaves thd DD being read only.
1793
1794 @retval true The data dictionary can only be read.
1795 @retval false The data dictionary can be read and written.
1796 */
1797typedef bool (*is_dict_readonly_t)();
1798
1799/**
1800 Drop all temporary tables which have been left from previous server
1801 run belonging to this SE. Used on server start-up.
1802
1803 @param[in] hton Handlerton for storage engine.
1804 @param[in] thd Thread context.
1805 @param[in,out] files List of files in directories for temporary files
1806 which match tmp_file_prefix and thus can belong to
1807 temporary tables (but not necessarily in this SE).
1808 It is recommended to remove file from the list if
1809 SE recognizes it as belonging to temporary table
1810 in this SE and deletes it.
1811*/
1812typedef bool (*rm_tmp_tables_t)(handlerton *hton, THD *thd,
1813 List<LEX_STRING> *files);
1814
1815/**
1816 Retrieve cost constants to be used for this storage engine.
1817
1818 A storage engine that wants to provide its own cost constants to
1819 be used in the optimizer cost model, should implement this function.
1820 The server will call this function to get a cost constant object
1821 that will be used for tables stored in this storage engine instead
1822 of using the default cost constants.
1823
1824 Life cycle for the cost constant object: The storage engine must
1825 allocate the cost constant object on the heap. After the function
1826 returns, the server takes over the ownership of this object.
1827 The server will eventually delete the object by calling delete.
1828
1829 @note In the initial version the storage_category parameter will
1830 not be used. The only valid value this will have is DEFAULT_STORAGE_CLASS
1831 (see declaration in opt_costconstants.h).
1832
1833 @param storage_category the storage type that the cost constants will
1834 be used for
1835
1836 @return a pointer to the cost constant object, if NULL is returned
1837 the default cost constants will be used
1838*/
1839typedef SE_cost_constants *(*get_cost_constants_t)(uint storage_category);
1840
1841/**
1842 @param[in,out] thd pointer to THD
1843 @param[in] new_trx_arg pointer to replacement transaction
1844 @param[out] ptr_trx_arg double pointer to being replaced transaction
1845
1846 Associated with THD engine's native transaction is replaced
1847 with @c new_trx_arg. The old value is returned through a buffer if non-null
1848 pointer is provided with @c ptr_trx_arg.
1849 The method is adapted by XA start and XA prepare handlers to
1850 handle XA transaction that is logged as two parts by slave applier.
1851
1852 This interface concerns engines that are aware of XA transaction.
1853*/
1854typedef void (*replace_native_transaction_in_thd_t)(THD *thd, void *new_trx_arg,
1855 void **ptr_trx_arg);
1856
1857/** Mode for initializing the data dictionary. */
1859 DICT_INIT_CREATE_FILES, ///< Create all required SE files
1860 DICT_INIT_CHECK_FILES, ///< Verify existence of expected files
1861 DICT_INIT_UPGRADE_57_FILES, ///< Used for upgrade from mysql-5.7
1862 DICT_INIT_IGNORE_FILES ///< Don't care about files at all
1864
1865/**
1866 Initialize the SE for being used to store the DD tables. Create
1867 the required files according to the dict_init_mode. Create strings
1868 representing the required DDSE tables, i.e., tables that the DDSE
1869 expects to exist in the DD, and add them to the appropriate out
1870 parameter.
1871
1872 @note There are two variants of this function type, one is to be
1873 used by the DDSE, and has a different type of output parameters
1874 because the SQL layer needs more information about the DDSE tables
1875 in order to support upgrade.
1876
1877 @param dict_init_mode How to initialize files
1878 @param version Target DD version if a new
1879 server is being installed.
1880 0 if restarting an existing
1881 server.
1882 @param [out] DDSE_tables List of SQL DDL statements
1883 for creating DD tables that
1884 are needed by the DDSE.
1885 @param [out] DDSE_tablespaces List of meta data for predefined
1886 tablespaces created by the DDSE.
1887
1888 @retval true An error occurred.
1889 @retval false Success - no errors.
1890 */
1891
1892typedef bool (*dict_init_t)(dict_init_mode_t dict_init_mode, uint version,
1893 List<const Plugin_table> *DDSE_tables,
1894 List<const Plugin_tablespace> *DDSE_tablespaces);
1895
1896typedef bool (*ddse_dict_init_t)(
1897 dict_init_mode_t dict_init_mode, uint version,
1898 List<const dd::Object_table> *DDSE_tables,
1899 List<const Plugin_tablespace> *DDSE_tablespaces);
1900
1901/**
1902 Initialize the set of hard coded DD table ids.
1903*/
1904typedef void (*dict_register_dd_table_id_t)(dd::Object_id hard_coded_tables);
1905
1906/**
1907 Invalidate an entry in the local dictionary cache.
1908
1909 Needed during bootstrap to make sure the contents in the DDSE
1910 dictionary cache is in sync with the global DD.
1911
1912 @param schema_name Schema name.
1913 @param table_name Table name.
1914 */
1915
1916typedef void (*dict_cache_reset_t)(const char *schema_name,
1917 const char *table_name);
1918
1919/**
1920 Invalidate all table and tablespace entries in the local dictionary cache.
1921
1922 Needed for recovery during server restart.
1923 */
1924
1926
1927/** Mode for data dictionary recovery. */
1929 DICT_RECOVERY_INITIALIZE_SERVER, ///< First start of a new server
1930 DICT_RECOVERY_INITIALIZE_TABLESPACES, ///< First start, create tablespaces
1931 DICT_RECOVERY_RESTART_SERVER ///< Restart of an existing server
1933
1934/**
1935 Do recovery in the DDSE as part of initializing the data dictionary.
1936 The dict_recovery_mode indicates what kind of recovery should be
1937 done.
1938
1939 @param dict_recovery_mode How to do recovery
1940 @param version Target DD version if a new
1941 server is being installed.
1942 Actual DD version if restarting
1943 an existing server.
1944
1945 @retval true An error occurred.
1946 @retval false Success - no errors.
1947 */
1948
1949typedef bool (*dict_recover_t)(dict_recovery_mode_t dict_recovery_mode,
1950 uint version);
1951
1952/**
1953 Get the server version id stored in the header of the
1954 dictionary tablespace.
1955
1956 @param [out] version Version number from the DD
1957 tablespace header.
1958
1959 @retval Operation outcome, false if no error, otherwise true.
1960*/
1962
1963/**
1964 Store the current server version number into the
1965 header of the dictionary tablespace.
1966
1967 @retval Operation outcome, false if no error, otherwise true.
1968*/
1970
1971/**
1972 Notify/get permission from storage engine before acquisition or after
1973 release of exclusive metadata lock on object represented by key.
1974
1975 @param thd Thread context.
1976 @param mdl_key MDL key identifying object on which exclusive
1977 lock is to be acquired/was released.
1978 @param notification_type Indicates whether this is pre-acquire or
1979 post-release notification.
1980 @param victimized 'true' if locking failed as we were selected
1981 as a victim in order to avoid possible deadlocks.
1982
1983 @note Notification is done only for objects from TABLESPACE, SCHEMA,
1984 TABLE, FUNCTION, PROCEDURE, TRIGGER and EVENT namespaces.
1985
1986 @note Problems during notification are to be reported as warnings, MDL
1987 subsystem will report generic error if pre-acquire notification
1988 fails/SE refuses lock acquisition.
1989 @note Return value is ignored/error is not reported in case of
1990 post-release notification.
1991
1992 @note In some cases post-release notification might happen even if
1993 there were no prior pre-acquire notification. For example,
1994 when SE was loaded after exclusive lock acquisition, or when
1995 we need notify SEs which permitted lock acquisition that it
1996 didn't happen because one of SEs didn't allow it (in such case
1997 we will do post-release notification for all SEs for simplicity).
1998
1999 @return False - if notification was successful/lock can be acquired,
2000 True - if it has failed/lock should not be acquired.
2001*/
2002typedef bool (*notify_exclusive_mdl_t)(THD *thd, const MDL_key *mdl_key,
2003 ha_notification_type notification_type,
2004 bool *victimized);
2005
2006/**
2007 Notify/get permission from storage engine before or after execution of
2008 ALTER TABLE operation on the table identified by the MDL key.
2009
2010 @param thd Thread context.
2011 @param mdl_key MDL key identifying table which is going to be
2012 or was ALTERed.
2013 @param notification_type Indicates whether this is pre-ALTER TABLE or
2014 post-ALTER TABLE notification.
2015
2016 @note This hook is necessary because for ALTER TABLE upgrade to X
2017 metadata lock happens fairly late during the execution process,
2018 so it can be expensive to abort ALTER TABLE operation at this
2019 stage by returning failure from notify_exclusive_mdl() hook.
2020
2021 @note This hook follows the same error reporting convention as
2022 @see notify_exclusive_mdl().
2023
2024 @note Similarly to notify_exclusive_mdl() in some cases post-ALTER
2025 notification might happen even if there were no prior pre-ALTER
2026 notification.
2027
2028 @note Post-ALTER notification can happen before post-release notification
2029 for exclusive metadata lock acquired by this ALTER TABLE.
2030
2031 @return False - if notification was successful/ALTER TABLE can proceed.
2032 True - if it has failed/ALTER TABLE should be aborted.
2033*/
2034typedef bool (*notify_alter_table_t)(THD *thd, const MDL_key *mdl_key,
2035 ha_notification_type notification_type);
2036
2037/**
2038 Notify/get permission from storage engine before or after execution of
2039 RENAME TABLE operation on the table identified by the MDL key.
2040
2041 @param thd Thread context.
2042 @param mdl_key MDL key identifying table which is going to be
2043 or was RENAMEd.
2044 @param notification_type Indicates whether this is pre-RENAME TABLE or
2045 post-RENAME TABLE notification.
2046 @param old_db_name
2047 @param old_table_name
2048 @param new_db_name
2049 @param new_table_name
2050*/
2051typedef bool (*notify_rename_table_t)(THD *thd, const MDL_key *mdl_key,
2052 ha_notification_type notification_type,
2053 const char *old_db_name,
2054 const char *old_table_name,
2055 const char *new_db_name,
2056 const char *new_table_name);
2057
2058/**
2059 Notify/get permission from storage engine before or after execution of
2060 TRUNCATE TABLE operation on the table identified by the MDL key.
2061
2062 @param thd Thread context.
2063 @param mdl_key MDL key identifying table which is going to be
2064 or was TRUNCATEd.
2065 @param notification_type Indicates whether this is pre-TRUNCATE TABLE or
2066 post-TRUNCATE TABLE notification.
2067*/
2068typedef bool (*notify_truncate_table_t)(THD *thd, const MDL_key *mdl_key,
2069 ha_notification_type notification_type);
2070
2071/**
2072 @brief
2073 Initiate master key rotation
2074
2075 @returns false on success,
2076 true on failure
2077*/
2079
2080/**
2081 @brief
2082 Enable or Disable SE write ahead logging.
2083
2084 @param[in] thd server thread handle
2085 @param[in] enable enable/disable redo logging
2086
2087 @return true iff failed.
2088*/
2089typedef bool (*redo_log_set_state_t)(THD *thd, bool enable);
2090
2091/**
2092 @brief
2093 Retrieve ha_statistics from SE.
2094
2095 @param db_name Name of schema
2096 @param table_name Name of table
2097 @param se_private_id SE private id of the table.
2098 @param ts_se_private_data Tablespace SE private data.
2099 @param tbl_se_private_data Table SE private data.
2100 @param flags Type of statistics to retrieve.
2101 @param[out] stats Contains statistics read from SE.
2102
2103 @note Handlers that implement this callback/API should adhere
2104 to servers expectation that, the implementation would invoke
2105 my_error() before returning 'true'/failure from this function.
2106
2107 @returns false on success,
2108 true on failure
2109*/
2111 const char *db_name, const char *table_name, dd::Object_id se_private_id,
2112 const dd::Properties &ts_se_private_data,
2113 const dd::Properties &tbl_se_private_data, uint flags,
2115
2116/**
2117 @brief
2118 Retrieve index column cardinality from SE.
2119
2120 @param db_name Name of schema
2121 @param table_name Name of table
2122 @param index_name Name of index
2123 @param index_ordinal_position Position of index.
2124 @param column_ordinal_position Position of column in index.
2125 @param se_private_id SE private id of the table.
2126 @param[out] cardinality cardinality being returned by SE.
2127
2128 @note Handlers that implement this callback/API should adhere
2129 to servers expectation that, the implementation would invoke
2130 my_error() before returning 'true'/failure from this function.
2131
2132 @returns false on success,
2133 true on failure
2134*/
2136 const char *db_name, const char *table_name, const char *index_name,
2137 uint index_ordinal_position, uint column_ordinal_position,
2138 dd::Object_id se_private_id, ulonglong *cardinality);
2139
2140/**
2141 Retrieve ha_tablespace_statistics from SE.
2142
2143 @param tablespace_name Tablespace_name
2144 @param file_name Tablespace file name.
2145 @param ts_se_private_data Tablespace SE private data.
2146 @param[out] stats Contains tablespace
2147 statistics read from SE.
2148
2149 @note Handlers that implement this callback/API should adhere
2150 to servers expectation that, the implementation would invoke
2151 my_error() before returning 'true'/failure from this function.
2152
2153 @returns false on success, true on failure
2154*/
2156 const char *tablespace_name, const char *file_name,
2157 const dd::Properties &ts_se_private_data, ha_tablespace_statistics *stats);
2158
2159/* Database physical clone interfaces */
2160
2161/** Get capability flags for clone operation
2162@param[out] flags capability flag */
2164
2165/** Begin copy from source database
2166@param[in] hton handlerton for SE
2167@param[in] thd server thread handle
2168@param[in,out] loc locator
2169@param[in,out] loc_len locator length
2170@param[out] task_id task identifier
2171@param[in] type clone type
2172@param[in] mode mode for starting clone
2173@return error code */
2174using Clone_begin_t = int (*)(handlerton *hton, THD *thd, const uchar *&loc,
2175 uint &loc_len, uint &task_id, Ha_clone_type type,
2177
2178/** Copy data from source database in chunks via callback
2179@param[in] hton handlerton for SE
2180@param[in] thd server thread handle
2181@param[in] loc locator
2182@param[in] loc_len locator length in bytes
2183@param[in] task_id task identifier
2184@param[in] cbk callback interface for sending data
2185@return error code */
2186using Clone_copy_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2187 uint loc_len, uint task_id, Ha_clone_cbk *cbk);
2188
2189/** Acknowledge data transfer to source database
2190@param[in] hton handlerton for SE
2191@param[in] thd server thread handle
2192@param[in] loc locator
2193@param[in] loc_len locator length in bytes
2194@param[in] task_id task identifier
2195@param[in] in_err inform any error occurred
2196@param[in] cbk callback interface
2197@return error code */
2198using Clone_ack_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2199 uint loc_len, uint task_id, int in_err,
2200 Ha_clone_cbk *cbk);
2201
2202/** End copy from source database
2203@param[in] hton handlerton for SE
2204@param[in] thd server thread handle
2205@param[in] loc locator
2206@param[in] loc_len locator length in bytes
2207@param[in] task_id task identifier
2208@param[in] in_err error code when ending after error
2209@return error code */
2210using Clone_end_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2211 uint loc_len, uint task_id, int in_err);
2212
2213/** Begin apply to destination database
2214@param[in] hton handlerton for SE
2215@param[in] thd server thread handle
2216@param[in,out] loc locator
2217@param[in,out] loc_len locator length
2218@param[in] task_id task identifier
2219@param[in] mode mode for starting clone
2220@param[in] data_dir target data directory
2221@return error code */
2222using Clone_apply_begin_t = int (*)(handlerton *hton, THD *thd,
2223 const uchar *&loc, uint &loc_len,
2224 uint &task_id, Ha_clone_mode mode,
2225 const char *data_dir);
2226
2227/** Apply data to destination database in chunks via callback
2228@param[in] hton handlerton for SE
2229@param[in] thd server thread handle
2230@param[in] loc locator
2231@param[in] loc_len locator length in bytes
2232@param[in] task_id task identifier
2233@param[in] in_err inform any error occurred
2234@param[in] cbk callback interface for receiving data
2235@return error code */
2236using Clone_apply_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2237 uint loc_len, uint task_id, int in_err,
2238 Ha_clone_cbk *cbk);
2239
2240/** End apply to destination database
2241@param[in] hton handlerton for SE
2242@param[in] thd server thread handle
2243@param[in] loc locator
2244@param[in] loc_len locator length in bytes
2245@param[in] task_id task identifier
2246@param[in] in_err error code when ending after error
2247@return error code */
2248using Clone_apply_end_t = int (*)(handlerton *hton, THD *thd, const uchar *loc,
2249 uint loc_len, uint task_id, int in_err);
2250
2252 /* Get clone capabilities of an SE */
2254
2255 /* Interfaces to copy data. */
2260
2261 /* Interfaces to apply data. */
2265};
2266
2267/**
2268 Perform post-commit/rollback cleanup after DDL statement (e.g. in
2269 case of DROP TABLES really remove table files from disk).
2270
2271 @note This hook will be invoked after DDL commit or rollback only
2272 for storage engines supporting atomic DDL.
2273
2274 @note Problems during execution of this method should be reported to
2275 error log and as warnings/notes to user. Since this method is
2276 called after successful commit of the statement we can't fail
2277 statement with error.
2278*/
2279typedef void (*post_ddl_t)(THD *thd);
2280
2281/**
2282 Perform SE-specific cleanup after recovery of transactions.
2283
2284 @note Particularly SEs supporting atomic DDL can use this call
2285 to perform post-DDL actions for DDL statements which were
2286 committed or rolled back during recovery stage.
2287*/
2288typedef void (*post_recover_t)(void);
2289
2290/**
2291 Lock a handlerton (resource) log to collect log information.
2292*/
2293
2294typedef bool (*lock_hton_log_t)(handlerton *hton);
2295
2296/**
2297 Unlock a handlerton (resource) log after collecting log information.
2298*/
2299
2300typedef bool (*unlock_hton_log_t)(handlerton *hton);
2301
2302/**
2303 Collect a handlerton (resource) log information.
2304*/
2305
2306typedef bool (*collect_hton_log_info_t)(handlerton *hton, Json_dom *json);
2307
2308/**
2309 Check SE considers types of child and parent columns in foreign key
2310 to be compatible.
2311
2312 @param child_column_type Child column type description.
2313 @param parent_column_type Parent column type description.
2314 @param check_charsets Indicates whether we need to check
2315 that charsets of string columns
2316 match. Which is true in most cases.
2317
2318 @returns True if types are compatible, False if not.
2319*/
2320
2322 const Ha_fk_column_type *child_column_type,
2323 const Ha_fk_column_type *parent_column_type, bool check_charsets);
2324
2325typedef bool (*is_reserved_db_name_t)(handlerton *hton, const char *name);
2326
2327/**
2328 Prepare the secondary engine for executing a statement. This function is
2329 called right after the secondary engine TABLE objects have been opened by
2330 open_secondary_engine_tables(), before the statement is optimized and
2331 executed. Secondary engines will typically create a context object in this
2332 function, which they can use to store state that is needed during the
2333 optimization and execution phases.
2334
2335 @param thd thread context
2336 @param lex the statement to execute
2337 @return true on error, false on success
2338*/
2339using prepare_secondary_engine_t = bool (*)(THD *thd, LEX *lex);
2340
2341/**
2342 Optimize a statement for execution on a secondary storage engine. This
2343 function is called when the optimization of a statement has completed, just
2344 before the statement is executed. Secondary engines can use this function to
2345 apply engine-specific optimizations to the execution plan. They can also
2346 reject executing the query by raising an error, in which case the query will
2347 be reprepared and executed by the primary storage engine.
2348
2349 @param thd thread context
2350 @param lex the statement being optimized
2351 @return true on error, false on success
2352*/
2353using optimize_secondary_engine_t = bool (*)(THD *thd, LEX *lex);
2354
2355/**
2356 Compares the cost of two join plans in the secondary storage engine. The cost
2357 of the current candidate is compared with the cost of the best plan seen so
2358 far.
2359
2360 @param thd thread context
2361 @param join the candidate plan to evaluate
2362 @param optimizer_cost the cost estimate calculated by the optimizer
2363 @param[out] use_best_so_far true if the optimizer should stop searching for
2364 a better plan and use the best plan it has seen so far
2365 @param[out] cheaper true if the candidate is the best plan seen so far for
2366 this JOIN (must be true if it is the first plan seen),
2367 false otherwise
2368 @param[out] secondary_engine_cost the cost estimated by the secondary engine
2369
2370 @return false on success, or true if an error has been raised
2371*/
2372using compare_secondary_engine_cost_t = bool (*)(THD *thd, const JOIN &join,
2373 double optimizer_cost,
2374 bool *use_best_so_far,
2375 bool *cheaper,
2376 double *secondary_engine_cost);
2377
2378/**
2379 Evaluates the cost of executing the given access path in this secondary
2380 storage engine, and potentially modifies the cost estimates that are in the
2381 access path. This function is only called from the hypergraph join optimizer.
2382
2383 The function is called on every access path that the join optimizer might
2384 compare to an alternative access path. This includes both paths that represent
2385 complete execution plans and paths that represent partial plans. It is not
2386 guaranteed to be called on every child path. For example, if GROUP BY is done
2387 by sorting first and then aggregating the sorted results, the function will
2388 only be called on the aggregation path, and not on the sort path, because only
2389 the aggregation path will be compared to other paths.
2390
2391 The secondary engine is allowed to modify the estimates in the access path to
2392 better match the costs of the access path in the secondary engine. It can
2393 change any of the following AccessPath members:
2394
2395 - init_once_cost
2396 - init_cost
2397 - cost
2398 - cost_before_filter
2399 - num_output_rows
2400 - num_output_rows_before_filter
2401 - secondary_engine_data
2402
2403 Any other members should be left unchanged. The AccessPath must be in an
2404 internally consistent state when the function returns, and satisfy invariants
2405 expected by the hypergraph join optimizer, such as:
2406
2407 - init_cost <= cost_before_filter <= cost
2408 - num_output_rows <= num_output_rows_before_filter
2409
2410 The secondary engine can also reject an access path altogether, by returning
2411 true, in which case the join optimizer will not use that path in the final
2412 plan. Since the secondary engine can reject any partial or complete plan, it
2413 is possible that the join optimizer does not find any valid plan that is
2414 accepted. In this case, the join optimizer will raise an error.
2415
2416 If the secondary encounters an error when evaluating the cost of the path, it
2417 can signal an error by calling my_error() and return true, in which case the
2418 join optimizer will not suggest any plan for the query.
2419
2420 @param thd The thread context.
2421 @param hypergraph The hypergraph that represents the search space.
2422 @param[in,out] access_path The AccessPath to evaluate.
2423
2424 @retval false on success.
2425 @retval true if the plan is to be rejected, or if an error was raised.
2426*/
2428 THD *thd, const JoinHypergraph &hypergraph, AccessPath *access_path);
2429
2430// Capabilities (bit flags) for secondary engines.
2431using SecondaryEngineFlags = uint64_t;
2435
2436 // If this flag is set, aggregation (GROUP BY and DISTINCT) do not require
2437 // ordered inputs and create unordered outputs. This is typically the case
2438 // if they are implemented using hash-based techniques.
2440
2441 /// This flag can be set to signal that a secondary storage engine will not
2442 /// use MySQL's executor (see JOIN::override_executor_func). In this case, it
2443 /// doesn't need MySQL's execution data structures, like internal temporary
2444 /// tables, filesort objects or iterators. If the flag is set,
2445 /// FinalizePlanForQueryBlock() will not make any changes to the plan, and
2446 /// CreateIteratorFromAccessPath() will not be called.
2448};
2449
2450/// Creates an empty bitmap of access path types. This is the base
2451/// case for the function template with the same name below.
2452inline constexpr SecondaryEngineFlags MakeSecondaryEngineFlags() { return 0; }
2453
2454/// Creates a bitmap representing a set of access path types.
2455template <typename... Args>
2457 SecondaryEngineFlag flag1, Args... rest) {
2458 return (uint64_t{1} << static_cast<int>(flag1)) |
2459 MakeSecondaryEngineFlags(rest...);
2460}
2461
2462/// Returns the handlerton of the secondary engine that is used in the session,
2463/// or nullptr if a secondary engine is not used.
2464const handlerton *SecondaryEngineHandlerton(const THD *thd);
2465
2466// FIXME: Temporary workaround to enable storage engine plugins to use the
2467// before_commit hook. Remove after WL#11320 has been completed.
2468typedef void (*se_before_commit_t)(void *arg);
2469
2470// FIXME: Temporary workaround to enable storage engine plugins to use the
2471// after_commit hook. Remove after WL#11320 has been completed.
2472typedef void (*se_after_commit_t)(void *arg);
2473
2474// FIXME: Temporary workaround to enable storage engine plugins to use the
2475// before_rollback hook. Remove after WL#11320 has been completed.
2476typedef void (*se_before_rollback_t)(void *arg);
2477
2478/*
2479 Page Tracking : interfaces to handlerton functions which starts/stops page
2480 tracking, and purges/fetches page tracking information.
2481*/
2482
2483/**
2484 Start page tracking.
2485
2486 @param[out] start_id SE specific sequence number [LSN for InnoDB]
2487 indicating when the tracking was started
2488
2489 @return Operation status.
2490 @retval 0 Success
2491 @retval other ER_* mysql error. Get error details from THD.
2492*/
2493using page_track_start_t = int (*)(uint64_t *start_id);
2494
2495/**
2496 Stop page tracking.
2497
2498 @param[out] stop_id SE specific sequence number [LSN for InnoDB]
2499 indicating when the tracking was stopped
2500
2501 @return Operation status.
2502 @retval 0 Success
2503 @retval other ER_* mysql error. Get error details from THD.
2504*/
2505using page_track_stop_t = int (*)(uint64_t *stop_id);
2506
2507/**
2508 Purge page tracking data.
2509
2510 @param[in,out] purge_id SE specific sequence number [LSN for InnoDB]
2511 initially indicating till where the data needs to be purged and finally
2512 updated to until where it was actually purged
2513
2514 @return Operation status.
2515 @retval 0 Success
2516 @retval other ER_* mysql error. Get error details from THD.
2517*/
2518using page_track_purge_t = int (*)(uint64_t *purge_id);
2519
2520/**
2521 Fetch tracked pages.
2522
2523 @param[in] cbk_func callback function return page IDs
2524 @param[in] cbk_ctx caller's context for callback
2525 @param[in,out] start_id SE specific sequence number [LSN for InnoDB] from
2526 where the pages tracked would be returned.
2527 @note The range might get expanded and the actual start_id used for the
2528 querying will be updated.
2529 @param[in,out] stop_id SE specific sequence number [LSN for InnoDB]
2530 until where the pages tracked would be returned.
2531 @note The range might get expanded and the actual stop_id used for the
2532 querying will be updated.
2533 @param[out] buffer allocated buffer to copy page IDs
2534 @param[in] buffer_len length of buffer in bytes
2535
2536 @return Operation status.
2537 @retval 0 Success
2538 @retval other ER_* mysql error. Get error details from THD.
2539*/
2541 void *cbk_ctx, uint64_t *start_id,
2542 uint64_t *stop_id,
2543 unsigned char *buffer,
2544 size_t buffer_len);
2545
2546/**
2547 Fetch approximate number of tracked pages in the given range.
2548
2549 @param[in,out] start_id SE specific sequence number [LSN for InnoDB] from
2550 where the pages tracked would be returned.
2551 @note the range might get expanded and the actual start_id used for the
2552 querying will be updated.
2553 @param[in,out] stop_id SE specific sequence number [LSN for InnoDB]
2554 until where the pages tracked would be returned.
2555 @note the range might get expanded and the actual stop_id used for the
2556 querying will be updated.
2557 @param[out] num_pages number of pages tracked
2558
2559 @return Operation status.
2560 @retval 0 Success
2561 @retval other ER_* mysql error. Get error details from THD.
2562*/
2563using page_track_get_num_page_ids_t = int (*)(uint64_t *start_id,
2564 uint64_t *stop_id,
2565 uint64_t *num_pages);
2566
2567/** Fetch the status of the page tracking system.
2568@param[out] status vector of a pair of (ID, bool) where ID is the
2569start/stop point and bool is true if the ID is a start point else false */
2571 void (*)(std::vector<std::pair<uint64_t, bool>> &status);
2572
2573/** Page track interface */
2581};
2582
2583/**
2584 handlerton is a singleton structure - one instance per storage engine -
2585 to provide access to storage engine functionality that works on the
2586 "global" level (unlike handler class that works on a per-table basis).
2587
2588 usually handlerton instance is defined statically in ha_xxx.cc as
2589
2590 static handlerton { ... } xxx_hton;
2591
2592 savepoint_*, prepare, recover, and *_by_xid pointers can be 0.
2593*/
2595 /**
2596 Historical marker for if the engine is available or not.
2597 */
2599
2600 /**
2601 Historical number used for frm file to determine the correct storage engine.
2602 This is going away and new engines will just use "name" for this.
2603 */
2605 /**
2606 Each storage engine has it's own memory area (actually a pointer)
2607 in the thd, for storing per-connection information.
2608 It is accessed as
2609
2610 thd->ha_data[xxx_hton.slot]
2611
2612 slot number is initialized by MySQL after xxx_init() is called.
2613 */
2615 /**
2616 To store per-savepoint data storage engine is provided with an area
2617 of a requested size (0 is ok here).
2618 savepoint_offset must be initialized statically to the size of
2619 the needed memory to store per-savepoint information.
2620 After xxx_init it is changed to be an offset to savepoint storage
2621 area and need not be used by storage engine.
2622 see binlog_hton and binlog_savepoint_set/rollback for an example.
2623 */
2625
2626 /* handlerton methods */
2627
2672
2673 /** Global handler flags. */
2675
2676 /*
2677 Those handlerton functions below are properly initialized at handler
2678 init.
2679 */
2680
2689
2690 /*
2691 APIs for retrieving Serialized Dictionary Information by tablespace id
2692 */
2693
2700
2701 /**
2702 Null-ended array of file extensions that exist for the storage engine.
2703 Used by frm_error() and the default handler::rename_table and delete_table
2704 methods in handler.cc.
2705
2706 For engines that have two file name extensions (separate meta/index file
2707 and data file), the order of elements is relevant. First element of engine
2708 file name extensions array should be meta/index file extension. Second
2709 element - data file extension. This order is assumed by
2710 prepare_for_repair() when REPAIR TABLE ... USE_FRM is issued.
2711
2712 For engines that don't have files, file_extensions is NULL.
2713
2714 Currently, the following alternatives are used:
2715 - file_extensions == NULL;
2716 - file_extensions[0] != NULL, file_extensions[1] == NULL;
2717 - file_extensions[0] != NULL, file_extensions[1] != NULL,
2718 file_extensions[2] == NULL;
2719 */
2720 const char **file_extensions;
2721
2732
2736
2739
2740 /** Clone data transfer interfaces */
2742
2743 /** Flag for Engine License. */
2745 /** Location for engines to keep personal structures. */
2746 void *data;
2747
2748 /*
2749 Log_resource functions that must be supported by storage engines
2750 with relevant log information to be collected.
2751 */
2755
2756 /** Flags describing details of foreign key support by storage engine. */
2758
2760
2761 /**
2762 Suffix for auto-generated foreign key names for tables using this storage
2763 engine. If such suffix is specified by SE then its generated foreign key
2764 names follow (table name)(SE-specific FK name suffix)(FK number) pattern.
2765 Length of such suffix should not exceed MAX_FK_NAME_SUFFIX_LENGTH bytes.
2766 If no suffix is specified then FK_NAME_DEFAULT_SUFFIX is used as
2767 default.
2768 */
2770
2771 /**
2772 Pointer to a function that prepares a secondary engine for executing a
2773 statement.
2774
2775 @see prepare_secondary_engine_t for function signature.
2776 */
2778
2779 /**
2780 Pointer to a function that optimizes the current statement for
2781 execution on the secondary storage engine represented by this
2782 handlerton.
2783
2784 @see optimize_secondary_engine_t for function signature.
2785 */
2787
2788 /**
2789 Pointer to a function that estimates the cost of executing a join in a
2790 secondary storage engine.
2791
2792 @see compare_secondary_engine_cost_t for function signature.
2793 */
2795
2796 /// Bitmap which contains the supported join types and other flags
2797 /// for a secondary storage engine when used with the hypergraph join
2798 /// optimizer. If it is empty, it means that the secondary engine
2799 /// does not support the hypergraph join optimizer.
2801
2802 /// Pointer to a function that evaluates the cost of executing an access path
2803 /// in a secondary storage engine.
2804 ///
2805 /// @see secondary_engine_modify_access_path_cost_t for function signature.
2808
2812
2813 /** Page tracking interface */
2815};
2816
2817/* Possible flags of a handlerton (there can be 32 of them) */
2818#define HTON_NO_FLAGS 0
2819#define HTON_CLOSE_CURSORS_AT_COMMIT (1 << 0)
2820#define HTON_ALTER_NOT_SUPPORTED (1 << 1) // Engine does not support alter
2821#define HTON_CAN_RECREATE (1 << 2) // Delete all is used for truncate
2822#define HTON_HIDDEN (1 << 3) // Engine does not appear in lists
2823/*
2824 Bit 4 was occupied by BDB-specific HTON_FLUSH_AFTER_RENAME flag and is no
2825 longer used.
2826*/
2827#define HTON_NOT_USER_SELECTABLE (1 << 5)
2828#define HTON_TEMPORARY_NOT_SUPPORTED \
2829 (1 << 6) // Having temporary tables not supported
2830#define HTON_SUPPORT_LOG_TABLES (1 << 7) // Engine supports log tables
2831#define HTON_NO_PARTITION (1 << 8) // You can not partition these tables
2832
2833/*
2834 This flag should be set when deciding that the engine does not allow row based
2835 binary logging (RBL) optimizations.
2836
2837 Currently, setting this flag, means that table's read/write_set will be left
2838 untouched when logging changes to tables in this engine. In practice this
2839 means that the server will not mess around with table->write_set and/or
2840 table->read_set when using RBL and deciding whether to log full or minimal
2841 rows.
2842
2843 It's valuable for instance for virtual tables, eg: Performance Schema which
2844 have no meaning for replication.
2845*/
2846#define HTON_NO_BINLOG_ROW_OPT (1 << 9)
2847
2848/**
2849 Engine supports extended keys. The flag allows to
2850 use 'extended key' feature if the engine is able to
2851 do it (has primary key values in the secondary key).
2852 Note that handler flag HA_PRIMARY_KEY_IN_READ_INDEX is
2853 actually partial case of HTON_SUPPORTS_EXTENDED_KEYS.
2854*/
2855
2856#define HTON_SUPPORTS_EXTENDED_KEYS (1 << 10)
2857
2858// Engine support foreign key constraint.
2859
2860#define HTON_SUPPORTS_FOREIGN_KEYS (1 << 11)
2861
2862/**
2863 Engine supports atomic DDL. That is rollback of transaction for DDL
2864 statement will also rollback all changes in SE, commit of transaction
2865 of DDL statement will make it durable.
2866*/
2867
2868#define HTON_SUPPORTS_ATOMIC_DDL (1 << 12)
2869
2870/* Engine supports packed keys. */
2871#define HTON_SUPPORTS_PACKED_KEYS (1 << 13)
2872
2873/** Engine is a secondary storage engine. */
2874#define HTON_IS_SECONDARY_ENGINE (1 << 14)
2875
2876/** Engine supports secondary storage engines. */
2877#define HTON_SUPPORTS_SECONDARY_ENGINE (1 << 15)
2878
2879/** Engine supports table or tablespace encryption . */
2880#define HTON_SUPPORTS_TABLE_ENCRYPTION (1 << 16)
2881
2883 1 << 17};
2884
2885/** Engine supports Generated invisible primary key. */
2886constexpr const decltype(
2888
2889/** Whether the secondary engine supports DDLs. No meaning if the engine is not
2890 * secondary. */
2891#define HTON_SECONDARY_ENGINE_SUPPORTS_DDL (1 << 19)
2892
2894 assert(hton->flags & HTON_IS_SECONDARY_ENGINE);
2895
2896 return (hton->flags & HTON_SECONDARY_ENGINE_SUPPORTS_DDL) != 0;
2897}
2898
2899inline bool ddl_is_atomic(const handlerton *hton) {
2900 return (hton->flags & HTON_SUPPORTS_ATOMIC_DDL) != 0;
2901}
2902
2903/* Bits for handlerton::foreign_keys_flags bitmap. */
2904
2905/**
2906 Engine supports both unique and non-unique parent keys for
2907 foreign keys which contain full foreign key as its prefix.
2908
2909 Storage engines which support foreign keys but do not have
2910 this flag set are assumed to support only parent keys which
2911 are primary/unique and contain exactly the same columns as
2912 the foreign key, possibly, in different order.
2913*/
2914
2916
2917/**
2918 Storage engine supports hash keys as supporting keys for foreign
2919 keys. Hash key should contain all foreign key columns and only
2920 them (although in any order).
2921
2922 Storage engines which support foreign keys but do not have this
2923 flag set are assumed to not allow hash keys as supporting keys.
2924*/
2925
2927
2928/**
2929 Storage engine supports non-hash keys which have common prefix
2930 with the foreign key as supporting keys for it. If there are
2931 several such keys, one which shares biggest prefix with FK is
2932 chosen.
2933
2934 Storage engines which support foreign keys but do not have this
2935 flag set are assumed to require that supporting key contains full
2936 foreign key as its prefix.
2937*/
2938
2940
2941/**
2942 Storage engine does not support using the same key for both parent
2943 and supporting key, but requires the two to be different.
2944*/
2945
2947 (1 << 3);
2948
2949/**
2950 Engine takes into account hidden part of key (coming from primary key)
2951 when determines if it can serve as parent key for a foreign key.
2952
2953 Implies HTON_FKS_WITH_PREFIX_PARENT_KEYS and is related to
2954 HTON_SUPPORTS_EXTENDED_KEYS.
2955*/
2956
2958
2959/**
2960 Maximum possible length of SE-specific suffixes for auto-generated
2961 foreign key names.
2962*/
2963static const size_t MAX_FK_NAME_SUFFIX_LENGTH = 16;
2964
2965/**
2966 Suffix for auto-generated foreign key names for tables in SE's which
2967 don't specify own suffix. I.e. for foreign keys on tables in such
2968 SE's generated names follow (table name)FK_NAME_DEFAULT_SUFFIX(FK number)
2969 pattern.
2970*/
2972
2979
2985
2986/* struct to hold information about the table that should be created */
2990 bool schema_read_only{false};
2992 const char *password{nullptr};
2993 const char *tablespace{nullptr};
2994 LEX_STRING comment{nullptr, 0};
2995
2996 /**
2997 Algorithm (and possible options) to be used for InnoDB's transparent
2998 page compression. If this attribute is set then it is hint to the
2999 storage engine to try and compress the data using the specified algorithm
3000 where possible. Note: this value is interpreted by the storage engine only.
3001 and ignored by the Server layer. */
3002
3004
3005 /**
3006 This attribute is used for InnoDB's transparent page encryption.
3007 If this attribute is set then it is hint to the storage engine to encrypt
3008 the data. Note: this value is interpreted by the storage engine only.
3009 and ignored by the Server layer. */
3010
3012
3013 /**
3014 * Secondary engine of the table.
3015 * Is nullptr if no secondary engine defined.
3016 */
3018
3019 const char *data_file_name{nullptr};
3020 const char *index_file_name{nullptr};
3021 const char *alias{nullptr};
3027 uint64_t used_fields{0};
3028 // Can only be 1,2,4,8 or 16, but use uint32_t since that how it is
3029 // represented in InnoDB
3030 std::uint32_t key_block_size{0};
3031 uint stats_sample_pages{0}; /* number of pages to sample during
3032 stats estimation, if used, otherwise 0. */
3036 /**
3037 Row type of the table definition.
3038
3039 Defaults to ROW_TYPE_DEFAULT for all non-ALTER statements.
3040 For ALTER TABLE defaults to ROW_TYPE_NOT_USED (means "keep the current").
3041
3042 Can be changed either explicitly by the parser.
3043 If nothing specified inherits the value of the original table (if present).
3044 */
3046 uint null_bits{0}; /* NULL bits at start of record */
3047 uint options{0}; /* OR of HA_CREATE_ options */
3049 ha_storage_media storage_media{HA_SM_DEFAULT}; /* DEFAULT, DISK or MEMORY */
3050
3051 /*
3052 A flag to indicate if this table should be marked as a hidden table in
3053 the data dictionary. One use case is to mark the temporary tables
3054 created by ALTER to be marked as hidden.
3055 */
3056 bool m_hidden{false};
3057
3058 /*
3059 A flag to indicate if this table should be created but not committed at
3060 the end of statement.
3061 */
3063
3066
3068
3070
3071 /**
3072 Fill HA_CREATE_INFO to be used by ALTER as well as upgrade code.
3073 This function separates code from mysql_prepare_alter_table() to be
3074 used by upgrade code as well to reduce code duplication.
3075 For ALTER code path, this lets new create options override the old
3076 ones.
3077
3078 @param[in] share TABLE_SHARE object
3079 @param[in] used_fields If a given create option is not flagged, old
3080 value be copied from the TABLE_SHARE.
3081 */
3082
3084 uint64_t used_fields);
3085};
3086
3087/**
3088 Structure describing changes to an index to be caused by ALTER TABLE.
3089*/
3090
3091struct KEY_PAIR {
3092 /**
3093 Pointer to KEY object describing old version of index in
3094 TABLE::key_info array for TABLE instance representing old
3095 version of table.
3096 */
3098 /**
3099 Pointer to KEY object describing new version of index in
3100 Alter_inplace_info::key_info_buffer array.
3101 */
3103};
3104
3105/**
3106 In-place alter handler context.
3107
3108 This is a superclass intended to be subclassed by individual handlers
3109 in order to store handler unique context between in-place alter API calls.
3110
3111 The handler is responsible for creating the object. This can be done
3112 as early as during check_if_supported_inplace_alter().
3113
3114 The SQL layer is responsible for destroying the object.
3115
3116 @see Alter_inplace_info
3117*/
3118
3120 public:
3122
3124 [[maybe_unused]]) {}
3125 virtual ~inplace_alter_handler_ctx() = default;
3126};
3127
3128/**
3129 Class describing changes to be done by ALTER TABLE.
3130 Instance of this class is passed to storage engine in order
3131 to determine if this ALTER TABLE can be done using in-place
3132 algorithm. It is also used for executing the ALTER TABLE
3133 using in-place algorithm.
3134*/
3135
3137 public:
3138 /**
3139 Bits to show in detail what operations the storage engine is
3140 to execute.
3141
3142 All these operations are supported as in-place operations by the
3143 SQL layer. This means that operations that by their nature must
3144 be performed by copying the table to a temporary table, will not
3145 have their own flags here (e.g. ALTER TABLE FORCE, ALTER TABLE
3146 ENGINE).
3147
3148 We generally try to specify handler flags only if there are real
3149 changes. But in cases when it is cumbersome to determine if some
3150 attribute has really changed we might choose to set flag
3151 pessimistically, for example, relying on parser output only.
3152 */
3154
3155 // Add non-unique, non-primary index
3156 static const HA_ALTER_FLAGS ADD_INDEX = 1ULL << 0;
3157
3158 // Drop non-unique, non-primary index
3159 static const HA_ALTER_FLAGS DROP_INDEX = 1ULL << 1;
3160
3161 // Add unique, non-primary index
3162 static const HA_ALTER_FLAGS ADD_UNIQUE_INDEX = 1ULL << 2;
3163
3164 // Drop unique, non-primary index
3165 static const HA_ALTER_FLAGS DROP_UNIQUE_INDEX = 1ULL << 3;
3166
3167 // Add primary index
3168 static const HA_ALTER_FLAGS ADD_PK_INDEX = 1ULL << 4;
3169
3170 // Drop primary index
3171 static const HA_ALTER_FLAGS DROP_PK_INDEX = 1ULL << 5;
3172
3173 // Add column
3174
3175 // Virtual generated column
3176 static const HA_ALTER_FLAGS ADD_VIRTUAL_COLUMN = 1ULL << 6;
3177 // Stored base (non-generated) column
3178 static const HA_ALTER_FLAGS ADD_STORED_BASE_COLUMN = 1ULL << 7;
3179 // Stored generated column
3181 // Add generic column (convenience constant).
3184
3185 // Drop column
3186 static const HA_ALTER_FLAGS DROP_VIRTUAL_COLUMN = 1ULL << 9;
3187 static const HA_ALTER_FLAGS DROP_STORED_COLUMN = 1ULL << 10;
3190
3191 // Rename column
3192 static const HA_ALTER_FLAGS ALTER_COLUMN_NAME = 1ULL << 11;
3193
3194 // Change column datatype
3196 static const HA_ALTER_FLAGS ALTER_STORED_COLUMN_TYPE = 1ULL << 13;
3197
3198 /**
3199 Change column datatype in such way that new type has compatible
3200 packed representation with old type, so it is theoretically
3201 possible to perform change by only updating data dictionary
3202 without changing table rows.
3203 */
3205
3206 /// A virtual column has changed its position
3208
3209 /// A stored column has changed its position (disregarding virtual columns)
3211
3212 // Change column from NOT NULL to NULL
3213 static const HA_ALTER_FLAGS ALTER_COLUMN_NULLABLE = 1ULL << 17;
3214
3215 // Change column from NULL to NOT NULL
3217
3218 // Set or remove default column value
3219 static const HA_ALTER_FLAGS ALTER_COLUMN_DEFAULT = 1ULL << 19;
3220
3221 // Change column generation expression
3222 static const HA_ALTER_FLAGS ALTER_VIRTUAL_GCOL_EXPR = 1ULL << 20;
3223 static const HA_ALTER_FLAGS ALTER_STORED_GCOL_EXPR = 1ULL << 21;
3224
3225 // Add foreign key
3226 static const HA_ALTER_FLAGS ADD_FOREIGN_KEY = 1ULL << 22;
3227
3228 // Drop foreign key
3229 static const HA_ALTER_FLAGS DROP_FOREIGN_KEY = 1ULL << 23;
3230
3231 // table_options changed, see HA_CREATE_INFO::used_fields for details.
3232 static const HA_ALTER_FLAGS CHANGE_CREATE_OPTION = 1ULL << 24;
3233
3234 // Table is renamed
3235 static const HA_ALTER_FLAGS ALTER_RENAME = 1ULL << 25;
3236
3237 // Change the storage type of column
3239
3240 // Change the column format of column
3242
3243 // Add partition
3244 static const HA_ALTER_FLAGS ADD_PARTITION = 1ULL << 28;
3245
3246 // Drop partition
3247 static const HA_ALTER_FLAGS DROP_PARTITION = 1ULL << 29;
3248
3249 // Changing partition options
3250 static const HA_ALTER_FLAGS ALTER_PARTITION = 1ULL << 30;
3251
3252 // Coalesce partition
3253 static const HA_ALTER_FLAGS COALESCE_PARTITION = 1ULL << 31;
3254
3255 // Reorganize partition ... into
3256 static const HA_ALTER_FLAGS REORGANIZE_PARTITION = 1ULL << 32;
3257
3258 // Reorganize partition
3259 static const HA_ALTER_FLAGS ALTER_TABLE_REORG = 1ULL << 33;
3260
3261 // Remove partitioning
3263
3264 // Partition operation with ALL keyword
3265 static const HA_ALTER_FLAGS ALTER_ALL_PARTITION = 1ULL << 35;
3266
3267 /**
3268 Rename index. Note that we set this flag only if there are no other
3269 changes to the index being renamed. Also for simplicity we don't
3270 detect renaming of indexes which is done by dropping index and then
3271 re-creating index with identical definition under different name.
3272 */
3273 static const HA_ALTER_FLAGS RENAME_INDEX = 1ULL << 36;
3274
3275 /**
3276 Recreate the table for ALTER TABLE FORCE, ALTER TABLE ENGINE
3277 and OPTIMIZE TABLE operations.
3278 */
3279 static const HA_ALTER_FLAGS RECREATE_TABLE = 1ULL << 37;
3280
3281 // Add spatial index
3282 static const HA_ALTER_FLAGS ADD_SPATIAL_INDEX = 1ULL << 38;
3283
3284 // Alter index comment
3285 static const HA_ALTER_FLAGS ALTER_INDEX_COMMENT = 1ULL << 39;
3286
3287 // New/changed virtual generated column require validation
3288 static const HA_ALTER_FLAGS VALIDATE_VIRTUAL_COLUMN = 1ULL << 40;
3289
3290 /**
3291 Change index option in a way which is likely not to require index
3292 recreation. For example, change COMMENT or KEY::is_algorithm_explicit
3293 flag (without change of index algorithm itself).
3294 */
3295 static const HA_ALTER_FLAGS CHANGE_INDEX_OPTION = 1LL << 41;
3296
3297 // Rebuild partition
3298 static const HA_ALTER_FLAGS ALTER_REBUILD_PARTITION = 1ULL << 42;
3299
3300 /**
3301 Change in index length such that it does not require index rebuild.
3302 For example, change in index length due to column expansion like
3303 varchar(X) changed to varchar(X + N).
3304 */
3306
3307 /**
3308 Change to one of columns on which virtual generated column depends,
3309 so its values require re-evaluation.
3310 */
3311 static const HA_ALTER_FLAGS VIRTUAL_GCOL_REEVAL = 1ULL << 44;
3312
3313 /**
3314 Change to one of columns on which stored generated column depends,
3315 so its values require re-evaluation.
3316 */
3317 static const HA_ALTER_FLAGS STORED_GCOL_REEVAL = 1ULL << 45;
3318
3319 // Add check constraint.
3320 static const HA_ALTER_FLAGS ADD_CHECK_CONSTRAINT = 1ULL << 46;
3321
3322 // Drop check constraint.
3323 static const HA_ALTER_FLAGS DROP_CHECK_CONSTRAINT = 1ULL << 47;
3324
3325 // Suspend check constraint.
3326 static const HA_ALTER_FLAGS SUSPEND_CHECK_CONSTRAINT = 1ULL << 48;
3327
3328 // Alter column visibility.
3329 static const HA_ALTER_FLAGS ALTER_COLUMN_VISIBILITY = 1ULL << 49;
3330
3331 /**
3332 Create options (like MAX_ROWS) for the new version of table.
3333
3334 @note The referenced instance of HA_CREATE_INFO object was already
3335 used to create new .FRM file for table being altered. So it
3336 has been processed by mysql_prepare_create_table() already.
3337 For example, this means that it has HA_OPTION_PACK_RECORD
3338 flag in HA_CREATE_INFO::table_options member correctly set.
3339 */
3341
3342 /**
3343 Alter options, fields and keys for the new version of table.
3344
3345 @note The referenced instance of Alter_info object was already
3346 used to create new .FRM file for table being altered. So it
3347 has been processed by mysql_prepare_create_table() already.
3348 In particular, this means that in Create_field objects for
3349 fields which were present in some form in the old version
3350 of table, Create_field::field member points to corresponding
3351 Field instance for old version of table.
3352 */
3354
3355 /**
3356 Indicates whether operation should fail if table is non-empty.
3357 Storage engines should not suggest/allow execution of such operations
3358 using INSTANT algorithm since check whether table is empty done from
3359 SQL-layer is not "instant". Also SEs might choose different algorithm for
3360 ALTER TABLE execution knowing that it will be allowed to proceed only if
3361 table is empty.
3362
3363 Unlike for Alter_table_ctx::error_if_not_empty, we use bool for this flag
3364 and not bitmap, since SEs are really interested in the fact that ALTER
3365 will fail if table is not empty and not in exact reason behind this fact,
3366 and because we want to avoid extra dependency between Alter_table_ctx and
3367 Alter_inplace_info.
3368 */
3370
3371 /**
3372 Array of KEYs for new version of table - including KEYs to be added.
3373
3374 @note Currently this array is produced as result of
3375 mysql_prepare_create_table() call.
3376 This means that it follows different convention for
3377 KEY_PART_INFO::fieldnr values than objects in TABLE::key_info
3378 array.
3379
3380 @todo This is mainly due to the fact that we need to keep compatibility
3381 with removed handler::add_index() call. We plan to switch to
3382 TABLE::key_info numbering later.
3383
3384 KEYs are sorted - see sort_keys().
3385 */
3387
3388 /** Size of key_info_buffer array. */
3390
3391 /** Size of index_drop_buffer array. */
3393
3394 /**
3395 Array of pointers to KEYs to be dropped belonging to the TABLE instance
3396 for the old version of the table.
3397 */
3399
3400 /** Size of index_add_buffer array. */
3402
3403 /**
3404 Array of indexes into key_info_buffer for KEYs to be added,
3405 sorted in increasing order.
3406 */
3408
3409 /** Size of index_rename_buffer array. */
3411
3412 /** Size of index_rename_buffer array. */
3414
3415 /**
3416 Array of KEY_PAIR objects describing indexes being renamed.
3417 For each index renamed it contains object with KEY_PAIR::old_key
3418 pointing to KEY object belonging to the TABLE instance for old
3419 version of table representing old version of index and with
3420 KEY_PAIR::new_key pointing to KEY object for new version of
3421 index in key_info_buffer member.
3422 */
3425
3426 /** Number of virtual columns to be added. */
3428
3429 /** number of virtual columns to be dropped. */
3431
3432 /**
3433 Context information to allow handlers to keep context between in-place
3434 alter API calls.
3435
3436 @see inplace_alter_handler_ctx for information about object lifecycle.
3437 */
3439
3440 /**
3441 If the table uses several handlers, like ha_partition uses one handler
3442 per partition, this contains a Null terminated array of ctx pointers
3443 that should all be committed together.
3444 Or NULL if only handler_ctx should be committed.
3445 Set to NULL if the low level handler::commit_inplace_alter_table uses it,
3446 to signal to the main handler that everything was committed as atomically.
3447
3448 @see inplace_alter_handler_ctx for information about object lifecycle.
3449 */
3451
3452 /**
3453 Flags describing in detail which operations the storage engine is to
3454 execute.
3455 */
3457
3458 /**
3459 Partition_info taking into account the partition changes to be performed.
3460 Contains all partitions which are present in the old version of the table
3461 with partitions to be dropped or changed marked as such + all partitions
3462 to be added in the new version of table marked as such.
3463 */
3465
3466 /** true for online operation (LOCK=NONE) */
3468
3469 /**
3470 Can be set by handler along with handler_ctx. The difference is that
3471 this flag can be used to store SE-specific in-place ALTER context in cases
3472 when constructing full-blown inplace_alter_handler_ctx descendant is
3473 inconvenient.
3474 */
3476
3477 /**
3478 Can be set by handler to describe why a given operation cannot be done
3479 in-place (HA_ALTER_INPLACE_NOT_SUPPORTED) or why it cannot be done
3480 online (HA_ALTER_INPLACE_NO_LOCK or HA_ALTER_INPLACE_NO_LOCK_AFTER_PREPARE)
3481 If set, it will be used with ER_ALTER_OPERATION_NOT_SUPPORTED_REASON if
3482 results from handler::check_if_supported_inplace_alter() doesn't match
3483 requirements set by user. If not set, the more generic
3484 ER_ALTER_OPERATION_NOT_SUPPORTED will be used.
3485
3486 Please set to a properly localized string, for example using
3487 my_get_err_msg(), so that the error message as a whole is localized.
3488 */
3490
3492 Alter_info *alter_info_arg, bool error_if_not_empty_arg,
3493 KEY *key_info_arg, uint key_count_arg,
3494 partition_info *modified_part_info_arg)
3495 : create_info(create_info_arg),
3496 alter_info(alter_info_arg),
3497 error_if_not_empty(error_if_not_empty_arg),
3498 key_info_buffer(key_info_arg),
3499 key_count(key_count_arg),
3502 index_add_count(0),
3511 handler_flags(0),
3512 modified_part_info(modified_part_info_arg),
3513 online(false),
3516
3518
3519 /**
3520 Used after check_if_supported_inplace_alter() to report
3521 error if the result does not match the LOCK/ALGORITHM
3522 requirements set by the user.
3523
3524 @param not_supported Part of statement that was not supported.
3525 @param try_instead Suggestion as to what the user should
3526 replace not_supported with.
3527 */
3528 void report_unsupported_error(const char *not_supported,
3529 const char *try_instead);
3530
3531 /** Add old and new version of key to array of indexes to be renamed. */
3532 void add_renamed_key(KEY *old_key, KEY *new_key) {
3534 key_pair->old_key = old_key;
3535 key_pair->new_key = new_key;
3536 DBUG_PRINT("info",
3537 ("index renamed: '%s' to '%s'", old_key->name, new_key->name));
3538 }
3539
3540 void add_altered_index_visibility(KEY *old_key, KEY *new_key) {
3541 KEY_PAIR *key_pair =
3543 key_pair->old_key = old_key;
3544 key_pair->new_key = new_key;
3545 DBUG_PRINT("info", ("index had visibility altered: %i to %i",
3546 old_key->is_visible, new_key->is_visible));
3547 }
3548
3549 /**
3550 Add old and new version of modified key to arrays of indexes to
3551 be dropped and added (correspondingly).
3552 */
3553 void add_modified_key(KEY *old_key, KEY *new_key) {
3556 DBUG_PRINT("info", ("index changed: '%s'", old_key->name));
3557 }
3558
3559 /** Drop key to array of indexes to be dropped. */
3560 void add_dropped_key(KEY *old_key) {
3562 DBUG_PRINT("info", ("index dropped: '%s'", old_key->name));
3563 }
3564
3565 /** Add key to array of indexes to be added. */
3566 void add_added_key(KEY *new_key) {
3568 DBUG_PRINT("info", ("index added: '%s'", new_key->name));
3569 }
3570};
3571
3573 uint flags{0}; /* isam layer flags (e.g. for myisamchk) */
3574 uint sql_flags{0}; /* sql layer flags - for something myisamchk cannot do */
3575 KEY_CACHE *key_cache; /* new key cache when changing key cache */
3576};
3577
3578/*
3579 This is a buffer area that the handler can use to store rows.
3580 'end_of_used_area' should be kept updated after calls to
3581 read-functions so that other parts of the code can use the
3582 remaining area (until next read calls is issued).
3583*/
3584
3586 uchar *buffer; /* Buffer one can start using */
3587 uchar *buffer_end; /* End of buffer */
3588 uchar *end_of_used_area; /* End of area that was used by handler */
3589};
3590
3591typedef void *range_seq_t;
3592
3594 /*
3595 Initialize the traversal of range sequence
3596
3597 SYNOPSIS
3598 init()
3599 init_params The seq_init_param parameter
3600 n_ranges The number of ranges obtained
3601 flags A combination of HA_MRR_SINGLE_POINT, HA_MRR_FIXED_KEY
3602
3603 RETURN
3604 An opaque value to be used as RANGE_SEQ_IF::next() parameter
3605 */
3606 range_seq_t (*init)(void *init_params, uint n_ranges, uint flags);
3607
3608 /*
3609 Get the next range in the range sequence
3610
3611 SYNOPSIS
3612 next()
3613 seq The value returned by RANGE_SEQ_IF::init()
3614 range OUT Information about the next range
3615
3616 RETURN
3617 0 - Ok, the range structure filled with info about the next range
3618 1 - No more ranges
3619 */
3621
3622 /*
3623 Check whether range_info orders to skip the next record
3624
3625 SYNOPSIS
3626 skip_record()
3627 seq The value returned by RANGE_SEQ_IF::init()
3628 range_info Information about the next range
3629 (Ignored if MRR_NO_ASSOCIATION is set)
3630 rowid Rowid of the record to be checked (ignored if set to 0)
3631
3632 RETURN
3633 1 - Record with this range_info and/or this rowid shall be filtered
3634 out from the stream of records returned by ha_multi_range_read_next()
3635 0 - The record shall be left in the stream
3636 */
3637 bool (*skip_record)(range_seq_t seq, char *range_info, uchar *rowid);
3638};
3639
3640/**
3641 Used to store optimizer cost estimates.
3642
3643 The class consists of PODs only: default operator=, copy constructor
3644 and destructor are used.
3645 */
3647 private:
3648 double io_cost; ///< cost of I/O operations
3649 double cpu_cost; ///< cost of CPU operations
3650 double import_cost; ///< cost of remote operations
3651 double mem_cost; ///< memory used (bytes)
3652
3653 public:
3655
3656 /// Returns sum of time-consuming costs, i.e., not counting memory cost
3657 double total_cost() const { return io_cost + cpu_cost + import_cost; }
3658 double get_io_cost() const { return io_cost; }
3659 double get_cpu_cost() const { return cpu_cost; }
3660 double get_import_cost() const { return import_cost; }
3661 double get_mem_cost() const { return mem_cost; }
3662
3663 /**
3664 Whether or not all costs in the object are zero
3665
3666 @return true if all costs are zero, false otherwise
3667 */
3668 bool is_zero() const {
3669 return !(io_cost || cpu_cost || import_cost || mem_cost);
3670 }
3671 /**
3672 Whether or not the total cost is the maximal double
3673
3674 @return true if total cost is the maximal double, false otherwise
3675 */
3676 bool is_max_cost() const { return io_cost == DBL_MAX; }
3677 /// Reset all costs to zero
3679 /// Set current cost to the maximal double
3681 reset();
3682 io_cost = DBL_MAX;
3683 }
3684
3685 /// Multiply io, cpu and import costs by parameter
3686 void multiply(double m) {
3687 assert(!is_max_cost());
3688
3689 io_cost *= m;
3690 cpu_cost *= m;
3691 import_cost *= m;
3692 /* Don't multiply mem_cost */
3693 }
3694
3696 assert(!is_max_cost() && !other.is_max_cost());
3697
3698 io_cost += other.io_cost;
3699 cpu_cost += other.cpu_cost;
3700 import_cost += other.import_cost;
3701 mem_cost += other.mem_cost;
3702
3703 return *this;
3704 }
3705
3707 Cost_estimate result = *this;
3708 result += other;
3709
3710 return result;
3711 }
3712
3715
3716 assert(!other.is_max_cost());
3717
3718 result.io_cost = io_cost - other.io_cost;
3719 result.cpu_cost = cpu_cost - other.cpu_cost;
3720 result.import_cost = import_cost - other.import_cost;
3721 result.mem_cost = mem_cost - other.mem_cost;
3722 return result;
3723 }
3724
3725 bool operator>(const Cost_estimate &other) const {
3726 return total_cost() > other.total_cost() ? true : false;
3727 }
3728
3729 bool operator<(const Cost_estimate &other) const {
3730 return other > *this ? true : false;
3731 }
3732
3733 /// Add to IO cost
3734 void add_io(double add_io_cost) {
3735 assert(!is_max_cost());
3736 io_cost += add_io_cost;
3737 }
3738
3739 /// Add to CPU cost
3740 void add_cpu(double add_cpu_cost) {
3741 assert(!is_max_cost());
3742 cpu_cost += add_cpu_cost;
3743 }
3744
3745 /// Add to import cost
3746 void add_import(double add_import_cost) {
3747 assert(!is_max_cost());
3748 import_cost += add_import_cost;
3749 }
3750
3751 /// Add to memory cost
3752 void add_mem(double add_mem_cost) {
3753 assert(!is_max_cost());
3754 mem_cost += add_mem_cost;
3755 }
3756};
3757
3758void get_sweep_read_cost(TABLE *table, ha_rows nrows, bool interrupted,
3759 Cost_estimate *cost);
3760
3761/*
3762 The below two are not used (and not handled) in this milestone of this WL
3763 entry because there seems to be no use for them at this stage of
3764 implementation.
3765*/
3766#define HA_MRR_SINGLE_POINT 1
3767#define HA_MRR_FIXED_KEY 2
3768
3769/*
3770 Indicates that RANGE_SEQ_IF::next(&range) doesn't need to fill in the
3771 'range' parameter.
3772*/
3773#define HA_MRR_NO_ASSOCIATION 4
3774
3775/*
3776 The MRR user will provide ranges in key order, and MRR implementation
3777 must return rows in key order.
3778 Passing this flag to multi_read_range_init() may cause the
3779 default MRR handler to be used even if HA_MRR_USE_DEFAULT_IMPL
3780 was not specified.
3781 (If the native MRR impl. can not provide SORTED result)
3782*/
3783#define HA_MRR_SORTED 8
3784
3785/* MRR implementation doesn't have to retrieve full records */
3786#define HA_MRR_INDEX_ONLY 16
3787
3788/*
3789 The passed memory buffer is of maximum possible size, the caller can't
3790 assume larger buffer.
3791*/
3792#define HA_MRR_LIMITS 32
3793
3794/*
3795 Flag set <=> default MRR implementation is used
3796 (The choice is made by **_info[_const]() function which may set this
3797 flag. SQL layer remembers the flag value and then passes it to
3798 multi_read_range_init().
3799*/
3800#define HA_MRR_USE_DEFAULT_IMPL 64
3801
3802/*
3803 Used only as parameter to multi_range_read_info():
3804 Flag set <=> the caller guarantees that the bounds of the scanned ranges
3805 will not have NULL values.
3806*/
3807#define HA_MRR_NO_NULL_ENDPOINTS 128
3808
3809/*
3810 Set by the MRR implementation to signal that it will natively
3811 produced sorted result if multi_range_read_init() is called with
3812 the HA_MRR_SORTED flag - Else multi_range_read_init(HA_MRR_SORTED)
3813 will revert to use the default MRR implementation.
3814*/
3815#define HA_MRR_SUPPORT_SORTED 256
3816
3818 public:
3819 ulonglong data_file_length; /* Length off data file */
3820 ulonglong max_data_file_length; /* Length off data file */
3823 ulonglong delete_length; /* Free bytes */
3825 /*
3826 The number of records in the table.
3827 0 - means the table has exactly 0 rows
3828 other - if (table_flags() & HA_STATS_RECORDS_IS_EXACT)
3829 the value is the exact number of records in the table
3830 else
3831 it is an estimate
3832 */
3834 ha_rows deleted; /* Deleted records */
3835 ulong mean_rec_length; /* physical reclength */
3836 /* TODO: create_time should be retrieved from the new DD. Remove this. */
3837 time_t create_time; /* When table was created */
3840 uint block_size; /* index block size */
3841
3842 /*
3843 number of buffer bytes that native mrr implementation needs,
3844 */
3846
3847 /**
3848 Estimate for how much of the table that is available in a memory
3849 buffer. Valid range is [0..1]. If it has the special value
3850 IN_MEMORY_ESTIMATE_UNKNOWN (defined in structs.h), it means that
3851 the storage engine has not supplied any value for it.
3852 */
3854
3856 : data_file_length(0),
3859 delete_length(0),
3861 records(0),
3862 deleted(0),
3863 mean_rec_length(0),
3864 create_time(0),
3865 check_time(0),
3866 update_time(0),
3867 block_size(0),
3869};
3870
3871/**
3872 Calculates length of key.
3873
3874 Given a key index and a map of key parts return length of buffer used by key
3875 parts.
3876
3877 @param table Table containing the key
3878 @param key Key index
3879 @param keypart_map which key parts that is used
3880
3881 @return Length of used key parts.
3882*/
3883uint calculate_key_len(TABLE *table, uint key, key_part_map keypart_map);
3884/*
3885 bitmap with first N+1 bits set
3886 (keypart_map for a key prefix of [0..N] keyparts)
3887*/
3888#define make_keypart_map(N) (((key_part_map)2 << (N)) - 1)
3889/*
3890 bitmap with first N bits set
3891 (keypart_map for a key prefix of [0..N-1] keyparts)
3892*/
3893#define make_prev_keypart_map(N) (((key_part_map)1 << (N)) - 1)
3894
3895/** Base class to be used by handlers different shares */
3897 public:
3898 Handler_share() = default;
3899 virtual ~Handler_share() = default;
3900};
3901
3902/**
3903 Wrapper for struct ft_hints.
3904*/
3905
3907 private:
3909
3910 public:
3911 explicit Ft_hints(uint ft_flags) {
3912 hints.flags = ft_flags;
3914 hints.op_value = 0.0;
3916 }
3917
3918 /**
3919 Set comparison operation type and and value for master MATCH function.
3920
3921 @param type comparison operation type
3922 @param value comparison operation value
3923 */
3924 void set_hint_op(enum ft_operation type, double value) {
3925 hints.op_type = type;
3926 hints.op_value = value;
3927 }
3928
3929 /**
3930 Set Ft_hints flag.
3931
3932 @param ft_flag Ft_hints flag
3933 */
3934 void set_hint_flag(uint ft_flag) { hints.flags |= ft_flag; }
3935
3936 /**
3937 Set Ft_hints limit.
3938
3939 @param ft_limit limit
3940 */
3941 void set_hint_limit(ha_rows ft_limit) { hints.limit = ft_limit; }
3942
3943 /**
3944 Get Ft_hints limit.
3945
3946 @return Ft_hints limit
3947 */
3948 ha_rows get_limit() const { return hints.limit; }
3949
3950 /**
3951 Get Ft_hints operation value.
3952
3953 @return operation value
3954 */
3955 double get_op_value() const { return hints.op_value; }
3956
3957 /**
3958 Get Ft_hints operation type.
3959
3960 @return operation type
3961 */
3962 enum ft_operation get_op_type() const { return hints.op_type; }
3963
3964 /**
3965 Get Ft_hints flags.
3966
3967 @return Ft_hints flags
3968 */
3969 uint get_flags() const { return hints.flags; }
3970
3971 /**
3972 Get ft_hints struct.
3973
3974 @return pointer to ft_hints struct
3975 */
3977 return &hints;
3978 }
3979};
3980
3981/**
3982 The handler class is the interface for dynamically loadable
3983 storage engines. Do not add ifdefs and take care when adding or
3984 changing virtual functions to avoid vtable confusion
3985
3986 Functions in this class accept and return table columns data. Two data
3987 representation formats are used:
3988 1. TableRecordFormat - Used to pass [partial] table records to/from
3989 storage engine
3990
3991 2. KeyTupleFormat - used to pass index search tuples (aka "keys") to
3992 storage engine. See opt_range.cc for description of this format.
3993
3994 TableRecordFormat
3995 =================
3996 [Warning: this description is work in progress and may be incomplete]
3997 The table record is stored in a fixed-size buffer:
3998
3999 record: null_bytes, column1_data, column2_data, ...
4000
4001 The offsets of the parts of the buffer are also fixed: every column has
4002 an offset to its column{i}_data, and if it is nullable it also has its own
4003 bit in null_bytes.
4004
4005 The record buffer only includes data about columns that are marked in the
4006 relevant column set (table->read_set and/or table->write_set, depending on
4007 the situation).
4008 <not-sure>It could be that it is required that null bits of non-present
4009 columns are set to 1</not-sure>
4010
4011 VARIOUS EXCEPTIONS AND SPECIAL CASES
4012
4013 If the table has no nullable columns, then null_bytes is still
4014 present, its length is one byte <not-sure> which must be set to 0xFF
4015 at all times. </not-sure>
4016
4017 If the table has columns of type BIT, then certain bits from those columns
4018 may be stored in null_bytes as well. Grep around for Field_bit for
4019 details.
4020
4021 For blob columns (see Field_blob), the record buffer stores length of the
4022 data, following by memory pointer to the blob data. The pointer is owned
4023 by the storage engine and is valid until the next operation.
4024
4025 If a blob column has NULL value, then its length and blob data pointer
4026 must be set to 0.
4027
4028
4029 Overview of main modules of the handler API
4030 ===========================================
4031 The overview below was copied from the storage/partition/ha_partition.h when
4032 support for non-native partitioning was removed.
4033
4034 -------------------------------------------------------------------------
4035 MODULE create/delete handler object
4036 -------------------------------------------------------------------------
4037 Object create/delete method. Normally called when a table object
4038 exists.
4039
4040 -------------------------------------------------------------------------
4041 MODULE meta data changes
4042 -------------------------------------------------------------------------
4043 Meta data routines to CREATE, DROP, RENAME table are often used at
4044 ALTER TABLE (update_create_info used from ALTER TABLE and SHOW ..).
4045
4046 Methods:
4047 delete_table()
4048 rename_table()
4049 create()
4050 update_create_info()
4051
4052 -------------------------------------------------------------------------
4053 MODULE open/close object
4054 -------------------------------------------------------------------------
4055 Open and close handler object to ensure all underlying files and
4056 objects allocated and deallocated for query handling is handled
4057 properly.
4058
4059 A handler object is opened as part of its initialisation and before
4060 being used for normal queries (not before meta-data changes always.
4061 If the object was opened it will also be closed before being deleted.
4062
4063 Methods:
4064 open()
4065 close()
4066
4067 -------------------------------------------------------------------------
4068 MODULE start/end statement
4069 -------------------------------------------------------------------------
4070 This module contains methods that are used to understand start/end of
4071 statements, transaction boundaries, and aid for proper concurrency
4072 control.
4073
4074 Methods:
4075 store_lock()
4076 external_lock()
4077 start_stmt()
4078 lock_count()
4079 unlock_row()
4080 was_semi_consistent_read()
4081 try_semi_consistent_read()
4082
4083 -------------------------------------------------------------------------
4084 MODULE change record
4085 -------------------------------------------------------------------------
4086 This part of the handler interface is used to change the records
4087 after INSERT, DELETE, UPDATE, REPLACE method calls but also other
4088 special meta-data operations as ALTER TABLE, LOAD DATA, TRUNCATE.
4089
4090 These methods are used for insert (write_row), update (update_row)
4091 and delete (delete_row). All methods to change data always work on
4092 one row at a time. update_row and delete_row also contains the old
4093 row.
4094 delete_all_rows will delete all rows in the table in one call as a
4095 special optimization for DELETE from table;
4096
4097 Bulk inserts are supported if all underlying handlers support it.
4098 start_bulk_insert and end_bulk_insert is called before and after a
4099 number of calls to write_row.
4100
4101 Methods:
4102 write_row()
4103 update_row()
4104 delete_row()
4105 delete_all_rows()
4106 start_bulk_insert()
4107 end_bulk_insert()
4108
4109 -------------------------------------------------------------------------
4110 MODULE full table scan
4111 -------------------------------------------------------------------------
4112 This module is used for the most basic access method for any table
4113 handler. This is to fetch all data through a full table scan. No
4114 indexes are needed to implement this part.
4115 It contains one method to start the scan (rnd_init) that can also be
4116 called multiple times (typical in a nested loop join). Then proceeding
4117 to the next record (rnd_next) and closing the scan (rnd_end).
4118 To remember a record for later access there is a method (position)
4119 and there is a method used to retrieve the record based on the stored
4120 position.
4121 The position can be a file position, a primary key, a ROWID dependent
4122 on the handler below.
4123
4124 All functions that retrieve records and are callable through the
4125 handler interface must indicate whether a record is present after the call
4126 or not. Record found is indicated by returning 0 and setting table status
4127 to "has row". Record not found is indicated by returning a non-zero value
4128 and setting table status to "no row".
4129 @see TABLE::set_found_row() and TABLE::set_no_row().
4130 By enforcing these rules in the handler interface, storage handler functions
4131 need not set any status in struct TABLE. These notes also apply to module
4132 index scan, documented below.
4133
4134 Methods:
4135
4136 rnd_init()
4137 rnd_end()
4138 rnd_next()
4139 rnd_pos()
4140 rnd_pos_by_record()
4141 position()
4142
4143 -------------------------------------------------------------------------
4144 MODULE index scan
4145 -------------------------------------------------------------------------
4146 This part of the handler interface is used to perform access through
4147 indexes. The interface is defined as a scan interface but the handler
4148 can also use key lookup if the index is a unique index or a primary
4149 key index.
4150 Index scans are mostly useful for SELECT queries but are an important
4151 part also of UPDATE, DELETE, REPLACE and CREATE TABLE table AS SELECT
4152 and so forth.
4153 Naturally an index is needed for an index scan and indexes can either
4154 be ordered, hash based. Some ordered indexes can return data in order
4155 but not necessarily all of them.
4156 There are many flags that define the behavior of indexes in the
4157 various handlers. These methods are found in the optimizer module.
4158
4159 index_read is called to start a scan of an index. The find_flag defines
4160 the semantics of the scan. These flags are defined in
4161 include/my_base.h
4162 index_read_idx is the same but also initializes index before calling doing
4163 the same thing as index_read. Thus it is similar to index_init followed
4164 by index_read. This is also how we implement it.
4165
4166 index_read/index_read_idx does also return the first row. Thus for
4167 key lookups, the index_read will be the only call to the handler in
4168 the index scan.
4169
4170 index_init initializes an index before using it and index_end does
4171 any end processing needed.
4172
4173 Methods:
4174 index_read_map()
4175 index_init()
4176 index_end()
4177 index_read_idx_map()
4178 index_next()
4179 index_prev()
4180 index_first()
4181 index_last()
4182 index_next_same()
4183 index_read_last_map()
4184 read_range_first()
4185 read_range_next()
4186
4187 -------------------------------------------------------------------------
4188 MODULE information calls
4189 -------------------------------------------------------------------------
4190 This calls are used to inform the handler of specifics of the ongoing
4191 scans and other actions. Most of these are used for optimisation
4192 purposes.
4193
4194 Methods:
4195 info()
4196 get_dynamic_partition_info
4197 extra()
4198 extra_opt()
4199 reset()
4200
4201 -------------------------------------------------------------------------
4202 MODULE optimizer support
4203 -------------------------------------------------------------------------
4204 NOTE:
4205 One important part of the public handler interface that is not depicted in
4206 the methods is the attribute records which is defined in the base class.
4207 This is looked upon directly and is set by calling info(HA_STATUS_INFO) ?
4208
4209 Methods:
4210 min_rows_for_estimate()
4211 get_biggest_used_partition()
4212 scan_time()
4213 read_time()
4214 records_in_range()
4215 estimate_rows_upper_bound()
4216 records()
4217
4218 -------------------------------------------------------------------------
4219 MODULE print messages
4220 -------------------------------------------------------------------------
4221 This module contains various methods that returns text messages for
4222 table types, index type and error messages.
4223
4224 Methods:
4225 table_type()
4226 get_row_type()
4227 print_error()
4228 get_error_message()
4229
4230 -------------------------------------------------------------------------
4231 MODULE handler characteristics
4232 -------------------------------------------------------------------------
4233 This module contains a number of methods defining limitations and
4234 characteristics of the handler (see also documentation regarding the
4235 individual flags).
4236
4237 Methods:
4238 table_flags()
4239 index_flags()
4240 min_of_the_max_uint()
4241 max_supported_record_length()
4242 max_supported_keys()
4243 max_supported_key_parts()
4244 max_supported_key_length()
4245 max_supported_key_part_length()
4246 low_byte_first()
4247 extra_rec_buf_length()
4248 min_record_length(uint options)
4249 primary_key_is_clustered()
4250 ha_key_alg get_default_index_algorithm()
4251 is_index_algorithm_supported()
4252
4253 -------------------------------------------------------------------------
4254 MODULE compare records
4255 -------------------------------------------------------------------------
4256 cmp_ref checks if two references are the same. For most handlers this is
4257 a simple memcmp of the reference. However some handlers use primary key
4258 as reference and this can be the same even if memcmp says they are
4259 different. This is due to character sets and end spaces and so forth.
4260
4261 Methods:
4262 cmp_ref()
4263
4264 -------------------------------------------------------------------------
4265 MODULE auto increment
4266 -------------------------------------------------------------------------
4267 This module is used to handle the support of auto increments.
4268
4269 This variable in the handler is used as part of the handler interface
4270 It is maintained by the parent handler object and should not be
4271 touched by child handler objects (see handler.cc for its use).
4272
4273 Methods:
4274 get_auto_increment()
4275 release_auto_increment()
4276
4277 -------------------------------------------------------------------------
4278 MODULE initialize handler for HANDLER call
4279 -------------------------------------------------------------------------
4280 This method is a special InnoDB method called before a HANDLER query.
4281
4282 Methods:
4283 init_table_handle_for_HANDLER()
4284
4285 -------------------------------------------------------------------------
4286 MODULE fulltext index
4287 -------------------------------------------------------------------------
4288 Fulltext index support.
4289
4290 Methods:
4291 ft_init_ext_with_hints()
4292 ft_init()
4293 ft_init_ext()
4294 ft_read()
4295
4296 -------------------------------------------------------------------------
4297 MODULE in-place ALTER TABLE
4298 -------------------------------------------------------------------------
4299 Methods for in-place ALTER TABLE support (implemented by InnoDB and NDB).
4300
4301 Methods:
4302 check_if_supported_inplace_alter()
4303 prepare_inplace_alter_table()
4304 inplace_alter_table()
4305 commit_inplace_alter_table()
4306 notify_table_changed()
4307
4308 -------------------------------------------------------------------------
4309 MODULE tablespace support
4310 -------------------------------------------------------------------------
4311 Methods:
4312 discard_or_import_tablespace()
4313
4314 -------------------------------------------------------------------------
4315 MODULE administrative DDL
4316 -------------------------------------------------------------------------
4317 Methods:
4318 optimize()
4319 analyze()
4320 check()
4321 repair()
4322 check_and_repair()
4323 auto_repair()
4324 is_crashed()
4325 check_for_upgrade()
4326 checksum()
4327 assign_to_keycache()
4328
4329 -------------------------------------------------------------------------
4330 MODULE enable/disable indexes
4331 -------------------------------------------------------------------------
4332 Enable/Disable Indexes are only supported by HEAP and MyISAM.
4333
4334 Methods:
4335 disable_indexes()
4336 enable_indexes()
4337 indexes_are_disabled()
4338
4339 -------------------------------------------------------------------------
4340 MODULE append_create_info
4341 -------------------------------------------------------------------------
4342 Only used by MyISAM MERGE tables.
4343
4344 Methods:
4345 append_create_info()
4346
4347 -------------------------------------------------------------------------
4348 MODULE partitioning specific handler API
4349 -------------------------------------------------------------------------
4350 Methods:
4351 get_partition_handler()
4352*/
4353
4354class handler {
4355 friend class Partition_handler;
4356
4357 public:
4359
4360 protected:
4361 TABLE_SHARE *table_share; /* The table definition */
4362 TABLE *table; /* The current open table */
4363 Table_flags cached_table_flags{0}; /* Set on init() and open() */
4364
4366
4367 public:
4368 handlerton *ht; /* storage engine of this handler */
4369 /** Pointer to current row */
4371 /** Pointer to duplicate row */
4373
4375
4376 /* MultiRangeRead-related members: */
4377 range_seq_t mrr_iter; /* Iterator to traverse the range sequence */
4378 RANGE_SEQ_IF mrr_funcs; /* Range sequence traversal functions */
4379 HANDLER_BUFFER *multi_range_buffer; /* MRR buffer info */
4380 uint ranges_in_seq; /* Total number of ranges in the traversed sequence */
4381 /* true <=> source MRR ranges and the output are ordered */
4383
4384 /* true <=> we're currently traversing a range in mrr_cur_range. */
4386 /* Current range (the one we're now returning rows from) */
4388
4389 /*
4390 The direction of the current range or index scan. This is used by
4391 the ICP implementation to determine if it has reached the end
4392 of the current range.
4393 */
4395
4396 private:
4397 Record_buffer *m_record_buffer = nullptr; ///< Buffer for multi-row reads.
4398 /*
4399 Storage space for the end range value. Should only be accessed using
4400 the end_range pointer. The content is invalid when end_range is NULL.
4401 */
4405
4406 /**
4407 Pointer to the handler of the table in the primary storage engine,
4408 if this handler represents a table in a secondary storage engine.
4409 */
4411
4412 protected:
4415 /*
4416 true <=> the engine guarantees that returned records are within the range
4417 being scanned.
4418 */
4420
4421 public:
4422 /**
4423 End value for a range scan. If this is NULL the range scan has no
4424 end value. Should also be NULL when there is no ongoing range scan.
4425 Used by the read_range() functions and also evaluated by pushed
4426 index conditions.
4427 */
4429 /**
4430 Flag which tells if #end_range contains a virtual generated column.
4431 The content is invalid when #end_range is @c nullptr.
4432 */
4434 uint errkey; /* Last dup key */
4437 /** Length of ref (1-8 or the clustered key length) */
4440 enum { NONE = 0, INDEX, RND, SAMPLING } inited;
4441 bool implicit_emptied; /* Can be !=0 only if HEAP */
4443
4445 uint pushed_idx_cond_keyno; /* The index which the above condition is for */
4446
4447 /**
4448 next_insert_id is the next value which should be inserted into the
4449 auto_increment column: in a inserting-multi-row statement (like INSERT
4450 SELECT), for the first row where the autoinc value is not specified by the
4451 statement, get_auto_increment() called and asked to generate a value,
4452 next_insert_id is set to the next value, then for all other rows
4453 next_insert_id is used (and increased each time) without calling
4454 get_auto_increment().
4455 */
4457 /**
4458 insert id for the current row (*autogenerated*; if not
4459 autogenerated, it's 0).
4460 At first successful insertion, this variable is stored into
4461 THD::first_successful_insert_id_in_cur_stmt.
4462 */
4464 /**
4465 Interval returned by get_auto_increment() and being consumed by the
4466 inserter.
4467 */
4469 /**
4470 Number of reserved auto-increment intervals. Serves as a heuristic
4471 when we have no estimation of how many records the statement will insert:
4472 the more intervals we have reserved, the bigger the next one. Reset in
4473 handler::ha_release_auto_increment().
4474 */
4476
4477 /**
4478 Instrumented table associated with this handler.
4479 */
4481
4484
4485 private:
4486 /** Internal state of the batch instrumentation. */
4488 /** Batch mode not used. */
4490 /** Batch mode used, before first table io. */
4492 /** Batch mode used, after first table io. */
4495 /**
4496 Batch mode state.
4497 @sa start_psi_batch_mode.
4498 @sa end_psi_batch_mode.
4499 */
4501 /**
4502 The number of rows in the batch.
4503 @sa start_psi_batch_mode.
4504 @sa end_psi_batch_mode.
4505 */
4507 /**
4508 The current event in a batch.
4509 @sa start_psi_batch_mode.
4510 @sa end_psi_batch_mode.
4511 */
4513 /**
4514 Storage for the event in a batch.
4515 @sa start_psi_batch_mode.
4516 @sa end_psi_batch_mode.
4517 */
4519
4520 public:
4521 void unbind_psi();
4522 void rebind_psi();
4523 /**
4524 Put the handler in 'batch' mode when collecting
4525 table io instrumented events.
4526 When operating in batch mode:
4527 - a single start event is generated in the performance schema.
4528 - all table io performed between @c start_psi_batch_mode
4529 and @c end_psi_batch_mode is not instrumented:
4530 the number of rows affected is counted instead in @c m_psi_numrows.
4531 - a single end event is generated in the performance schema
4532 when the batch mode ends with @c end_psi_batch_mode.
4533 */
4534 void start_psi_batch_mode();
4535 /** End a batch started with @c start_psi_batch_mode. */
4536 void end_psi_batch_mode();
4537 /**
4538 If a PSI batch was started, turn if off.
4539 @returns true if it was started.
4540 */
4542 bool rc = m_psi_batch_mode;
4543 if (rc) end_psi_batch_mode();
4544 return rc;
4545 }
4546
4547 private:
4548 /**
4549 The lock type set by when calling::ha_external_lock(). This is
4550 propagated down to the storage engine. The reason for also storing
4551 it here, is that when doing MRR we need to create/clone a second handler
4552 object. This cloned handler object needs to know about the lock_type used.
4553 */
4555 /**
4556 Pointer where to store/retrieve the Handler_share pointer.
4557 For non partitioned handlers this is &TABLE_SHARE::ha_share.
4558 */
4560
4561 /**
4562 Some non-virtual ha_* functions, responsible for reading rows,
4563 like ha_rnd_pos(), must ensure that virtual generated columns are
4564 calculated before they return. For that, they should set this
4565 member to true at their start, and check it before they return: if
4566 the member is still true, it means they should calculate; if it's
4567 false, it means the calculation has been done by some called
4568 lower-level function and does not need to be re-done (which is why
4569 we need this status flag: to avoid redundant calculations, for
4570 performance).
4571
4572 Note that when updating generated fields, the NULL row status in
4573 the underlying TABLE objects matter, so be sure to reset them if needed!
4574 */
4576
4577 /* Filter row ids to weed out duplicates when multi-valued index is used */
4579
4580 public:
4581 handler(handlerton *ht_arg, TABLE_SHARE *share_arg)
4582 : table_share(share_arg),
4583 table(nullptr),
4585 ht(ht_arg),
4586 ref(nullptr),
4592 ref_length(sizeof(my_off_t)),
4594 inited(NONE),
4595 implicit_emptied(false),
4599 next_insert_id(0),
4602 m_psi(nullptr),
4604 m_psi_numrows(0),
4606 m_lock_type(F_UNLCK),
4609 m_unique(nullptr) {
4610 DBUG_PRINT("info", ("handler created F_UNLCK %d F_RDLCK %d F_WRLCK %d",
4611 F_UNLCK, F_RDLCK, F_WRLCK));
4612 }
4613
4614 virtual ~handler(void) {
4615 assert(m_psi == nullptr);
4617 assert(m_psi_locker == nullptr);
4618 assert(m_lock_type == F_UNLCK);
4619 assert(inited == NONE);
4620 }
4621
4622 /**
4623 Return extra handler specific text for EXPLAIN.
4624 */
4625 virtual std::string explain_extra() const { return ""; }
4626
4627 /*
4628 @todo reorganize functions, make proper public/protected/private qualifiers
4629 */
4630 virtual handler *clone(const char *name, MEM_ROOT *mem_root);
4631 /** This is called after create to allow us to set up cached variables */
4633 /* ha_ methods: public wrappers for private virtual API */
4634
4635 /**
4636 Set a record buffer that the storage engine can use for multi-row reads.
4637 The buffer has to be provided prior to the first read from an index or a
4638 table.
4639
4640 @param buffer the buffer to use for multi-row reads
4641 */
4643
4644 /**
4645 Get the record buffer that was set with ha_set_record_buffer().
4646
4647 @return the buffer to use for multi-row reads, or nullptr if there is none
4648 */
4650
4651 /**
4652 Does this handler want to get a Record_buffer for multi-row reads
4653 via the ha_set_record_buffer() function? And if so, what is the
4654 maximum number of records to allocate space for in the buffer?
4655
4656 Storage engines that support using a Record_buffer should override
4657 handler::is_record_buffer_wanted().
4658
4659 @param[out] max_rows gets set to the maximum number of records to
4660 allocate space for in the buffer if the function
4661 returns true
4662
4663 @retval true if the handler would like a Record_buffer
4664 @retval false if the handler does not want a Record_buffer
4665 */
4666 bool ha_is_record_buffer_wanted(ha_rows *const max_rows) const {
4667 return is_record_buffer_wanted(max_rows);
4668 }
4669
4670 int ha_open(TABLE *table, const char *name, int mode, int test_if_locked,
4671 const dd::Table *table_def);
4672 int ha_close(void);
4673 int ha_index_init(uint idx, bool sorted);
4674 int ha_index_end();
4675 int ha_rnd_init(bool scan);
4676 int ha_rnd_end();
4677 int ha_rnd_next(uchar *buf);
4678 // See the comment on m_update_generated_read_fields.
4679 int ha_rnd_pos(uchar *buf, uchar *pos);
4680 int ha_index_read_map(uchar *buf, const uchar *key, key_part_map keypart_map,
4681 enum ha_rkey_function find_flag);
4683 key_part_map keypart_map);
4684 int ha_index_read_idx_map(uchar *buf, uint index, const uchar *key,
4685 key_part_map keypart_map,
4686 enum ha_rkey_function find_flag);
4687 int ha_index_next(uchar *buf);
4688 int ha_index_prev(uchar *buf);
4689 int ha_index_first(uchar *buf);
4690 int ha_index_last(uchar *buf);
4691 int ha_index_next_same(uchar *buf, const uchar *key, uint keylen);
4692 int ha_reset();
4693 /* this is necessary in many places, e.g. in HANDLER command */
4695 return inited == INDEX ? ha_index_end() : inited == RND ? ha_rnd_end() : 0;
4696 }
4697 /**
4698 The cached_table_flags is set at ha_open and ha_external_lock
4699 */
4701 /**
4702 These functions represent the public interface to *users* of the
4703 handler class, hence they are *not* virtual. For the inheritance
4704 interface, see the (private) functions write_row(), update_row(),
4705 and delete_row() below.
4706 */
4707 int ha_external_lock(THD *thd, int lock_type);
4708 int ha_write_row(uchar *buf);
4709 /**
4710 Update the current row.
4711
4712 @param old_data the old contents of the row
4713 @param new_data the new contents of the row
4714 @return error status (zero on success, HA_ERR_* error code on error)
4715 */
4716 int ha_update_row(const uchar *old_data, uchar *new_data);
4717 int ha_delete_row(const uchar *buf);
4719
4720 int ha_check_for_upgrade(HA_CHECK_OPT *check_opt);
4721 /** to be actually called to get 'check()' functionality*/
4722 int ha_check(THD *thd, HA_CHECK_OPT *check_opt);
4723 int ha_repair(THD *thd, HA_CHECK_OPT *check_opt);
4724 void ha_start_bulk_insert(ha_rows rows);
4725 int ha_end_bulk_insert();
4726 int ha_bulk_update_row(const uchar *old_data, uchar *new_data,
4727 uint *dup_key_found);
4728 int ha_delete_all_rows();
4730 int ha_optimize(THD *thd, HA_CHECK_OPT *check_opt);
4731 int ha_analyze(THD *thd, HA_CHECK_OPT *check_opt);
4732 bool ha_check_and_repair(THD *thd);
4736 int ha_rename_table(const char *from, const char *to,
4737 const dd::Table *from_table_def, dd::Table *to_table_def);
4738 int ha_delete_table(const char *name, const dd::Table *table_def);
4739 void ha_drop_table(const char *name);
4740
4741 int ha_create(const char *name, TABLE *form, HA_CREATE_INFO *info,
4743
4744 int ha_load_table(const TABLE &table);
4745
4746 int ha_unload_table(const char *db_name, const char *table_name,
4747 bool error_if_not_loaded);
4748
4749 /**
4750 Initializes a parallel scan. It creates a parallel_scan_ctx that has to
4751 be used across all parallel_scan methods. Also, gets the number of
4752 threads that would be spawned for parallel scan.
4753 @param[out] scan_ctx The parallel scan context.
4754 @param[out] num_threads Number of threads used for the scan.
4755 @param[in] use_reserved_threads true if reserved threads are to be used
4756 if we exhaust the max cap of number of
4757 parallel read threads that can be
4758 spawned at a time
4759 @return error code
4760 @retval 0 on success
4761 */
4762 virtual int parallel_scan_init(void *&scan_ctx [[maybe_unused]],
4763 size_t *num_threads [[maybe_unused]],
4764 bool use_reserved_threads [[maybe_unused]]) {
4765 return 0;
4766 }
4767
4768 /**
4769 This callback is called by each parallel load thread at the beginning of
4770 the parallel load for the adapter scan.
4771 @param cookie The cookie for this thread
4772 @param ncols Number of columns in each row
4773 @param row_len The size of a row in bytes
4774 @param col_offsets An array of size ncols, where each element represents
4775 the offset of a column in the row data. The memory of
4776 this array belongs to the caller and will be free-ed
4777 after the pload_end_cbk call.
4778 @param null_byte_offsets An array of size ncols, where each element
4779 represents the offset of a column in the row data. The
4780 memory of this array belongs to the caller and will be
4781 free-ed after the pload_end_cbk call.
4782 @param null_bitmasks An array of size ncols, where each element
4783 represents the bitmask required to get the null bit. The
4784 memory of this array belongs to the caller and will be
4785 free-ed after the pload_end_cbk call.
4786 */
4787 using Load_init_cbk = std::function<bool(
4788 void *cookie, ulong ncols, ulong row_len, const ulong *col_offsets,
4789 const ulong *null_byte_offsets, const ulong *null_bitmasks)>;
4790
4791 /**
4792 This callback is called by each parallel load thread when processing
4793 of rows is required for the adapter scan.
4794 @param[in] cookie The cookie for this thread
4795 @param[in] nrows The nrows that are available
4796 @param[in] rowdata The mysql-in-memory row data buffer. This is a
4797 memory buffer for nrows records. The length of each record is fixed and
4798 communicated via Load_init_cbk
4799 @param[in] partition_id Partition id if it's a partitioned table, else
4800 std::numeric_limits<uint64_t>::max()
4801 @returns true if there is an error, false otherwise.
4802 */
4803 using Load_cbk = std::function<bool(void *cookie, uint nrows, void *rowdata,
4804 uint64_t partition_id)>;
4805
4806 /**
4807 This callback is called by each parallel load thread when processing
4808 of rows has ended for the adapter scan.
4809 @param[in] cookie The cookie for this thread
4810 */
4811 using Load_end_cbk = std::function<void(void *cookie)>;
4812
4813 /**
4814 Run the parallel read of data.
4815 @param[in] scan_ctx Scan context of the parallel read.
4816 @param[in,out] thread_ctxs Caller thread contexts.
4817 @param[in] init_fn Callback called by each parallel load
4818 thread at the beginning of the parallel load.
4819 @param[in] load_fn Callback called by each parallel load
4820 thread when processing of rows is required.
4821 @param[in] end_fn Callback called by each parallel load
4822 thread when processing of rows has ended.
4823 @return error code
4824 @retval 0 on success
4825 */
4826 virtual int parallel_scan(void *scan_ctx [[maybe_unused]],
4827 void **thread_ctxs [[maybe_unused]],
4828 Load_init_cbk init_fn [[maybe_unused]],
4829 Load_cbk load_fn [[maybe_unused]],
4830 Load_end_cbk end_fn [[maybe_unused]]) {
4831 return 0;
4832 }
4833
4834 /**
4835 End of the parallel scan.
4836 @param[in] scan_ctx A scan context created by parallel_scan_init.
4837 */
4838 virtual void parallel_scan_end(void *scan_ctx [[maybe_unused]]) { return; }
4839
4840 /**
4841 Submit a dd::Table object representing a core DD table having
4842 hardcoded data to be filled in by the DDSE. This function can be
4843 used for retrieving the hard coded SE private data for the
4844 mysql.dd_properties table, before creating or opening it, or for
4845 retrieving the hard coded SE private data for a core table,
4846 before creating or opening them.
4847
4848 @param dd_table [in,out] A dd::Table object representing
4849 a core DD table.
4850 @param reset Reset counters.
4851
4852 @retval true An error occurred.
4853 @retval false Success - no errors.
4854 */
4855
4856 bool ha_get_se_private_data(dd::Table *dd_table, bool reset);
4857
4860 virtual void print_error(int error, myf errflag);
4861 virtual bool get_error_message(int error, String *buf);
4862 uint get_dup_key(int error);
4863 /**
4864 Retrieves the names of the table and the key for which there was a
4865 duplicate entry in the case of HA_ERR_FOREIGN_DUPLICATE_KEY.
4866
4867 If any of the table or key name is not available this method will return
4868 false and will not change any of child_table_name or child_key_name.
4869
4870 @param [out] child_table_name Table name
4871 @param [in] child_table_name_len Table name buffer size
4872 @param [out] child_key_name Key name
4873 @param [in] child_key_name_len Key name buffer size
4874
4875 @retval true table and key names were available
4876 and were written into the corresponding
4877 out parameters.
4878 @retval false table and key names were not available,
4879 the out parameters were not touched.
4880 */
4881 virtual bool get_foreign_dup_key(char *child_table_name,
4882 uint child_table_name_len,
4883 char *child_key_name,
4884 uint child_key_name_len);
4885 /**
4886 Change the internal TABLE_SHARE pointer.
4887
4888 @param table_arg TABLE object
4889 @param share New share to use
4890
4891 @note Is used in error handling in ha_delete_table.
4892 */
4893
4894 virtual void change_table_ptr(TABLE *table_arg, TABLE_SHARE *share) {
4895 table = table_arg;
4896 table_share = share;
4897 }
4898 const TABLE_SHARE *get_table_share() const { return table_share; }
4899
4900 /* Estimates calculation */
4901
4902 /**
4903 @deprecated This function is deprecated and will be removed in a future
4904 version. Use table_scan_cost() instead.
4905 */
4906
4907 virtual double scan_time() {
4908 return ulonglong2double(stats.data_file_length) / IO_SIZE + 2;
4909 }
4910
4911 /**
4912 The cost of reading a set of ranges from the table using an index
4913 to access it.
4914
4915 @deprecated This function is deprecated and will be removed in a future
4916 version. Use read_cost() instead.
4917
4918 @param index The index number.
4919 @param ranges The number of ranges to be read.
4920 @param rows Total number of rows to be read.
4921
4922 This method can be used to calculate the total cost of scanning a table
4923 using an index by calling it using read_time(index, 1, table_size).
4924 */
4925
4926 virtual double read_time(uint index [[maybe_unused]], uint ranges,
4927 ha_rows rows) {
4928 return rows2double(ranges + rows);
4929 }
4930
4931 /**
4932 @deprecated This function is deprecated and will be removed in a future
4933 version. Use index_scan_cost() instead.
4934 */
4935
4936 virtual double index_only_read_time(uint keynr, double records);
4937
4938 /**
4939 Cost estimate for doing a complete table scan.
4940
4941 @note For this version it is recommended that storage engines continue
4942 to override scan_time() instead of this function.
4943
4944 @returns the estimated cost
4945 */
4946
4948
4949 /**
4950 Cost estimate for reading a number of ranges from an index.
4951
4952 The cost estimate will only include the cost of reading data that
4953 is contained in the index. If the records need to be read, use
4954 read_cost() instead.
4955
4956 @note The ranges parameter is currently ignored and is not taken
4957 into account in the cost estimate.
4958
4959 @note For this version it is recommended that storage engines continue
4960 to override index_only_read_time() instead of this function.
4961
4962 @param index the index number
4963 @param ranges the number of ranges to be read
4964 @param rows total number of rows to be read
4965
4966 @returns the estimated cost
4967 */
4968
4969 virtual Cost_estimate index_scan_cost(uint index, double ranges, double rows);
4970
4971 /**
4972 Cost estimate for reading a set of ranges from the table using an index
4973 to access it.
4974
4975 @note For this version it is recommended that storage engines continue
4976 to override read_time() instead of this function.
4977
4978 @param index the index number
4979 @param ranges the number of ranges to be read
4980 @param rows total number of rows to be read
4981
4982 @returns the estimated cost
4983 */
4984
4985 virtual Cost_estimate read_cost(uint index, double ranges, double rows);
4986
4987 /**
4988 Cost estimate for doing a number of non-sequentially accesses
4989 against the storage engine. Such accesses can be either number
4990 of rows to read, or number of disk pages to access.
4991 Each handler implementation is free to interpret that as best
4992 suited, depending on what is the dominating cost for that
4993 storage engine.
4994
4995 This method is mainly provided as a temporary workaround for
4996 bug#33317872, where we fix problems caused by calling
4997 Cost_model::page_read_cost() directly from the optimizer.
4998 That should be avoided, as it introduced assumption about all
4999 storage engines being disk-page based, and having a 'page' cost.
5000 Furthermore, this page cost was even compared against read_cost(),
5001 which was computed with an entirely different algorithm, and thus
5002 could not be compared.
5003
5004 The default implementation still call Cost_model::page_read_cost(),
5005 thus behaving just as before. However, handler implementation may
5006 override it to call handler::read_cost() instead(), which probably
5007 will be more correct. (If a page_read_cost should be included
5008 in the cost estimate, that should preferable be done inside
5009 each read_cost() implementation)
5010
5011 Longer term we should consider to remove all page_read_cost()
5012 usage from the optimizer itself, making this method obsolete.
5013
5014 @param index the index number
5015 @param reads the number of accesses being made
5016
5017 @returns the estimated cost
5018 */
5019 virtual double page_read_cost(uint index, double reads);
5020
5021 /**
5022 Provide an upper cost-limit of doing a specified number of
5023 seek-and-read key lookups. This need to be comparable and
5024 calculated with the same 'metric' as page_read_cost.
5025
5026 @param reads the number of rows read in the 'worst' case.
5027
5028 @returns the estimated cost
5029 */
5030 virtual double worst_seek_times(double reads);
5031
5032 /**