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