MySQL 8.2.0
Source Code Documentation
dictionary.h
Go to the documentation of this file.
1/* Copyright (c) 2014, 2023, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef DD__DICTIONARY_INCLUDED
24#define DD__DICTIONARY_INCLUDED
25
26#include "sql/dd/string_type.h" // dd::String_type
28
29class THD;
30class MDL_ticket;
31class Plugin_table;
32// class Tablespace;
33
34namespace dd {
35
36///////////////////////////////////////////////////////////////////////////
37
38class Collation;
39class Object_table;
40class Schema;
41class Tablespace;
42
43namespace cache {
44class Dictionary_client;
45}
46
47///////////////////////////////////////////////////////////////////////////
48
49/// Main interface class enabling users to operate on data dictionary.
51 public:
52 /**
53 Get dictionary object for a given dictionary table name.
54 If the given schema_name and table_name is not a dictionary
55 table name, then the function returns NULL.
56
57 @returns Pointer to dictionary object for the given
58 dictionary table name, else NULL.
59 */
60 virtual const Object_table *get_dd_table(
61 const String_type &schema_name, const String_type &table_name) const = 0;
62
63 public:
64 /////////////////////////////////////////////////////////////////////////
65 // Auxiliary operations.
66 /////////////////////////////////////////////////////////////////////////
67
68 /**
69 Check if the given schema name is 'mysql', which where
70 the DD tables are stored.
71
72 @param schema_name Schema name to check.
73
74 @returns true - If schema_name is 'mysql'
75 @returns false - If schema_name is not 'mysql'
76 */
77 virtual bool is_dd_schema_name(const String_type &schema_name) const = 0;
78
79 /**
80 Check if given table name is a dictionary table name.
81
82 @param schema_name Schema name to check.
83 @param table_name Table name to check.
84
85 @returns true - If given table name is a dictionary table.
86 @returns false - If table name is not a dictionary table.
87 */
88 virtual bool is_dd_table_name(const String_type &schema_name,
89 const String_type &table_name) const = 0;
90
91 /**
92 Check if given table name is a system table name.
93
94 @param schema_name Schema name to check.
95 @param table_name Table name to check.
96
97 @returns true - If given table name is a system table.
98 @returns false - If table name is not a system table.
99 */
100 virtual bool is_system_table_name(const String_type &schema_name,
101 const String_type &table_name) const = 0;
102
103 /**
104 Get the error code representing the type name string for a dictionary
105 or system table.
106
107 Necessary to support localization of error messages.
108
109 @param schema_name Schema name to check.
110 @param table_name Table name to check.
111
112 @returns The error code representing the type name associated with the
113 table, for being used in error messages.
114 */
115 virtual int table_type_error_code(const String_type &schema_name,
116 const String_type &table_name) const = 0;
117
118 /**
119 Check if given table name can be accessed by the given thread type.
120
121 @param is_dd_internal_thread 'true' if this is a DD internal
122 thread.
123 @param is_ddl_statement 'true' if this is a DDL statement.
124 @param schema_name Schema name to check.
125 @param schema_length Length of schema name to check.
126 @param table_name Table name to check.
127
128 @returns true - If given table name is accessible by the thread type.
129 @returns false - If table name is not accessible.
130 */
131 virtual bool is_dd_table_access_allowed(bool is_dd_internal_thread,
132 bool is_ddl_statement,
133 const char *schema_name,
134 size_t schema_length,
135 const char *table_name) const = 0;
136
137 /**
138 Check if given table name is a system view name.
139
140 @param schema_name Schema name to check.
141 @param table_name Table name to check.
142 @param[out] hidden Pointer to boolean flag indicating
143 if the object is hidden.
144
145 @returns true - If given table name is a system view.
146 @returns false - If table name is not a system view.
147 */
148 virtual bool is_system_view_name(const char *schema_name,
149 const char *table_name,
150 bool *hidden) const = 0;
151
152 /**
153 Check if given table name is a system view name.
154
155 @param schema_name Schema name to check.
156 @param table_name Table name to check.
157
158 @returns true - If given table name is a system view.
159 @returns false - If table name is not a system view.
160 */
161 virtual bool is_system_view_name(const char *schema_name,
162 const char *table_name) const = 0;
163
164 public:
165 // Destructor to cleanup data dictionary instance upon server shutdown.
166 virtual ~Dictionary() = default;
167};
168
169///////////////////////////////////////////////////////////////////////////
170
171//
172// MDL wrapper functions
173//
174
175/**
176 @brief
177 Acquire shared metadata lock on the given table name with
178 explicit duration.
179
180 @param thd - THD to which lock belongs to.
181 @param schema_name - Schema name
182 @param table_name - Table name
183 @param no_wait - Use try_acquire_lock() if no_wait is true.
184 else use acquire_lock() with
185 thd->variables.lock_wait_timeout timeout value.
186 @param out_mdl_ticket - This is a OUT parameter, a pointer to MDL_ticket
187 upon successful lock attempt.
188
189*/
190[[nodiscard]] bool acquire_shared_table_mdl(THD *thd, const char *schema_name,
191 const char *table_name,
192 bool no_wait,
193 MDL_ticket **out_mdl_ticket);
194
195/**
196 Predicate to check if we have a shared meta data lock on the
197 submitted schema qualified table name.
198
199 @param thd Thread context.
200 @param schema_name Schema name.
201 @param table_name Table name.
202
203 @retval true The thread context has a lock.
204 @retval false The thread context does not have a lock.
205*/
206
207bool has_shared_table_mdl(THD *thd, const char *schema_name,
208 const char *table_name);
209
210/**
211 Predicate to check if we have an exclusive meta data lock on the
212 submitted schema qualified table name.
213
214 @param thd Thread context.
215 @param schema_name Schema name.
216 @param table_name Table name.
217
218 @retval true The thread context has a lock.
219 @retval false The thread context does not have a lock.
220*/
221
222bool has_exclusive_table_mdl(THD *thd, const char *schema_name,
223 const char *table_name);
224
225/**
226 Acquire an exclusive metadata lock on the given tablespace name with
227 transaction duration.
228
229 @param thd THD to which lock belongs.
230 @param tablespace_name Tablespace name
231 @param no_wait Use try_acquire_lock() if no_wait is true,
232 else use acquire_lock() with
233 thd->variables.lock_wait_timeout timeout value.
234 @param ticket ticket for request (optional out parameter)
235 @param for_trx true if MDL duration is MDL_TRANSACTION
236 false if MDL duration is MDL_EXPLICIT
237
238 @retval true Failure, e.g. a lock wait timeout.
239 @retval false Successful lock acquisition.
240*/
241
242[[nodiscard]] bool acquire_exclusive_tablespace_mdl(
243 THD *thd, const char *tablespace_name, bool no_wait,
244 MDL_ticket **ticket = nullptr, bool for_trx = true);
245
246/**
247 Acquire a shared metadata lock on the given tablespace name with
248 transaction duration.
249
250 @param thd THD to which lock belongs.
251 @param tablespace_name Tablespace name
252 @param no_wait Use try_acquire_lock() if no_wait is true,
253 else use acquire_lock() with
254 thd->variables.lock_wait_timeout timeout value.
255 @param ticket ticket for request (optional out parameter)
256 @param for_trx true if MDL duration is MDL_TRANSACTION
257 false if MDL duration is MDL_EXPLICIT
258
259 @retval true Failure, e.g. a lock wait timeout.
260 @retval false Successful lock acquisition.
261*/
262[[nodiscard]] bool acquire_shared_tablespace_mdl(THD *thd,
263 const char *tablespace_name,
264 bool no_wait,
265 MDL_ticket **ticket = nullptr,
266 bool for_trx = true);
267
268/**
269 Predicate to check if we have a shared meta data lock on the
270 submitted tablespace name.
271
272 @param thd Thread context.
273 @param tablespace_name Tablespace name.
274
275 @retval true The thread context has a lock.
276 @retval false The thread context does not have a lock.
277*/
278
279bool has_shared_tablespace_mdl(THD *thd, const char *tablespace_name);
280
281/**
282 Predicate to check if we have an exclusive meta data lock on the
283 submitted tablespace name.
284
285 @param thd Thread context.
286 @param tablespace_name Tablespace name.
287
288 @retval true The thread context has a lock.
289 @retval false The thread context does not have a lock.
290*/
291
292bool has_exclusive_tablespace_mdl(THD *thd, const char *tablespace_name);
293
294/**
295 Acquire exclusive metadata lock on the given table name with
296 TRANSACTIONAL duration.
297
298 @param[in] thd THD to which lock belongs to.
299 @param[in] schema_name Schema name
300 @param[in] table_name Table name
301 @param[in] no_wait Use try_acquire_lock() if no_wait is true.
302 else use acquire_lock() with
303 thd->variables.lock_wait_timeout timeout value.
304 @param[out] out_mdl_ticket A pointer to MDL_ticket upon successful lock
305 attempt.
306*/
307
308[[nodiscard]] bool acquire_exclusive_table_mdl(THD *thd,
309 const char *schema_name,
310 const char *table_name,
311 bool no_wait,
312 MDL_ticket **out_mdl_ticket);
313
314/**
315 Acquire exclusive metadata lock on the given table name with
316 TRANSACTIONAL duration.
317
318 @param[in] thd THD to which lock belongs to.
319 @param[in] schema_name Schema name
320 @param[in] table_name Table name
321 @param[in] lock_wait_timeout Time to wait.
322 @param[out] out_mdl_ticket A pointer to MDL_ticket upon successful lock
323 attempt.
324*/
325
326[[nodiscard]] bool acquire_exclusive_table_mdl(
327 THD *thd, const char *schema_name, const char *table_name,
328 unsigned long int lock_wait_timeout, MDL_ticket **out_mdl_ticket);
329
330/**
331 Acquire exclusive metadata lock on the given schema name with
332 explicit duration.
333
334 @param[in] thd THD to which lock belongs to.
335 @param[in] schema_name Schema name
336 @param[in] no_wait Use try_acquire_lock() if no_wait is true.
337 else use acquire_lock() with
338 thd->variables.lock_wait_timeout timeout value.
339 @param[out] out_mdl_ticket A pointer to MDL_ticket upon successful lock
340 attempt.
341*/
342
343[[nodiscard]] bool acquire_exclusive_schema_mdl(THD *thd,
344 const char *schema_name,
345 bool no_wait,
346 MDL_ticket **out_mdl_ticket);
347
348/**
349 @brief
350 Release MDL_EXPLICIT lock held by a ticket
351
352 @param thd - THD to which lock belongs to.
353 @param mdl_ticket - Lock ticket.
354
355*/
356void release_mdl(THD *thd, MDL_ticket *mdl_ticket);
357
358/** Get Dictionary_client from THD object (the latter is opaque * in SEs). */
360
361/**
362 Create plugin native table. The API would only write metadata to DD
363 and skip calling handler::create().
364
365 @param[in] thd THD to which lock belongs to.
366 @param[in] pt Plugin_table* contain metadata of table to
367 be created.
368
369 @returns false on success, otherwise true.
370*/
371
372bool create_native_table(THD *thd, const Plugin_table *pt);
373
374/**
375 Remove plugin native table from DD. The API would only update
376 metadata to DD and skip calling handler::drop().
377
378 @param[in] thd THD to which lock belongs to.
379 @param[in] schema_name schema name which the table belongs to.
380 @param[in] table_name table name to be dropped.
381
382 @returns false on success, otherwise true.
383*/
384
385bool drop_native_table(THD *thd, const char *schema_name,
386 const char *table_name);
387
388/**
389 Reset the tables and tablespace partitions in the DD cache,
390 and invalidate the entries in the DDSE cache.
391
392 @note This is a temporary workaround to support proper recovery
393 after ha_recover().
394
395 @returns false on success, otherwise true.
396*/
398
399/**
400 Update a tablespace change, commit and release transactional MDL.
401
402 @param[in,out] thd Current thread context.
403 @param[in,out] space Tablespace to update and commit.
404 @param[in] error true for failure: Do rollback.
405 false for success: Do commit.
406 @param[in] release_mdl_on_commit_only release MDLs only on commit
407
408 @retval true If error is true, or if failure in update or in commit.
409 @retval false Otherwise.
410*/
411
413 THD *thd, dd::Tablespace *space, bool error,
414 bool release_mdl_on_commit_only = false);
415
416/**
417 Get the Object_table instance storing the given entity object type.
418
419 We can return this as a reference since all relevant types for which
420 this template is used will indeed have a corresponding object table.
421
422 @tparam Entity_object_type Type for which to get the object table.
423
424 @returns reference to Object_table instance.
425*/
426template <typename Entity_object_type>
428
429/**
430 Implicit tablespaces are renamed inside SE. But it is necessary to inform the
431 server layer about the rename, specifically which MDLs have been taken, so
432 that it can perform the necessary adjustment of MDLs when running in LOCK
433 TABLES mode.
434
435 @param thd thread context
436 @param src ticket for old name
437 @param dst ticket for new name
438*/
440
441/**
442 Execute an ALTER TABLESPACE ... ENCRYPTION statement.
443
444 During recovery of a storage engine, an ALTER TABLESPACE ... ENCRYPTION
445 statement may be resumed. This is initiated from the SE, which will first
446 set the state as appropriate in the SE, then invoke this method to start
447 executing the statement. When the SE is involved during execution of the
448 statement, the internal state in the SE will indicate that this is a
449 statement that has been initiated and partially executed already.
450
451 @param thd Thread context.
452 @param tablespace_name Name of tablespace to encrypt/decrypt.
453 @param encryption True to turn on encryption, false to turn off.
454
455 @retval false if no errors, otherwise true.
456*/
457bool alter_tablespace_encryption(THD *thd, const char *tablespace_name,
458 bool encryption);
459
460} // namespace dd
461
462#endif // DD__DICTIONARY_INCLUDED
A granted metadata lock.
Definition: mdl.h:984
Class to hold information regarding a table to be created on behalf of a plugin.
Definition: plugin_table.h:39
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:35
Data structure that contains the information about shared tablespaces.
Definition: fsp0space.h:46
Main interface class enabling users to operate on data dictionary.
Definition: dictionary.h:50
virtual bool is_dd_table_name(const String_type &schema_name, const String_type &table_name) const =0
Check if given table name is a dictionary table name.
virtual const Object_table * get_dd_table(const String_type &schema_name, const String_type &table_name) const =0
Get dictionary object for a given dictionary table name.
virtual bool is_system_view_name(const char *schema_name, const char *table_name) const =0
Check if given table name is a system view name.
virtual bool is_dd_schema_name(const String_type &schema_name) const =0
Check if the given schema name is 'mysql', which where the DD tables are stored.
virtual int table_type_error_code(const String_type &schema_name, const String_type &table_name) const =0
Get the error code representing the type name string for a dictionary or system table.
virtual bool is_system_view_name(const char *schema_name, const char *table_name, bool *hidden) const =0
Check if given table name is a system view name.
virtual bool is_system_table_name(const String_type &schema_name, const String_type &table_name) const =0
Check if given table name is a system table name.
virtual ~Dictionary()=default
virtual bool is_dd_table_access_allowed(bool is_dd_internal_thread, bool is_ddl_statement, const char *schema_name, size_t schema_length, const char *table_name) const =0
Check if given table name can be accessed by the given thread type.
This class represents all data dictionary table like mysql.tables, mysql.columns and more.
Definition: object_table.h:71
Definition: tablespace.h:55
Definition: dictionary_client.h:148
borrowable::session_track::Schema< true > Schema
Definition: classic_protocol_session_track.h:288
The version of the current data dictionary table definitions.
Definition: dictionary_client.h:42
bool has_shared_table_mdl(THD *thd, const char *schema_name, const char *table_name)
Predicate to check if we have a shared meta data lock on the submitted schema qualified table name.
Definition: dictionary_impl.cc:518
bool alter_tablespace_encryption(THD *thd, const char *tablespace_name, bool encryption)
Execute an ALTER TABLESPACE ... ENCRYPTION statement.
Definition: dictionary_impl.cc:755
bool acquire_shared_tablespace_mdl(THD *thd, const char *tablespace_name, bool no_wait, MDL_ticket **ticket=nullptr, bool for_trx=true)
Acquire a shared metadata lock on the given tablespace name with transaction duration.
Definition: dictionary_impl.cc:539
bool acquire_exclusive_table_mdl(THD *thd, const char *schema_name, const char *table_name, bool no_wait, MDL_ticket **out_mdl_ticket)
Acquire exclusive metadata lock on the given table name with TRANSACTIONAL duration.
Definition: dictionary_impl.cc:561
bool acquire_exclusive_tablespace_mdl(THD *thd, const char *tablespace_name, bool no_wait, MDL_ticket **ticket=nullptr, bool for_trx=true)
Acquire an exclusive metadata lock on the given tablespace name with transaction duration.
Definition: dictionary_impl.cc:530
bool acquire_exclusive_schema_mdl(THD *thd, const char *schema_name, bool no_wait, MDL_ticket **out_mdl_ticket)
Acquire exclusive metadata lock on the given schema name with explicit duration.
Definition: dictionary_impl.cc:578
bool reset_tables_and_tablespaces()
Reset the tables and tablespace partitions in the DD cache, and invalidate the entries in the DDSE ca...
Definition: dictionary_impl.cc:694
cache::Dictionary_client * get_dd_client(THD *thd)
Get Dictionary_client from THD object (the latter is opaque * in SEs).
Definition: dictionary_impl.cc:592
void rename_tablespace_mdl_hook(THD *thd, MDL_ticket *src, MDL_ticket *dst)
Implicit tablespaces are renamed inside SE.
Definition: dictionary_impl.cc:748
const Object_table & get_dd_table()
Get the Object_table instance storing the given entity object type.
Definition: dictionary_impl.cc:738
bool create_native_table(THD *thd, const Plugin_table *pt)
Create plugin native table.
Definition: dictionary_impl.cc:595
Char_string_template< String_type_allocator > String_type
Definition: string_type.h:50
bool drop_native_table(THD *thd, const char *schema_name, const char *table_name)
Remove plugin native table from DD.
Definition: dictionary_impl.cc:658
bool has_shared_tablespace_mdl(THD *thd, const char *tablespace_name)
Predicate to check if we have a shared meta data lock on the submitted tablespace name.
Definition: dictionary_impl.cc:549
bool acquire_shared_table_mdl(THD *thd, const char *schema_name, const char *table_name, bool no_wait, MDL_ticket **out_mdl_ticket)
Acquire shared metadata lock on the given table name with explicit duration.
Definition: dictionary_impl.cc:510
void release_mdl(THD *thd, MDL_ticket *mdl_ticket)
Release MDL_EXPLICIT lock held by a ticket.
Definition: dictionary_impl.cc:585
bool has_exclusive_table_mdl(THD *thd, const char *schema_name, const char *table_name)
Predicate to check if we have an exclusive meta data lock on the submitted schema qualified table nam...
Definition: dictionary_impl.cc:524
bool has_exclusive_tablespace_mdl(THD *thd, const char *tablespace_name)
Predicate to check if we have an exclusive meta data lock on the submitted tablespace name.
Definition: dictionary_impl.cc:555
bool commit_or_rollback_tablespace_change(THD *thd, dd::Tablespace *space, bool error, bool release_mdl_on_commit_only=false)
Update a tablespace change, commit and release transactional MDL.
Definition: dictionary_impl.cc:714
const char * table_name
Definition: rules_table_service.cc:55