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