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