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