MySQL 8.0.33
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, 2023, 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
2893/** Whether the engine does not support triggers. */
2894#define HTON_NO_TRIGGER_SUPPORT (1 << 20)
2895
2896/** Whether the primary engine supports external data sources. This case refers
2897 to having tables with data in object store and the engine does not store any
2898 of those data, only metadata. Table contents can be accessed only after
2899 loading the table in the secondary storage engine. The flag is used for
2900 a primary engine only.
2901 */
2902#define HTON_SUPPORTS_EXTERNAL_SOURCE (1 << 21)
2903
2905 assert(hton->flags & HTON_IS_SECONDARY_ENGINE);
2906
2907 return (hton->flags & HTON_SECONDARY_ENGINE_SUPPORTS_DDL) != 0;
2908}
2909
2910inline bool ddl_is_atomic(const handlerton *hton) {
2911 return (hton->flags & HTON_SUPPORTS_ATOMIC_DDL) != 0;
2912}
2913
2914/* Bits for handlerton::foreign_keys_flags bitmap. */
2915
2916/**
2917 Engine supports both unique and non-unique parent keys for
2918 foreign keys which contain full foreign key as its prefix.
2919
2920 Storage engines which support foreign keys but do not have
2921 this flag set are assumed to support only parent keys which
2922 are primary/unique and contain exactly the same columns as
2923 the foreign key, possibly, in different order.
2924*/
2925
2927
2928/**
2929 Storage engine supports hash keys as supporting keys for foreign
2930 keys. Hash key should contain all foreign key columns and only
2931 them (although in any order).
2932
2933 Storage engines which support foreign keys but do not have this
2934 flag set are assumed to not allow hash keys as supporting keys.
2935*/
2936
2938
2939/**
2940 Storage engine supports non-hash keys which have common prefix
2941 with the foreign key as supporting keys for it. If there are
2942 several such keys, one which shares biggest prefix with FK is
2943 chosen.
2944
2945 Storage engines which support foreign keys but do not have this
2946 flag set are assumed to require that supporting key contains full
2947 foreign key as its prefix.
2948*/
2949
2951
2952/**
2953 Storage engine does not support using the same key for both parent
2954 and supporting key, but requires the two to be different.
2955*/
2956
2958 (1 << 3);
2959
2960/**
2961 Engine takes into account hidden part of key (coming from primary key)
2962 when determines if it can serve as parent key for a foreign key.
2963
2964 Implies HTON_FKS_WITH_PREFIX_PARENT_KEYS and is related to
2965 HTON_SUPPORTS_EXTENDED_KEYS.
2966*/
2967
2969
2970/**
2971 Maximum possible length of SE-specific suffixes for auto-generated
2972 foreign key names.
2973*/
2974static const size_t MAX_FK_NAME_SUFFIX_LENGTH = 16;
2975
2976/**
2977 Suffix for auto-generated foreign key names for tables in SE's which
2978 don't specify own suffix. I.e. for foreign keys on tables in such
2979 SE's generated names follow (table name)FK_NAME_DEFAULT_SUFFIX(FK number)
2980 pattern.
2981*/
2983
2990
2996
2997/* struct to hold information about the table that should be created */
3001 bool schema_read_only{false};
3003 const char *password{nullptr};
3004 const char *tablespace{nullptr};
3005 LEX_STRING comment{nullptr, 0};
3006
3007 /**
3008 Algorithm (and possible options) to be used for InnoDB's transparent
3009 page compression. If this attribute is set then it is hint to the
3010 storage engine to try and compress the data using the specified algorithm
3011 where possible. Note: this value is interpreted by the storage engine only.
3012 and ignored by the Server layer. */
3013
3015
3016 /**
3017 This attribute is used for InnoDB's transparent page encryption.
3018 If this attribute is set then it is hint to the storage engine to encrypt
3019 the data. Note: this value is interpreted by the storage engine only.
3020 and ignored by the Server layer. */
3021
3023
3024 /**
3025 * Secondary engine of the table.
3026 * Is nullptr if no secondary engine defined.
3027 */
3029
3030 const char *data_file_name{nullptr};
3031 const char *index_file_name{nullptr};
3032 const char *alias{nullptr};
3038 uint64_t used_fields{0};
3039 // Can only be 1,2,4,8 or 16, but use uint32_t since that how it is
3040 // represented in InnoDB
3041 std::uint32_t key_block_size{0};
3042 uint stats_sample_pages{0}; /* number of pages to sample during
3043 stats estimation, if used, otherwise 0. */
3047 /**
3048 Row type of the table definition.
3049
3050 Defaults to ROW_TYPE_DEFAULT for all non-ALTER statements.
3051 For ALTER TABLE defaults to ROW_TYPE_NOT_USED (means "keep the current").
3052
3053 Can be changed either explicitly by the parser.
3054 If nothing specified inherits the value of the original table (if present).
3055 */
3057 uint null_bits{0}; /* NULL bits at start of record */
3058 uint options{0}; /* OR of HA_CREATE_ options */
3060 ha_storage_media storage_media{HA_SM_DEFAULT}; /* DEFAULT, DISK or MEMORY */
3061
3062 /*
3063 A flag to indicate if this table should be marked as a hidden table in
3064 the data dictionary. One use case is to mark the temporary tables
3065 created by ALTER to be marked as hidden.
3066 */
3067 bool m_hidden{false};
3068
3069 /*
3070 A flag to indicate if this table should be created but not committed at
3071 the end of statement.
3072 */
3074
3077
3079
3081
3082 /**
3083 Fill HA_CREATE_INFO to be used by ALTER as well as upgrade code.
3084 This function separates code from mysql_prepare_alter_table() to be
3085 used by upgrade code as well to reduce code duplication.
3086 For ALTER code path, this lets new create options override the old
3087 ones.
3088
3089 @param[in] share TABLE_SHARE object
3090 @param[in] used_fields If a given create option is not flagged, old
3091 value be copied from the TABLE_SHARE.
3092 */
3093
3095 uint64_t used_fields);
3096};
3097
3098/**
3099 Structure describing changes to an index to be caused by ALTER TABLE.
3100*/
3101
3102struct KEY_PAIR {
3103 /**
3104 Pointer to KEY object describing old version of index in
3105 TABLE::key_info array for TABLE instance representing old
3106 version of table.
3107 */
3109 /**
3110 Pointer to KEY object describing new version of index in
3111 Alter_inplace_info::key_info_buffer array.
3112 */
3114};
3115
3116/**
3117 In-place alter handler context.
3118
3119 This is a superclass intended to be subclassed by individual handlers
3120 in order to store handler unique context between in-place alter API calls.
3121
3122 The handler is responsible for creating the object. This can be done
3123 as early as during check_if_supported_inplace_alter().
3124
3125 The SQL layer is responsible for destroying the object.
3126
3127 @see Alter_inplace_info
3128*/
3129
3131 public:
3133
3135 [[maybe_unused]]) {}
3136 virtual ~inplace_alter_handler_ctx() = default;
3137};
3138
3139/**
3140 Class describing changes to be done by ALTER TABLE.
3141 Instance of this class is passed to storage engine in order
3142 to determine if this ALTER TABLE can be done using in-place
3143 algorithm. It is also used for executing the ALTER TABLE
3144 using in-place algorithm.
3145*/
3146
3148 public:
3149 /**
3150 Bits to show in detail what operations the storage engine is
3151 to execute.
3152
3153 All these operations are supported as in-place operations by the
3154 SQL layer. This means that operations that by their nature must
3155 be performed by copying the table to a temporary table, will not
3156 have their own flags here (e.g. ALTER TABLE FORCE, ALTER TABLE
3157 ENGINE).
3158
3159 We generally try to specify handler flags only if there are real
3160 changes. But in cases when it is cumbersome to determine if some
3161 attribute has really changed we might choose to set flag
3162 pessimistically, for example, relying on parser output only.
3163 */
3165
3166 // Add non-unique, non-primary index
3167 static const HA_ALTER_FLAGS ADD_INDEX = 1ULL << 0;
3168
3169 // Drop non-unique, non-primary index
3170 static const HA_ALTER_FLAGS DROP_INDEX = 1ULL << 1;
3171
3172 // Add unique, non-primary index
3173 static const HA_ALTER_FLAGS ADD_UNIQUE_INDEX = 1ULL << 2;
3174
3175 // Drop unique, non-primary index
3176 static const HA_ALTER_FLAGS DROP_UNIQUE_INDEX = 1ULL << 3;
3177
3178 // Add primary index
3179 static const HA_ALTER_FLAGS ADD_PK_INDEX = 1ULL << 4;
3180
3181 // Drop primary index
3182 static const HA_ALTER_FLAGS DROP_PK_INDEX = 1ULL << 5;
3183
3184 // Add column
3185
3186 // Virtual generated column
3187 static const HA_ALTER_FLAGS ADD_VIRTUAL_COLUMN = 1ULL << 6;
3188 // Stored base (non-generated) column
3189 static const HA_ALTER_FLAGS ADD_STORED_BASE_COLUMN = 1ULL << 7;
3190 // Stored generated column
3192 // Add generic column (convenience constant).
3195
3196 // Drop column
3197 static const HA_ALTER_FLAGS DROP_VIRTUAL_COLUMN = 1ULL << 9;
3198 static const HA_ALTER_FLAGS DROP_STORED_COLUMN = 1ULL << 10;
3201
3202 // Rename column
3203 static const HA_ALTER_FLAGS ALTER_COLUMN_NAME = 1ULL << 11;
3204
3205 // Change column datatype
3207 static const HA_ALTER_FLAGS ALTER_STORED_COLUMN_TYPE = 1ULL << 13;
3208
3209 /**
3210 Change column datatype in such way that new type has compatible
3211 packed representation with old type, so it is theoretically
3212 possible to perform change by only updating data dictionary
3213 without changing table rows.
3214 */
3216
3217 /// A virtual column has changed its position
3219
3220 /// A stored column has changed its position (disregarding virtual columns)
3222
3223 // Change column from NOT NULL to NULL
3224 static const HA_ALTER_FLAGS ALTER_COLUMN_NULLABLE = 1ULL << 17;
3225
3226 // Change column from NULL to NOT NULL
3228
3229 // Set or remove default column value
3230 static const HA_ALTER_FLAGS ALTER_COLUMN_DEFAULT = 1ULL << 19;
3231
3232 // Change column generation expression
3233 static const HA_ALTER_FLAGS ALTER_VIRTUAL_GCOL_EXPR = 1ULL << 20;
3234 static const HA_ALTER_FLAGS ALTER_STORED_GCOL_EXPR = 1ULL << 21;
3235
3236 // Add foreign key
3237 static const HA_ALTER_FLAGS ADD_FOREIGN_KEY = 1ULL << 22;
3238
3239 // Drop foreign key
3240 static const HA_ALTER_FLAGS DROP_FOREIGN_KEY = 1ULL << 23;
3241
3242 // table_options changed, see HA_CREATE_INFO::used_fields for details.
3243 static const HA_ALTER_FLAGS CHANGE_CREATE_OPTION = 1ULL << 24;
3244
3245 // Table is renamed
3246 static const HA_ALTER_FLAGS ALTER_RENAME = 1ULL << 25;
3247
3248 // Change the storage type of column
3250
3251 // Change the column format of column
3253
3254 // Add partition
3255 static const HA_ALTER_FLAGS ADD_PARTITION = 1ULL << 28;
3256
3257 // Drop partition
3258 static const HA_ALTER_FLAGS DROP_PARTITION = 1ULL << 29;
3259
3260 // Changing partition options
3261 static const HA_ALTER_FLAGS ALTER_PARTITION = 1ULL << 30;
3262
3263 // Coalesce partition
3264 static const HA_ALTER_FLAGS COALESCE_PARTITION = 1ULL << 31;
3265
3266 // Reorganize partition ... into
3267 static const HA_ALTER_FLAGS REORGANIZE_PARTITION = 1ULL << 32;
3268
3269 // Reorganize partition
3270 static const HA_ALTER_FLAGS ALTER_TABLE_REORG = 1ULL << 33;
3271
3272 // Remove partitioning
3274
3275 // Partition operation with ALL keyword
3276 static const HA_ALTER_FLAGS ALTER_ALL_PARTITION = 1ULL << 35;
3277
3278 /**
3279 Rename index. Note that we set this flag only if there are no other
3280 changes to the index being renamed. Also for simplicity we don't
3281 detect renaming of indexes which is done by dropping index and then
3282 re-creating index with identical definition under different name.
3283 */
3284 static const HA_ALTER_FLAGS RENAME_INDEX = 1ULL << 36;
3285
3286 /**
3287 Recreate the table for ALTER TABLE FORCE, ALTER TABLE ENGINE
3288 and OPTIMIZE TABLE operations.
3289 */
3290 static const HA_ALTER_FLAGS RECREATE_TABLE = 1ULL << 37;
3291
3292 // Add spatial index
3293 static const HA_ALTER_FLAGS ADD_SPATIAL_INDEX = 1ULL << 38;
3294
3295 // Alter index comment
3296 static const HA_ALTER_FLAGS ALTER_INDEX_COMMENT = 1ULL << 39;
3297
3298 // New/changed virtual generated column require validation
3299 static const HA_ALTER_FLAGS VALIDATE_VIRTUAL_COLUMN = 1ULL << 40;
3300
3301 /**
3302 Change index option in a way which is likely not to require index
3303 recreation. For example, change COMMENT or KEY::is_algorithm_explicit
3304 flag (without change of index algorithm itself).
3305 */
3306 static const HA_ALTER_FLAGS CHANGE_INDEX_OPTION = 1LL << 41;
3307
3308 // Rebuild partition
3309 static const HA_ALTER_FLAGS ALTER_REBUILD_PARTITION = 1ULL << 42;
3310
3311 /**
3312 Change in index length such that it does not require index rebuild.
3313 For example, change in index length due to column expansion like
3314 varchar(X) changed to varchar(X + N).
3315 */
3317
3318 /**
3319 Change to one of columns on which virtual generated column depends,
3320 so its values require re-evaluation.
3321 */
3322 static const HA_ALTER_FLAGS VIRTUAL_GCOL_REEVAL = 1ULL << 44;
3323
3324 /**
3325 Change to one of columns on which stored generated column depends,
3326 so its values require re-evaluation.
3327 */
3328 static const HA_ALTER_FLAGS STORED_GCOL_REEVAL = 1ULL << 45;
3329
3330 // Add check constraint.
3331 static const HA_ALTER_FLAGS ADD_CHECK_CONSTRAINT = 1ULL << 46;
3332
3333 // Drop check constraint.
3334 static const HA_ALTER_FLAGS DROP_CHECK_CONSTRAINT = 1ULL << 47;
3335
3336 // Suspend check constraint.
3337 static const HA_ALTER_FLAGS SUSPEND_CHECK_CONSTRAINT = 1ULL << 48;
3338
3339 // Alter column visibility.
3340 static const HA_ALTER_FLAGS ALTER_COLUMN_VISIBILITY = 1ULL << 49;
3341
3342 /**
3343 Create options (like MAX_ROWS) for the new version of table.
3344
3345 @note The referenced instance of HA_CREATE_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 For example, this means that it has HA_OPTION_PACK_RECORD
3349 flag in HA_CREATE_INFO::table_options member correctly set.
3350 */
3352
3353 /**
3354 Alter options, fields and keys for the new version of table.
3355
3356 @note The referenced instance of Alter_info object was already
3357 used to create new .FRM file for table being altered. So it
3358 has been processed by mysql_prepare_create_table() already.
3359 In particular, this means that in Create_field objects for
3360 fields which were present in some form in the old version
3361 of table, Create_field::field member points to corresponding
3362 Field instance for old version of table.
3363 */
3365
3366 /**
3367 Indicates whether operation should fail if table is non-empty.
3368 Storage engines should not suggest/allow execution of such operations
3369 using INSTANT algorithm since check whether table is empty done from
3370 SQL-layer is not "instant". Also SEs might choose different algorithm for
3371 ALTER TABLE execution knowing that it will be allowed to proceed only if
3372 table is empty.
3373
3374 Unlike for Alter_table_ctx::error_if_not_empty, we use bool for this flag
3375 and not bitmap, since SEs are really interested in the fact that ALTER
3376 will fail if table is not empty and not in exact reason behind this fact,
3377 and because we want to avoid extra dependency between Alter_table_ctx and
3378 Alter_inplace_info.
3379 */
3381
3382 /**
3383 Array of KEYs for new version of table - including KEYs to be added.
3384
3385 @note Currently this array is produced as result of
3386 mysql_prepare_create_table() call.
3387 This means that it follows different convention for
3388 KEY_PART_INFO::fieldnr values than objects in TABLE::key_info
3389 array.
3390
3391 @todo This is mainly due to the fact that we need to keep compatibility
3392 with removed handler::add_index() call. We plan to switch to
3393 TABLE::key_info numbering later.
3394
3395 KEYs are sorted - see sort_keys().
3396 */
3398
3399 /** Size of key_info_buffer array. */
3401
3402 /** Size of index_drop_buffer array. */
3404
3405 /**
3406 Array of pointers to KEYs to be dropped belonging to the TABLE instance
3407 for the old version of the table.
3408 */
3410
3411 /** Size of index_add_buffer array. */
3413
3414 /**
3415 Array of indexes into key_info_buffer for KEYs to be added,
3416 sorted in increasing order.
3417 */
3419
3420 /** Size of index_rename_buffer array. */
3422
3423 /** Size of index_rename_buffer array. */
3425
3426 /**
3427 Array of KEY_PAIR objects describing indexes being renamed.
3428 For each index renamed it contains object with KEY_PAIR::old_key
3429 pointing to KEY object belonging to the TABLE instance for old
3430 version of table representing old version of index and with
3431 KEY_PAIR::new_key pointing to KEY object for new version of
3432 index in key_info_buffer member.
3433 */
3436
3437 /** Number of virtual columns to be added. */
3439
3440 /** number of virtual columns to be dropped. */
3442
3443 /**
3444 Context information to allow handlers to keep context between in-place
3445 alter API calls.
3446
3447 @see inplace_alter_handler_ctx for information about object lifecycle.
3448 */
3450
3451 /**
3452 If the table uses several handlers, like ha_partition uses one handler
3453 per partition, this contains a Null terminated array of ctx pointers
3454 that should all be committed together.
3455 Or NULL if only handler_ctx should be committed.
3456 Set to NULL if the low level handler::commit_inplace_alter_table uses it,
3457 to signal to the main handler that everything was committed as atomically.
3458
3459 @see inplace_alter_handler_ctx for information about object lifecycle.
3460 */
3462
3463 /**
3464 Flags describing in detail which operations the storage engine is to
3465 execute.
3466 */
3468
3469 /**
3470 Partition_info taking into account the partition changes to be performed.
3471 Contains all partitions which are present in the old version of the table
3472 with partitions to be dropped or changed marked as such + all partitions
3473 to be added in the new version of table marked as such.
3474 */
3476
3477 /** true for online operation (LOCK=NONE) */
3479
3480 /**
3481 Can be set by handler along with handler_ctx. The difference is that
3482 this flag can be used to store SE-specific in-place ALTER context in cases
3483 when constructing full-blown inplace_alter_handler_ctx descendant is
3484 inconvenient.
3485 */
3487
3488 /**
3489 Can be set by handler to describe why a given operation cannot be done
3490 in-place (HA_ALTER_INPLACE_NOT_SUPPORTED) or why it cannot be done
3491 online (HA_ALTER_INPLACE_NO_LOCK or HA_ALTER_INPLACE_NO_LOCK_AFTER_PREPARE)
3492 If set, it will be used with ER_ALTER_OPERATION_NOT_SUPPORTED_REASON if
3493 results from handler::check_if_supported_inplace_alter() doesn't match
3494 requirements set by user. If not set, the more generic
3495 ER_ALTER_OPERATION_NOT_SUPPORTED will be used.
3496
3497 Please set to a properly localized string, for example using
3498 my_get_err_msg(), so that the error message as a whole is localized.
3499 */
3501
3503 Alter_info *alter_info_arg, bool error_if_not_empty_arg,
3504 KEY *key_info_arg, uint key_count_arg,
3505 partition_info *modified_part_info_arg)
3506 : create_info(create_info_arg),
3507 alter_info(alter_info_arg),
3508 error_if_not_empty(error_if_not_empty_arg),
3509 key_info_buffer(key_info_arg),
3510 key_count(key_count_arg),
3513 index_add_count(0),
3522 handler_flags(0),
3523 modified_part_info(modified_part_info_arg),
3524 online(false),
3527
3529
3530 /**
3531 Used after check_if_supported_inplace_alter() to report
3532 error if the result does not match the LOCK/ALGORITHM
3533 requirements set by the user.
3534
3535 @param not_supported Part of statement that was not supported.
3536 @param try_instead Suggestion as to what the user should
3537 replace not_supported with.
3538 */
3539 void report_unsupported_error(const char *not_supported,
3540 const char *try_instead);
3541
3542 /** Add old and new version of key to array of indexes to be renamed. */
3543 void add_renamed_key(KEY *old_key, KEY *new_key) {
3545 key_pair->old_key = old_key;
3546 key_pair->new_key = new_key;
3547 DBUG_PRINT("info",
3548 ("index renamed: '%s' to '%s'", old_key->name, new_key->name));
3549 }
3550
3551 void add_altered_index_visibility(KEY *old_key, KEY *new_key) {
3552 KEY_PAIR *key_pair =
3554 key_pair->old_key = old_key;
3555 key_pair->new_key = new_key;
3556 DBUG_PRINT("info", ("index had visibility altered: %i to %i",
3557 old_key->is_visible, new_key->is_visible));
3558 }
3559
3560 /**
3561 Add old and new version of modified key to arrays of indexes to
3562 be dropped and added (correspondingly).
3563 */
3564 void add_modified_key(KEY *old_key, KEY *new_key) {
3567 DBUG_PRINT("info", ("index changed: '%s'", old_key->name));
3568 }
3569
3570 /** Drop key to array of indexes to be dropped. */
3571 void add_dropped_key(KEY *old_key) {
3573 DBUG_PRINT("info", ("index dropped: '%s'", old_key->name));
3574 }
3575
3576 /** Add key to array of indexes to be added. */
3577 void add_added_key(KEY *new_key) {
3579 DBUG_PRINT("info", ("index added: '%s'", new_key->name));
3580 }
3581};
3582
3584 uint flags{0}; /* isam layer flags (e.g. for myisamchk) */
3585 uint sql_flags{0}; /* sql layer flags - for something myisamchk cannot do */
3586 KEY_CACHE *key_cache; /* new key cache when changing key cache */
3587};
3588
3589/*
3590 This is a buffer area that the handler can use to store rows.
3591 'end_of_used_area' should be kept updated after calls to
3592 read-functions so that other parts of the code can use the
3593 remaining area (until next read calls is issued).
3594*/
3595
3597 uchar *buffer; /* Buffer one can start using */
3598 uchar *buffer_end; /* End of buffer */
3599 uchar *end_of_used_area; /* End of area that was used by handler */
3600};
3601
3602typedef void *range_seq_t;
3603
3605 /*
3606 Initialize the traversal of range sequence
3607
3608 SYNOPSIS
3609 init()
3610 init_params The seq_init_param parameter
3611 n_ranges The number of ranges obtained
3612 flags A combination of HA_MRR_SINGLE_POINT, HA_MRR_FIXED_KEY
3613
3614 RETURN
3615 An opaque value to be used as RANGE_SEQ_IF::next() parameter
3616 */
3617 range_seq_t (*init)(void *init_params, uint n_ranges, uint flags);
3618
3619 /*
3620 Get the next range in the range sequence
3621
3622 SYNOPSIS
3623 next()
3624 seq The value returned by RANGE_SEQ_IF::init()
3625 range OUT Information about the next range
3626
3627 RETURN
3628 0 - Ok, the range structure filled with info about the next range
3629 1 - No more ranges
3630 */
3632
3633 /*
3634 Check whether range_info orders to skip the next record
3635
3636 SYNOPSIS
3637 skip_record()
3638 seq The value returned by RANGE_SEQ_IF::init()
3639 range_info Information about the next range
3640 (Ignored if MRR_NO_ASSOCIATION is set)
3641 rowid Rowid of the record to be checked (ignored if set to 0)
3642
3643 RETURN
3644 1 - Record with this range_info and/or this rowid shall be filtered
3645 out from the stream of records returned by ha_multi_range_read_next()
3646 0 - The record shall be left in the stream
3647 */
3648 bool (*skip_record)(range_seq_t seq, char *range_info, uchar *rowid);
3649};
3650
3651/**
3652 Used to store optimizer cost estimates.
3653
3654 The class consists of PODs only: default operator=, copy constructor
3655 and destructor are used.
3656 */
3658 private:
3659 double io_cost; ///< cost of I/O operations
3660 double cpu_cost; ///< cost of CPU operations
3661 double import_cost; ///< cost of remote operations
3662 double mem_cost; ///< memory used (bytes)
3663
3664 public:
3666
3667 /// Returns sum of time-consuming costs, i.e., not counting memory cost
3668 double total_cost() const { return io_cost + cpu_cost + import_cost; }
3669 double get_io_cost() const { return io_cost; }
3670 double get_cpu_cost() const { return cpu_cost; }
3671 double get_import_cost() const { return import_cost; }
3672 double get_mem_cost() const { return mem_cost; }
3673
3674 /**
3675 Whether or not all costs in the object are zero
3676
3677 @return true if all costs are zero, false otherwise
3678 */
3679 bool is_zero() const {
3680 return !(io_cost || cpu_cost || import_cost || mem_cost);
3681 }
3682 /**
3683 Whether or not the total cost is the maximal double
3684
3685 @return true if total cost is the maximal double, false otherwise
3686 */
3687 bool is_max_cost() const { return io_cost == DBL_MAX; }
3688 /// Reset all costs to zero
3690 /// Set current cost to the maximal double
3692 reset();
3693 io_cost = DBL_MAX;
3694 }
3695
3696 /// Multiply io, cpu and import costs by parameter
3697 void multiply(double m) {
3698 assert(!is_max_cost());
3699
3700 io_cost *= m;
3701 cpu_cost *= m;
3702 import_cost *= m;
3703 /* Don't multiply mem_cost */
3704 }
3705
3707 assert(!is_max_cost() && !other.is_max_cost());
3708
3709 io_cost += other.io_cost;
3710 cpu_cost += other.cpu_cost;
3711 import_cost += other.import_cost;
3712 mem_cost += other.mem_cost;
3713
3714 return *this;
3715 }
3716
3718 Cost_estimate result = *this;
3719 result += other;
3720
3721 return result;
3722 }
3723
3726
3727 assert(!other.is_max_cost());
3728
3729 result.io_cost = io_cost - other.io_cost;
3730 result.cpu_cost = cpu_cost - other.cpu_cost;
3731 result.import_cost = import_cost - other.import_cost;
3732 result.mem_cost = mem_cost - other.mem_cost;
3733 return result;
3734 }
3735
3736 bool operator>(const Cost_estimate &other) const {
3737 return total_cost() > other.total_cost() ? true : false;
3738 }
3739
3740 bool operator<(const Cost_estimate &other) const {
3741 return other > *this ? true : false;
3742 }
3743
3744 /// Add to IO cost
3745 void add_io(double add_io_cost) {
3746 assert(!is_max_cost());
3747 io_cost += add_io_cost;
3748 }
3749
3750 /// Add to CPU cost
3751 void add_cpu(double add_cpu_cost) {
3752 assert(!is_max_cost());
3753 cpu_cost += add_cpu_cost;
3754 }
3755
3756 /// Add to import cost
3757 void add_import(double add_import_cost) {
3758 assert(!is_max_cost());
3759 import_cost += add_import_cost;
3760 }
3761
3762 /// Add to memory cost
3763 void add_mem(double add_mem_cost) {
3764 assert(!is_max_cost());
3765 mem_cost += add_mem_cost;
3766 }
3767};
3768
3769void get_sweep_read_cost(TABLE *table, ha_rows nrows, bool interrupted,
3770 Cost_estimate *cost);
3771
3772/*
3773 The below two are not used (and not handled) in this milestone of this WL
3774 entry because there seems to be no use for them at this stage of
3775 implementation.
3776*/
3777#define HA_MRR_SINGLE_POINT 1
3778#define HA_MRR_FIXED_KEY 2
3779
3780/*
3781 Indicates that RANGE_SEQ_IF::next(&range) doesn't need to fill in the
3782 'range' parameter.
3783*/
3784#define HA_MRR_NO_ASSOCIATION 4
3785
3786/*
3787 The MRR user will provide ranges in key order, and MRR implementation
3788 must return rows in key order.
3789 Passing this flag to multi_read_range_init() may cause the
3790 default MRR handler to be used even if HA_MRR_USE_DEFAULT_IMPL
3791 was not specified.
3792 (If the native MRR impl. can not provide SORTED result)
3793*/
3794#define HA_MRR_SORTED 8
3795
3796/* MRR implementation doesn't have to retrieve full records */
3797#define HA_MRR_INDEX_ONLY 16
3798
3799/*
3800 The passed memory buffer is of maximum possible size, the caller can't
3801 assume larger buffer.
3802*/
3803#define HA_MRR_LIMITS 32
3804
3805/*
3806 Flag set <=> default MRR implementation is used
3807 (The choice is made by **_info[_const]() function which may set this
3808 flag. SQL layer remembers the flag value and then passes it to
3809 multi_read_range_init().
3810*/
3811#define HA_MRR_USE_DEFAULT_IMPL 64
3812
3813/*
3814 Used only as parameter to multi_range_read_info():
3815 Flag set <=> the caller guarantees that the bounds of the scanned ranges
3816 will not have NULL values.
3817*/
3818#define HA_MRR_NO_NULL_ENDPOINTS 128
3819
3820/*
3821 Set by the MRR implementation to signal that it will natively
3822 produced sorted result if multi_range_read_init() is called with
3823 the HA_MRR_SORTED flag - Else multi_range_read_init(HA_MRR_SORTED)
3824 will revert to use the default MRR implementation.
3825*/
3826#define HA_MRR_SUPPORT_SORTED 256
3827
3829 public:
3830 ulonglong data_file_length; /* Length off data file */
3831 ulonglong max_data_file_length; /* Length off data file */
3834 ulonglong delete_length; /* Free bytes */
3836 /*
3837 The number of records in the table.
3838 0 - means the table has exactly 0 rows
3839 other - if (table_flags() & HA_STATS_RECORDS_IS_EXACT)
3840 the value is the exact number of records in the table
3841 else
3842 it is an estimate
3843 */
3845 ha_rows deleted; /* Deleted records */
3846 ulong mean_rec_length; /* physical reclength */
3847 /* TODO: create_time should be retrieved from the new DD. Remove this. */
3848 time_t create_time; /* When table was created */
3851 uint block_size; /* index block size */
3852
3853 /*
3854 number of buffer bytes that native mrr implementation needs,
3855 */
3857
3858 /**
3859 Estimate for how much of the table that is available in a memory
3860 buffer. Valid range is [0..1]. If it has the special value
3861 IN_MEMORY_ESTIMATE_UNKNOWN (defined in structs.h), it means that
3862 the storage engine has not supplied any value for it.
3863 */
3865
3867 : data_file_length(0),
3870 delete_length(0),
3872 records(0),
3873 deleted(0),
3874 mean_rec_length(0),
3875 create_time(0),
3876 check_time(0),
3877 update_time(0),
3878 block_size(0),
3880};
3881
3882/**
3883 Calculates length of key.
3884
3885 Given a key index and a map of key parts return length of buffer used by key
3886 parts.
3887
3888 @param table Table containing the key
3889 @param key Key index
3890 @param keypart_map which key parts that is used
3891
3892 @return Length of used key parts.
3893*/
3894uint calculate_key_len(TABLE *table, uint key, key_part_map keypart_map);
3895/*
3896 bitmap with first N+1 bits set
3897 (keypart_map for a key prefix of [0..N] keyparts)
3898*/
3899#define make_keypart_map(N) (((key_part_map)2 << (N)) - 1)
3900/*
3901 bitmap with first N bits set
3902 (keypart_map for a key prefix of [0..N-1] keyparts)
3903*/
3904#define make_prev_keypart_map(N) (((key_part_map)1 << (N)) - 1)
3905
3906/** Base class to be used by handlers different shares */
3908 public:
3909 Handler_share() = default;
3910 virtual ~Handler_share() = default;
3911};
3912
3913/**
3914 Wrapper for struct ft_hints.
3915*/
3916
3918 private:
3920
3921 public:
3922 explicit Ft_hints(uint ft_flags) {
3923 hints.flags = ft_flags;
3925 hints.op_value = 0.0;
3927 }
3928
3929 /**
3930 Set comparison operation type and and value for master MATCH function.
3931
3932 @param type comparison operation type
3933 @param value comparison operation value
3934 */
3935 void set_hint_op(enum ft_operation type, double value) {
3936 hints.op_type = type;
3937 hints.op_value = value;
3938 }
3939
3940 /**
3941 Set Ft_hints flag.
3942
3943 @param ft_flag Ft_hints flag
3944 */
3945 void set_hint_flag(uint ft_flag) { hints.flags |= ft_flag; }
3946
3947 /**
3948 Set Ft_hints limit.
3949
3950 @param ft_limit limit
3951 */
3952 void set_hint_limit(ha_rows ft_limit) { hints.limit = ft_limit; }
3953
3954 /**
3955 Get Ft_hints limit.
3956
3957 @return Ft_hints limit
3958 */
3959 ha_rows get_limit() const { return hints.limit; }
3960
3961 /**
3962 Get Ft_hints operation value.
3963
3964 @return operation value
3965 */
3966 double get_op_value() const { return hints.op_value; }
3967
3968 /**
3969 Get Ft_hints operation type.
3970
3971 @return operation type
3972 */
3973 enum ft_operation get_op_type() const { return hints.op_type; }
3974
3975 /**
3976 Get Ft_hints flags.
3977
3978 @return Ft_hints flags
3979 */
3980 uint get_flags() const { return hints.flags; }
3981
3982 /**
3983 Get ft_hints struct.
3984
3985 @return pointer to ft_hints struct
3986 */
3988 return &hints;
3989 }
3990};
3991
3992/**
3993 The handler class is the interface for dynamically loadable
3994 storage engines. Do not add ifdefs and take care when adding or
3995 changing virtual functions to avoid vtable confusion
3996
3997 Functions in this class accept and return table columns data. Two data
3998 representation formats are used:
3999 1. TableRecordFormat - Used to pass [partial] table records to/from
4000 storage engine
4001
4002 2. KeyTupleFormat - used to pass index search tuples (aka "keys") to
4003 storage engine. See opt_range.cc for description of this format.
4004
4005 TableRecordFormat
4006 =================
4007 [Warning: this description is work in progress and may be incomplete]
4008 The table record is stored in a fixed-size buffer:
4009
4010 record: null_bytes, column1_data, column2_data, ...
4011
4012 The offsets of the parts of the buffer are also fixed: every column has
4013 an offset to its column{i}_data, and if it is nullable it also has its own
4014 bit in null_bytes.
4015
4016 The record buffer only includes data about columns that are marked in the
4017 relevant column set (table->read_set and/or table->write_set, depending on
4018 the situation).
4019 <not-sure>It could be that it is required that null bits of non-present
4020 columns are set to 1</not-sure>
4021
4022 VARIOUS EXCEPTIONS AND SPECIAL CASES
4023
4024 If the table has no nullable columns, then null_bytes is still
4025 present, its length is one byte <not-sure> which must be set to 0xFF
4026 at all times. </not-sure>
4027
4028 If the table has columns of type BIT, then certain bits from those columns
4029 may be stored in null_bytes as well. Grep around for Field_bit for
4030 details.
4031
4032 For blob columns (see Field_blob), the record buffer stores length of the
4033 data, following by memory pointer to the blob data. The pointer is owned
4034 by the storage engine and is valid until the next operation.
4035
4036 If a blob column has NULL value, then its length and blob data pointer
4037 must be set to 0.
4038
4039
4040 Overview of main modules of the handler API
4041 ===========================================
4042 The overview below was copied from the storage/partition/ha_partition.h when
4043 support for non-native partitioning was removed.
4044
4045 -------------------------------------------------------------------------
4046 MODULE create/delete handler object
4047 -------------------------------------------------------------------------
4048 Object create/delete method. Normally called when a table object
4049 exists.
4050
4051 -------------------------------------------------------------------------
4052 MODULE meta data changes
4053 -------------------------------------------------------------------------
4054 Meta data routines to CREATE, DROP, RENAME table are often used at
4055 ALTER TABLE (update_create_info used from ALTER TABLE and SHOW ..).
4056
4057 Methods:
4058 delete_table()
4059 rename_table()
4060 create()
4061 update_create_info()
4062
4063 -------------------------------------------------------------------------
4064 MODULE open/close object
4065 -------------------------------------------------------------------------
4066 Open and close handler object to ensure all underlying files and
4067 objects allocated and deallocated for query handling is handled
4068 properly.
4069
4070 A handler object is opened as part of its initialisation and before
4071 being used for normal queries (not before meta-data changes always.
4072 If the object was opened it will also be closed before being deleted.
4073
4074 Methods:
4075 open()
4076 close()
4077
4078 -------------------------------------------------------------------------
4079 MODULE start/end statement
4080 -------------------------------------------------------------------------
4081 This module contains methods that are used to understand start/end of
4082 statements, transaction boundaries, and aid for proper concurrency
4083 control.
4084
4085 Methods:
4086 store_lock()
4087 external_lock()
4088 start_stmt()
4089 lock_count()
4090 unlock_row()
4091 was_semi_consistent_read()
4092 try_semi_consistent_read()
4093
4094 -------------------------------------------------------------------------
4095 MODULE change record
4096 -------------------------------------------------------------------------
4097 This part of the handler interface is used to change the records
4098 after INSERT, DELETE, UPDATE, REPLACE method calls but also other
4099 special meta-data operations as ALTER TABLE, LOAD DATA, TRUNCATE.
4100
4101 These methods are used for insert (write_row), update (update_row)
4102 and delete (delete_row). All methods to change data always work on
4103 one row at a time. update_row and delete_row also contains the old
4104 row.
4105 delete_all_rows will delete all rows in the table in one call as a
4106 special optimization for DELETE from table;
4107
4108 Bulk inserts are supported if all underlying handlers support it.
4109 start_bulk_insert and end_bulk_insert is called before and after a
4110 number of calls to write_row.
4111
4112 Methods:
4113 write_row()
4114 update_row()
4115 delete_row()
4116 delete_all_rows()
4117 start_bulk_insert()
4118 end_bulk_insert()
4119
4120 -------------------------------------------------------------------------
4121 MODULE full table scan
4122 -------------------------------------------------------------------------
4123 This module is used for the most basic access method for any table
4124 handler. This is to fetch all data through a full table scan. No
4125 indexes are needed to implement this part.
4126 It contains one method to start the scan (rnd_init) that can also be
4127 called multiple times (typical in a nested loop join). Then proceeding
4128 to the next record (rnd_next) and closing the scan (rnd_end).
4129 To remember a record for later access there is a method (position)
4130 and there is a method used to retrieve the record based on the stored
4131 position.
4132 The position can be a file position, a primary key, a ROWID dependent
4133 on the handler below.
4134
4135 All functions that retrieve records and are callable through the
4136 handler interface must indicate whether a record is present after the call
4137 or not. Record found is indicated by returning 0 and setting table status
4138 to "has row". Record not found is indicated by returning a non-zero value
4139 and setting table status to "no row".
4140 @see TABLE::set_found_row() and TABLE::set_no_row().
4141 By enforcing these rules in the handler interface, storage handler functions
4142 need not set any status in struct TABLE. These notes also apply to module
4143 index scan, documented below.
4144
4145 Methods:
4146
4147 rnd_init()
4148 rnd_end()
4149 rnd_next()
4150 rnd_pos()
4151 rnd_pos_by_record()
4152 position()
4153
4154 -------------------------------------------------------------------------
4155 MODULE index scan
4156 -------------------------------------------------------------------------
4157 This part of the handler interface is used to perform access through
4158 indexes. The interface is defined as a scan interface but the handler
4159 can also use key lookup if the index is a unique index or a primary
4160 key index.
4161 Index scans are mostly useful for SELECT queries but are an important
4162 part also of UPDATE, DELETE, REPLACE and CREATE TABLE table AS SELECT
4163 and so forth.
4164 Naturally an index is needed for an index scan and indexes can either
4165 be ordered, hash based. Some ordered indexes can return data in order
4166 but not necessarily all of them.
4167 There are many flags that define the behavior of indexes in the
4168 various handlers. These methods are found in the optimizer module.
4169
4170 index_read is called to start a scan of an index. The find_flag defines
4171 the semantics of the scan. These flags are defined in
4172 include/my_base.h
4173 index_read_idx is the same but also initializes index before calling doing
4174 the same thing as index_read. Thus it is similar to index_init followed
4175 by index_read. This is also how we implement it.
4176
4177 index_read/index_read_idx does also return the first row. Thus for
4178 key lookups, the index_read will be the only call to the handler in
4179 the index scan.
4180
4181 index_init initializes an index before using it and index_end does
4182 any end processing needed.
4183
4184 Methods:
4185 index_read_map()
4186 index_init()
4187 index_end()
4188 index_read_idx_map()
4189 index_next()
4190 index_prev()
4191 index_first()
4192 index_last()
4193 index_next_same()
4194 index_read_last_map()
4195 read_range_first()
4196 read_range_next()
4197
4198 -------------------------------------------------------------------------
4199 MODULE information calls
4200 -------------------------------------------------------------------------
4201 This calls are used to inform the handler of specifics of the ongoing
4202 scans and other actions. Most of these are used for optimisation
4203 purposes.
4204
4205 Methods:
4206 info()
4207 get_dynamic_partition_info
4208 extra()
4209 extra_opt()
4210 reset()
4211
4212 -------------------------------------------------------------------------
4213 MODULE optimizer support
4214 -------------------------------------------------------------------------
4215 NOTE:
4216 One important part of the public handler interface that is not depicted in
4217 the methods is the attribute records which is defined in the base class.
4218 This is looked upon directly and is set by calling info(HA_STATUS_INFO) ?
4219
4220 Methods:
4221 min_rows_for_estimate()
4222 get_biggest_used_partition()
4223 scan_time()
4224 read_time()
4225 records_in_range()
4226 estimate_rows_upper_bound()
4227 records()
4228
4229 -------------------------------------------------------------------------
4230 MODULE print messages
4231 -------------------------------------------------------------------------
4232 This module contains various methods that returns text messages for
4233 table types, index type and error messages.
4234
4235 Methods:
4236 table_type()
4237 get_row_type()
4238 print_error()
4239 get_error_message()
4240
4241 -------------------------------------------------------------------------
4242 MODULE handler characteristics
4243 -------------------------------------------------------------------------
4244 This module contains a number of methods defining limitations and
4245 characteristics of the handler (see also documentation regarding the
4246 individual flags).
4247
4248 Methods:
4249 table_flags()
4250 index_flags()
4251 min_of_the_max_uint()
4252 max_supported_record_length()
4253 max_supported_keys()
4254 max_supported_key_parts()
4255 max_supported_key_length()
4256 max_supported_key_part_length()
4257 low_byte_first()
4258 extra_rec_buf_length()
4259 min_record_length(uint options)
4260 primary_key_is_clustered()
4261 ha_key_alg get_default_index_algorithm()
4262 is_index_algorithm_supported()
4263
4264 -------------------------------------------------------------------------
4265 MODULE compare records
4266 -------------------------------------------------------------------------
4267 cmp_ref checks if two references are the same. For most handlers this is
4268 a simple memcmp of the reference. However some handlers use primary key
4269 as reference and this can be the same even if memcmp says they are
4270 different. This is due to character sets and end spaces and so forth.
4271
4272 Methods:
4273 cmp_ref()
4274
4275 -------------------------------------------------------------------------
4276 MODULE auto increment
4277 -------------------------------------------------------------------------
4278 This module is used to handle the support of auto increments.
4279
4280 This variable in the handler is used as part of the handler interface
4281 It is maintained by the parent handler object and should not be
4282 touched by child handler objects (see handler.cc for its use).
4283
4284 Methods:
4285 get_auto_increment()
4286 release_auto_increment()
4287
4288 -------------------------------------------------------------------------
4289 MODULE initialize handler for HANDLER call
4290 -------------------------------------------------------------------------
4291 This method is a special InnoDB method called before a HANDLER query.
4292
4293 Methods:
4294 init_table_handle_for_HANDLER()
4295
4296 -------------------------------------------------------------------------
4297 MODULE fulltext index
4298 -------------------------------------------------------------------------
4299 Fulltext index support.
4300
4301 Methods:
4302 ft_init_ext_with_hints()
4303 ft_init()
4304 ft_init_ext()
4305 ft_read()
4306
4307 -------------------------------------------------------------------------
4308 MODULE in-place ALTER TABLE
4309 -------------------------------------------------------------------------
4310 Methods for in-place ALTER TABLE support (implemented by InnoDB and NDB).
4311
4312 Methods:
4313 check_if_supported_inplace_alter()
4314 prepare_inplace_alter_table()
4315 inplace_alter_table()
4316 commit_inplace_alter_table()
4317 notify_table_changed()
4318
4319 -------------------------------------------------------------------------
4320 MODULE tablespace support
4321 -------------------------------------------------------------------------
4322 Methods:
4323 discard_or_import_tablespace()
4324
4325 -------------------------------------------------------------------------
4326 MODULE administrative DDL
4327 -------------------------------------------------------------------------
4328 Methods:
4329 optimize()
4330 analyze()
4331 check()
4332 repair()
4333 check_and_repair()
4334 auto_repair()
4335 is_crashed()
4336 check_for_upgrade()
4337 checksum()
4338 assign_to_keycache()
4339
4340 -------------------------------------------------------------------------
4341 MODULE enable/disable indexes
4342 -------------------------------------------------------------------------
4343 Enable/Disable Indexes are only supported by HEAP and MyISAM.
4344
4345 Methods:
4346 disable_indexes()
4347 enable_indexes()
4348 indexes_are_disabled()
4349
4350 -------------------------------------------------------------------------
4351 MODULE append_create_info
4352 -------------------------------------------------------------------------
4353 Only used by MyISAM MERGE tables.
4354
4355 Methods:
4356 append_create_info()
4357
4358 -------------------------------------------------------------------------
4359 MODULE partitioning specific handler API
4360 -------------------------------------------------------------------------
4361 Methods:
4362 get_partition_handler()
4363*/
4364
4365class handler {
4366 friend class Partition_handler;
4367
4368 public:
4370
4371 protected:
4372 TABLE_SHARE *table_share; /* The table definition */
4373 TABLE *table; /* The current open table */
4374 Table_flags cached_table_flags{0}; /* Set on init() and open() */
4375
4377
4378 public:
4379 handlerton *ht; /* storage engine of this handler */
4380 /** Pointer to current row */
4382 /** Pointer to duplicate row */
4384
4386
4387 /* MultiRangeRead-related members: */
4388 range_seq_t mrr_iter; /* Iterator to traverse the range sequence */
4389 RANGE_SEQ_IF mrr_funcs; /* Range sequence traversal functions */
4390 HANDLER_BUFFER *multi_range_buffer; /* MRR buffer info */
4391 uint ranges_in_seq; /* Total number of ranges in the traversed sequence */
4392 /* true <=> source MRR ranges and the output are ordered */
4394
4395 /* true <=> we're currently traversing a range in mrr_cur_range. */
4397 /* Current range (the one we're now returning rows from) */
4399
4400 /*
4401 The direction of the current range or index scan. This is used by
4402 the ICP implementation to determine if it has reached the end
4403 of the current range.
4404 */
4406
4407 private:
4408 Record_buffer *m_record_buffer = nullptr; ///< Buffer for multi-row reads.
4409 /*
4410 Storage space for the end range value. Should only be accessed using
4411 the end_range pointer. The content is invalid when end_range is NULL.
4412 */
4416
4417 /**
4418 Pointer to the handler of the table in the primary storage engine,
4419 if this handler represents a table in a secondary storage engine.
4420 */
4422
4423 protected:
4426 /*
4427 true <=> the engine guarantees that returned records are within the range
4428 being scanned.
4429 */
4431
4432 public:
4433 /**
4434 End value for a range scan. If this is NULL the range scan has no
4435 end value. Should also be NULL when there is no ongoing range scan.
4436 Used by the read_range() functions and also evaluated by pushed
4437 index conditions.
4438 */
4440 /**
4441 Flag which tells if #end_range contains a virtual generated column.
4442 The content is invalid when #end_range is @c nullptr.
4443 */
4445 uint errkey; /* Last dup key */
4448 /** Length of ref (1-8 or the clustered key length) */
4451 enum { NONE = 0, INDEX, RND, SAMPLING } inited;
4452 bool implicit_emptied; /* Can be !=0 only if HEAP */
4454
4456 uint pushed_idx_cond_keyno; /* The index which the above condition is for */
4457
4458 /**
4459 next_insert_id is the next value which should be inserted into the
4460 auto_increment column: in a inserting-multi-row statement (like INSERT
4461 SELECT), for the first row where the autoinc value is not specified by the
4462 statement, get_auto_increment() called and asked to generate a value,
4463 next_insert_id is set to the next value, then for all other rows
4464 next_insert_id is used (and increased each time) without calling
4465 get_auto_increment().
4466 */
4468 /**
4469 insert id for the current row (*autogenerated*; if not
4470 autogenerated, it's 0).
4471 At first successful insertion, this variable is stored into
4472 THD::first_successful_insert_id_in_cur_stmt.
4473 */
4475 /**
4476 Interval returned by get_auto_increment() and being consumed by the
4477 inserter.
4478 */
4480 /**
4481 Number of reserved auto-increment intervals. Serves as a heuristic
4482 when we have no estimation of how many records the statement will insert:
4483 the more intervals we have reserved, the bigger the next one. Reset in
4484 handler::ha_release_auto_increment().
4485 */
4487
4488 /**
4489 Instrumented table associated with this handler.
4490 */
4492
4495
4496 private:
4497 /** Internal state of the batch instrumentation. */
4499 /** Batch mode not used. */
4501 /** Batch mode used, before first table io. */
4503 /** Batch mode used, after first table io. */
4506 /**
4507 Batch mode state.
4508 @sa start_psi_batch_mode.
4509 @sa end_psi_batch_mode.
4510 */
4512 /**
4513 The number of rows in the batch.
4514 @sa start_psi_batch_mode.
4515 @sa end_psi_batch_mode.
4516 */
4518 /**
4519 The current event in a batch.
4520 @sa start_psi_batch_mode.
4521 @sa end_psi_batch_mode.
4522 */
4524 /**
4525 Storage for the event in a batch.
4526 @sa start_psi_batch_mode.
4527 @sa end_psi_batch_mode.
4528 */
4530
4531 public:
4532 void unbind_psi();
4533 void rebind_psi();
4534 /**
4535 Put the handler in 'batch' mode when collecting
4536 table io instrumented events.
4537 When operating in batch mode:
4538 - a single start event is generated in the performance schema.
4539 - all table io performed between @c start_psi_batch_mode
4540 and @c end_psi_batch_mode is not instrumented:
4541 the number of rows affected is counted instead in @c m_psi_numrows.
4542 - a single end event is generated in the performance schema
4543 when the batch mode ends with @c end_psi_batch_mode.
4544 */
4545 void start_psi_batch_mode();
4546 /** End a batch started with @c start_psi_batch_mode. */
4547 void end_psi_batch_mode();
4548 /**
4549 If a PSI batch was started, turn if off.
4550 @returns true if it was started.
4551 */
4553 bool rc = m_psi_batch_mode;
4554 if (rc) end_psi_batch_mode();
4555 return rc;
4556 }
4557
4558 private:
4559 /**
4560 The lock type set by when calling::ha_external_lock(). This is
4561 propagated down to the storage engine. The reason for also storing
4562 it here, is that when doing MRR we need to create/clone a second handler
4563 object. This cloned handler object needs to know about the lock_type used.
4564 */
4566 /**
4567 Pointer where to store/retrieve the Handler_share pointer.
4568 For non partitioned handlers this is &TABLE_SHARE::ha_share.
4569 */
4571
4572 /**
4573 Some non-virtual ha_* functions, responsible for reading rows,
4574 like ha_rnd_pos(), must ensure that virtual generated columns are
4575 calculated before they return. For that, they should set this
4576 member to true at their start, and check it before they return: if
4577 the member is still true, it means they should calculate; if it's
4578 false, it means the calculation has been done by some called
4579 lower-level function and does not need to be re-done (which is why
4580 we need this status flag: to avoid redundant calculations, for
4581 performance).
4582
4583 Note that when updating generated fields, the NULL row status in
4584 the underlying TABLE objects matter, so be sure to reset them if needed!
4585 */
4587
4588 /* Filter row ids to weed out duplicates when multi-valued index is used */
4590
4591 public:
4592 handler(handlerton *ht_arg, TABLE_SHARE *share_arg)
4593 : table_share(share_arg),
4594 table(nullptr),
4596 ht(ht_arg),
4597 ref(nullptr),
4603 ref_length(sizeof(my_off_t)),
4605 inited(NONE),
4606 implicit_emptied(false),
4610 next_insert_id(0),
4613 m_psi(nullptr),
4615 m_psi_numrows(0),
4617 m_lock_type(F_UNLCK),
4620 m_unique(nullptr) {
4621 DBUG_PRINT("info", ("handler created F_UNLCK %d F_RDLCK %d F_WRLCK %d",
4622 F_UNLCK, F_RDLCK, F_WRLCK));
4623 }
4624
4625 virtual ~handler(void) {
4626 assert(m_psi == nullptr);
4628 assert(m_psi_locker == nullptr);
4629 assert(m_lock_type == F_UNLCK);
4630 assert(inited == NONE);
4631 }
4632
4633 /**
4634 Return extra handler specific text for EXPLAIN.
4635 */
4636 virtual std::string explain_extra() const { return ""; }
4637
4638 /*
4639 @todo reorganize functions, make proper public/protected/private qualifiers
4640 */
4641 virtual handler *clone(const char *name, MEM_ROOT *mem_root);
4642 /** This is called after create to allow us to set up cached variables */
4644 /* ha_ methods: public wrappers for private virtual API */
4645
4646 /**
4647 Set a record buffer that the storage engine can use for multi-row reads.
4648 The buffer has to be provided prior to the first read from an index or a
4649 table.
4650
4651 @param buffer the buffer to use for multi-row reads
4652 */
4654
4655 /**
4656 Get the record buffer that was set with ha_set_record_buffer().
4657
4658 @return the buffer to use for multi-row reads, or nullptr if there is none
4659 */
4661
4662 /**
4663 Does this handler want to get a Record_buffer for multi-row reads
4664 via the ha_set_record_buffer() function? And if so, what is the
4665 maximum number of records to allocate space for in the buffer?
4666
4667 Storage engines that support using a Record_buffer should override
4668 handler::is_record_buffer_wanted().
4669
4670 @param[out] max_rows gets set to the maximum number of records to
4671 allocate space for in the buffer if the function
4672 returns true
4673
4674 @retval true if the handler would like a Record_buffer
4675 @retval false if the handler does not want a Record_buffer
4676 */
4677 bool ha_is_record_buffer_wanted(ha_rows *const max_rows) const {
4678 return is_record_buffer_wanted(max_rows);
4679 }
4680
4681 int ha_open(TABLE *table, const char *name, int mode, int test_if_locked,
4682 const dd::Table *table_def);
4683 int ha_close(void);
4684 int ha_index_init(uint idx, bool sorted);
4685 int ha_index_end();
4686 int ha_rnd_init(bool scan);
4687 int ha_rnd_end();
4688 int ha_rnd_next(uchar *buf);
4689 // See the comment on m_update_generated_read_fields.
4690 int ha_rnd_pos(uchar *buf, uchar *pos);
4691 int ha_index_read_map(uchar *buf, const uchar *key, key_part_map keypart_map,
4692 enum ha_rkey_function find_flag);
4694 key_part_map keypart_map);
4695 int ha_index_read_idx_map(uchar *buf, uint index, const uchar *key,
4696 key_part_map keypart_map,
4697 enum ha_rkey_function find_flag);
4698 int ha_index_next(uchar *buf);
4699 int ha_index_prev(uchar *buf);
4700 int ha_index_first(uchar *buf);
4701 int ha_index_last(uchar *buf);
4702 int ha_index_next_same(uchar *buf, const uchar *key, uint keylen);
4703 int ha_reset();
4704 /* this is necessary in many places, e.g. in HANDLER command */
4706 return inited == INDEX ? ha_index_end() : inited == RND ? ha_rnd_end() : 0;
4707 }
4708 /**
4709 The cached_table_flags is set at ha_open and ha_external_lock
4710 */
4712 /**
4713 These functions represent the public interface to *users* of the
4714 handler class, hence they are *not* virtual. For the inheritance
4715 interface, see the (private) functions write_row(), update_row(),
4716 and delete_row() below.
4717 */
4718 int ha_external_lock(THD *thd, int lock_type);
4719 int ha_write_row(uchar *buf);
4720 /**
4721 Update the current row.
4722
4723 @param old_data the old contents of the row
4724 @param new_data the new contents of the row
4725 @return error status (zero on success, HA_ERR_* error code on error)
4726 */
4727 int ha_update_row(const uchar *old_data, uchar *new_data);
4728 int ha_delete_row(const uchar *buf);
4730
4731 int ha_check_for_upgrade(HA_CHECK_OPT *check_opt);
4732 /** to be actually called to get 'check()' functionality*/
4733 int ha_check(THD *thd, HA_CHECK_OPT *check_opt);
4734 int ha_repair(THD *thd, HA_CHECK_OPT *check_opt);
4735 void ha_start_bulk_insert(ha_rows rows);
4736 int ha_end_bulk_insert();
4737 int ha_bulk_update_row(const uchar *old_data, uchar *new_data,
4738 uint *dup_key_found);
4739 int ha_delete_all_rows();
4741 int ha_optimize(THD *thd, HA_CHECK_OPT *check_opt);
4742 int ha_analyze(THD *thd, HA_CHECK_OPT *check_opt);
4743 bool ha_check_and_repair(THD *thd);
4747 int ha_rename_table(const char *from, const char *to,
4748 const dd::Table *from_table_def, dd::Table *to_table_def);
4749 int ha_delete_table(const char *name, const dd::Table *table_def);
4750 void ha_drop_table(const char *name);
4751
4752 int ha_create(const char *name, TABLE *form, HA_CREATE_INFO *info,
4754
4755 int ha_load_table(const TABLE &table);
4756
4757 int ha_unload_table(const char *db_name, const char *table_name,
4758 bool error_if_not_loaded);
4759
4760 /**
4761 Initializes a parallel scan. It creates a parallel_scan_ctx that has to
4762 be used across all parallel_scan methods. Also, gets the number of
4763 threads that would be spawned for parallel scan.
4764 @param[out] scan_ctx The parallel scan context.
4765 @param[out] num_threads Number of threads used for the scan.
4766 @param[in] use_reserved_threads true if reserved threads are to be used
4767 if we exhaust the max cap of number of
4768 parallel read threads that can be
4769 spawned at a time
4770 @return error code
4771 @retval 0 on success
4772 */
4773 virtual int parallel_scan_init(void *&scan_ctx [[maybe_unused]],
4774 size_t *num_threads [[maybe_unused]],
4775 bool use_reserved_threads [[maybe_unused]]) {
4776 return 0;
4777 }
4778
4779 /**
4780 This callback is called by each parallel load thread at the beginning of
4781 the parallel load for the adapter scan.
4782 @param cookie The cookie for this thread
4783 @param ncols Number of columns in each row
4784 @param row_len The size of a row in bytes
4785 @param col_offsets An array of size ncols, where each element represents
4786 the offset of a column in the row data. The memory of
4787 this array belongs to the caller and will be free-ed
4788 after the pload_end_cbk call.
4789 @param null_byte_offsets An array of size ncols, where each element
4790 represents the offset of a column in the row data. The
4791 memory of this array belongs to the caller and will be
4792 free-ed after the pload_end_cbk call.
4793 @param null_bitmasks An array of size ncols, where each element
4794 represents the bitmask required to get the null bit. The
4795 memory of this array belongs to the caller and will be
4796 free-ed after the pload_end_cbk call.
4797 */
4798 using Load_init_cbk = std::function<bool(
4799 void *cookie, ulong ncols, ulong row_len, const ulong *col_offsets,
4800 const ulong *null_byte_offsets, const ulong *null_bitmasks)>;
4801
4802 /**
4803 This callback is called by each parallel load thread when processing
4804 of rows is required for the adapter scan.
4805 @param[in] cookie The cookie for this thread
4806 @param[in] nrows The nrows that are available
4807 @param[in] rowdata The mysql-in-memory row data buffer. This is a
4808 memory buffer for nrows records. The length of each record is fixed and
4809 communicated via Load_init_cbk
4810 @param[in] partition_id Partition id if it's a partitioned table, else
4811 std::numeric_limits<uint64_t>::max()
4812 @returns true if there is an error, false otherwise.
4813 */
4814 using Load_cbk = std::function<bool(void *cookie, uint nrows, void *rowdata,
4815 uint64_t partition_id)>;
4816
4817 /**
4818 This callback is called by each parallel load thread when processing
4819 of rows has ended for the adapter scan.
4820 @param[in] cookie The cookie for this thread
4821 */
4822 using Load_end_cbk = std::function<void(void *cookie)>;
4823
4824 /**
4825 Run the parallel read of data.
4826 @param[in] scan_ctx Scan context of the parallel read.
4827 @param[in,out] thread_ctxs Caller thread contexts.
4828 @param[in] init_fn Callback called by each parallel load
4829 thread at the beginning of the parallel load.
4830 @param[in] load_fn Callback called by each parallel load
4831 thread when processing of rows is required.
4832 @param[in] end_fn Callback called by each parallel load
4833 thread when processing of rows has ended.
4834 @return error code
4835 @retval 0 on success
4836 */
4837 virtual int parallel_scan(void *scan_ctx [[maybe_unused]],
4838 void **thread_ctxs [[maybe_unused]],
4839 Load_init_cbk init_fn [[maybe_unused]],
4840 Load_cbk load_fn [[maybe_unused]],
4841 Load_end_cbk end_fn [[maybe_unused]]) {
4842 return 0;
4843 }
4844
4845 /**
4846 End of the parallel scan.
4847 @param[in] scan_ctx A scan context created by parallel_scan_init.
4848 */
4849 virtual void parallel_scan_end(void *scan_ctx [[maybe_unused]]) { return; }
4850
4851 /**
4852 Submit a dd::Table object representing a core DD table having
4853 hardcoded data to be filled in by the DDSE. This function can be
4854 used for retrieving the hard coded SE private data for the
4855 mysql.dd_properties table, before creating or opening it, or for
4856 retrieving the hard coded SE private data for a core table,
4857 before creating or opening them.
4858
4859 @param dd_table [in,out] A dd::Table object representing
4860 a core DD table.
4861 @param reset Reset counters.
4862
4863 @retval true An error occurred.
4864 @retval false Success - no errors.
4865 */
4866
4867 bool ha_get_se_private_data(dd::Table *dd_table, bool reset);
4868
4871 virtual void print_error(int error, myf errflag);
4872 virtual bool get_error_message(int error, String *buf);
4873 uint get_dup_key(int error);
4874 /**
4875 Retrieves the names of the table and the key for which there was a
4876 duplicate entry in the case of HA_ERR_FOREIGN_DUPLICATE_KEY.
4877
4878 If any of the table or key name is not available this method will return
4879 false and will not change any of child_table_name or child_key_name.
4880
4881 @param [out] child_table_name Table name
4882 @param [in] child_table_name_len Table name buffer size
4883 @param [out] child_key_name Key name
4884 @param [in] child_key_name_len Key name buffer size
4885
4886 @retval true table and key names were available
4887 and were written into the corresponding
4888 out parameters.
4889 @retval false table and key names were not available,
4890 the out parameters were not touched.
4891 */
4892 virtual bool get_foreign_dup_key(char *child_table_name,
4893 uint child_table_name_len,
4894 char *child_key_name,
4895 uint child_key_name_len);
4896 /**
4897 Change the internal TABLE_SHARE pointer.
4898
4899 @param table_arg TABLE object
4900 @param share New share to use
4901
4902 @note Is used in error handling in ha_delete_table.
4903 */
4904
4905 virtual void change_table_ptr(TABLE *table_arg, TABLE_SHARE *share) {
4906 table = table_arg;
4907 table_share = share;
4908 }
4909 const TABLE_SHARE *get_table_share() const { return table_share; }
4910
4911 /* Estimates calculation */
4912
4913 /**
4914 @deprecated This function is deprecated and will be removed in a future
4915 version. Use table_scan_cost() instead.
4916 */
4917
4918 virtual double scan_time() {
4919 return ulonglong2double(stats.data_file_length) / IO_SIZE + 2;
4920 }
4921
4922 /**
4923 The cost of reading a set of ranges from the table using an index
4924 to access it.
4925
4926 @deprecated This function is deprecated and will be removed in a future
4927 version. Use read_cost() instead.
4928
4929 @param index The index number.
4930 @param ranges The number of ranges to be read.
4931 @param rows Total number of rows to be read.
4932
4933 This method can be used to calculate the total cost of scanning a table
4934 using an index by calling it using read_time(index, 1, table_size).
4935 */
4936
4937 virtual double read_time(uint index [[maybe_unused]], uint ranges,
4938 ha_rows rows) {
4939 return rows2double(ranges + rows);
4940 }
4941
4942 /**
4943 @deprecated This function is deprecated and will be removed in a future
4944 version. Use index_scan_cost() instead.
4945 */
4946
4947 virtual double index_only_read_time(uint keynr, double records);
4948
4949 /**
4950 Cost estimate for doing a complete table scan.
4951
4952 @note For this version it is recommended that storage engines continue
4953 to override scan_time() instead of this function.
4954
4955 @returns the estimated cost
4956 */
4957
4959
4960 /**
4961 Cost estimate for reading a number of ranges from an index.
4962
4963 The cost estimate will only include the cost of reading data that
4964 is contained in the index. If the records need to be read, use
4965 read_cost() instead.
4966
4967 @note The ranges parameter is currently ignored and is not taken
4968 into account in the cost estimate.
4969
4970 @note For this version it is recommended that storage engines continue
4971 to override index_only_read_time() instead of this function.
4972
4973 @param index the index number
4974 @param ranges the number of ranges to be read
4975 @param rows total number of rows to be read
4976
4977 @returns the estimated cost
4978 */
4979
4980 virtual Cost_estimate index_scan_cost(uint index, double ranges, double rows);
4981
4982 /**
4983 Cost estimate for reading a set of ranges from the table using an index
4984 to access it.
4985
4986 @note For this version it is recommended that storage engines continue
4987 to override read_time() instead of this function.
4988
4989 @param index the index number
4990 @param ranges the number of ranges to be read
4991 @param rows total number of rows to be read
4992
4993 @returns the estimated cost
4994 */
4995
4996 virtual Cost_estimate read_cost(uint index, double ranges, double rows);
4997
4998 /**
4999 Cost estimate for doing a number of non-sequentially accesses
5000 against the storage engine. Such accesses can be either number
5001 of rows to read, or number of disk pages to access.
5002 Each handler implementation is free to interpret that as best
5003 suited, depending on what is the dominating cost for that
5004 storage engine.
5005
5006 This method is mainly provided as a temporary workaround for
5007 bug#33317872, where we fix problems caused by calling
5008 Cost_model::page_read_cost() directly from the optimizer.
5009 That should be avoided, as it introduced assumption about all
5010 storage engines being disk-page based, and having a 'page' cost.
5011 Furthermore, this page cost was even compared against read_cost(),
5012 which was computed with an entirely different algorithm, and thus
5013 could not be compared.
5014
5015 The default implementation still call Cost_model::page_read_cost(),
5016 thus behaving just as before. However, handler implementation may
5017 override it to call handler::read_cost() instead(), which probably
5018 will be more correct. (If a page_read_cost should be included
5019 in the cost estimate, that should preferable be done inside
5020 each read_cost() implementation)
5021
5022 Longer term we should consider to remove all page_read_cost()
5023 usage from the optimizer itself, making this method obsolete.
5024
5025 @param index the index number
5026 @param reads the number of accesses being made
5027
5028 @returns the estimated cost
5029 */
5030 virtual double page_read_cost(uint index, double reads);
5031