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