MySQL 9.0.0
Source Code Documentation
sdi.h
Go to the documentation of this file.
1/* Copyright (c) 2015, 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__SDI_INCLUDED
25#define DD__SDI_INCLUDED
26
27#include <cstdint>
28#include <functional>
29#include "my_compiler.h"
30#include "sql/dd/sdi_fwd.h" // RJ_Document
31#include "sql/dd/string_type.h" // dd::String_type
32
33class THD;
34struct handlerton;
35
36/**
37 @file
38 @ingroup sdi
39
40 Exposes SDI-related functionality to the rest of the dictionary code.
41*/
42
43namespace dd {
44
45class Schema;
46class Table;
47class Tablespace;
48class View;
49
51
52/**
53 The version of the current SDI Json format.
54
55 This version number is stored inside SDIs. This number is bumpred only when
56 there is a change in how the data dictionary information is converted to json
57 (e.g. adding a forgotten member). It does not need to be bumped when the data
58 dictionary schema structure is changed, as this is covered by the DD_VERSION
59 variable.
60
61 The SDI version number is the MySQL server version number
62 of the first MySQL server version that published a given SDI Json format.
63 The format is Mmmdd with M=Major, m=minor, d=dot, so that MySQL 8.0.4 is
64 encoded as 80004. This is the same version numbering scheme as the
65 information schema and performance schema are using.
66
67 The next change to the SDI Json format will be associated with the next
68 available MySQL server version number.
69
70 Historical version number published in the data dictionary, (note that 1 is a
71 legacy number from before SDI version numbers were mapped to server versions):
72
73
74 1: Published in 8.0.15
75 ----------------------------------------------------------------------------
76 Initial version.
77
78
79 80016: Published in 8.0.16
80 ----------------------------------------------------------------------------
81 Changes from version 1:
82
83 - Bug#29210646: DD::INDEX_IMPL::M_HIDDEN NOT INCLUDED IN SDI
84
85
86 80019: Current
87 ----------------------------------------------------------------------------
88 Changes from version 80016:
89
90 - Bug#30326020: SUBPARTITIONING NOT REFLECTED IN SDI
91
92
93 800XX: Next SDI version number after the previous is public. The next
94 server version > current SDI version where a change to the SDI
95 JSON format is made.
96 ----------------------------------------------------------------------------
97 Changes from current version:
98
99 - No changes, this version number is not active yet.
100
101 If a new SDI version is published in a MRU, it will not
102 be possible to import this version into previous MRUs within the same GA.
103*/
104constexpr const std::uint64_t SDI_VERSION = 80019;
105
106/**
107 @defgroup serialize_api (De)serialize api functions.
108 @ingroup sdi
109
110 Functions for serializing (with complete header) and deserializing
111 the dd object which supports this.
112 @{
113 */
114
115/**
116 Serialize a Schema object.
117
118 @param schema dobject which will be serialized
119
120 @return sdi (as json string).
121
122*/
123Sdi_type serialize(const Schema &schema);
124
125/**
126 Serialize a Table object.
127
128 @param thd thread context
129 @param table object which will be serialized
130 @param schema_name name of the schema
131 @return sdi (as json string).
132
133*/
134Sdi_type serialize(THD *thd, const Table &table,
135 const String_type &schema_name);
136
137/**
138 Serialize a Tablespace object.
139
140 @param tablespace object which will be serialized
141
142 @return sdi (as json string).
143
144*/
145
146Sdi_type serialize(const Tablespace &tablespace);
147
148/**
149 Type alias for std::function wrapping a callable to check if
150 SDI, as an RJ_Document, is compatible. Normal MySQL error handling.
151 Return value: false => success, true => error in DA.
152*/
153using SdiCompatibilityChecker = std::function<bool(const RJ_Document &)>;
154
156
157bool deserialize(THD *thd, const Sdi_type &sdi, Table *table,
158 SdiCompatibilityChecker comp_checker,
159 String_type *deser_schema_name = nullptr);
160
161/**
162 Deserialize a dd::Table object.
163
164 Populates the dd::Table object provided with data from sdi string.
165 Note! Additional objects are dynamically allocated and added to the
166 top-level Schema object, which assumes ownership.
167 @note Uses the default strict compatibility checking, @see
168 DefaultCheckCompatibility
169
170 @param thd thread context
171 @param sdi serialized representation of schema (as a json string)
172 @param table empty top-level object
173 @param deser_schema_name name of schema containing the table
174
175 @return error status
176 @retval false if successful
177 @retval true otherwise
178*/
179inline bool deserialize(THD *thd, const Sdi_type &sdi, Table *table,
180 String_type *deser_schema_name = nullptr) {
182 deser_schema_name);
183}
184
185bool deserialize(THD *thd, const Sdi_type &sdi, Tablespace *tablespace,
186 SdiCompatibilityChecker comp_checker);
187
188/**
189 Deserialize a dd::Tablespace object.
190
191 Populates the dd::Tablespace object provided with data from sdi string.
192 Note! Additional objects are dynamically allocated and added to the
193 top-level Tablespace object, which assumes ownership.
194
195 @note Uses the default strict compatibility checking, @see
196 DefaultCheckCompatibility
197
198 @param thd thread context
199 @param sdi serialized representation of schema (as a json string)
200 @param tablespace empty top-level object
201
202 @return error status
203 @retval false if successful
204 @retval true otherwise
205*/
206inline bool deserialize(THD *thd, const Sdi_type &sdi, Tablespace *tablespace) {
207 return deserialize(thd, sdi, tablespace, CheckDefaultCompatibility);
208}
209
210/** @} End of group serialize_api */
211
212namespace sdi {
213
214/**
215 @defgroup sdi_storage_ops Storage operations on SDIs.
216 @ingroup sdi
217
218 Functions for storing and dropping (deleting) SDIs. To be used from
219 dd::cache::Storage_adapter and dd::cache::Dictionary_client to store
220 and remove SDIs as DD objects are added, modified or deleted.
221 @{
222*/
223
224/**
225 Generic noop for all types that don't have a specific overload. No
226 SDIs are written for these types.
227
228 @param thd thread context
229 @param ddo DD object
230 @return error status
231 @retval false always
232 */
233
234template <class DDT>
235inline bool store(THD *thd [[maybe_unused]], const DDT *ddo [[maybe_unused]]) {
236 return false;
237}
238
239/**
240 Stores the SDI for a table.
241
242 Serializes the table, and then forwards to SE through handlerton
243 api, or falls back to storing the sdi string in an .SDI file in the
244 default case. The schema object is serialized and stored
245 if the schema's SDI file does not exist, or if is missing from the
246 tablespace used to store the table.
247
248 @param thd thread context
249 @param t Table object.
250
251 @return error status
252 @retval false on success
253 @retval true otherwise
254*/
255
256bool store(THD *thd, const Table *t);
257
258/**
259 Stores the SDI for a table space.
260
261 Serializes the table space object, and then forwards to SE through
262 handlerton api, or falls back to storing the sdi string in an .SDI
263 file in the default case.
264
265 @param thd thread context
266 @param ts Tablespace object.
267
268 @return error status
269 @retval false on success
270 @retval true otherwise
271*/
272
273bool store(THD *thd, const Tablespace *ts);
274
275/**
276 Generic noop for all types that don't have a specific overload. No
277 SDIs are removed for these types.
278
279 @param thd thread context
280 @return error status
281 @retval false always
282 */
283
284template <class DDT>
285inline bool drop(THD *thd [[maybe_unused]], const DDT *) {
286 return false;
287}
288
289/**
290 Remove SDI for a table.
291
292 Forwards to SE through handlerton api, which will remove from
293 tablespace, or falls back to deleting the .SDI file in the default
294 case.
295
296 @param thd thread context
297 @param t Table object.
298
299 @return error status
300 @retval false on success
301 @retval true otherwise
302*/
303
304bool drop(THD *thd, const Table *t);
305
306// Note that there is NO drop() overload for Tablespace. Dropping a
307// tablespace implies that all sdis in it are dropped also.
308
309/**
310 Hook for SDI cleanup after updating DD object. Generic noop for all
311 types that don't have a specific overload.
312
313 @param thd thread context
314 @param old_ddo old DD object
315 @param new_ddo new DD object
316 @return error status
317 @retval false always
318 */
319
320template <class DDT>
321inline bool drop_after_update(THD *thd [[maybe_unused]],
322 const DDT *old_ddo [[maybe_unused]],
323 const DDT *new_ddo [[maybe_unused]]) {
324 return false;
325}
326
327/**
328 Table cleanup hook. When a Dictionary_client issues a store which is
329 performed as an update in the DD a new table SDI file will be
330 stored. If SDI is stored in a file and the update modifies the name
331 of the table it is necessary to remove the old SDI file after the
332 new one has been written successfully. If the file names are the
333 same the file is updated in place, potentially leaving it corrupted
334 if something goes wrong. If the SDI is stored in a tablespace it
335 will use the same key even if the names change and the update will
336 transactional so then this hook does nothing.
337
338 @param thd thread context
339 @param old_t old Schema object
340 @param new_t new Schema object
341
342 @return error status
343 @retval false on success
344 @retval true otherwise
345*/
346
347bool drop_after_update(THD *thd, const Table *old_t, const Table *new_t);
348
349/** @} End of group sdi_storage_ops */
350} // namespace sdi
351} // namespace dd
352
353#endif /* DD__SDI_INCLUDED */
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
Definition: schema.h:63
Definition: table.h:47
Definition: tablespace.h:56
bool drop(THD *thd, const Table *tp)
Remove SDI for a table.
Definition: sdi.cc:639
bool drop_after_update(THD *thd, const Table *old_tp, const Table *new_tp)
Table cleanup hook.
Definition: sdi.cc:650
bool store(THD *thd, const Table *tp)
Stores the SDI for a table.
Definition: sdi.cc:607
bool CheckDefaultCompatibility(const RJ_Document &doc)
Default checker which implements the traditional (strict) compatibility check: MYSQL_VERSION less tha...
Definition: sdi.cc:379
Sdi_type serialize(THD *thd, const Table &table, const String_type &schema_name)
Serialize a Table object.
Definition: sdi.cc:364
std::function< bool(const RJ_Document &)> SdiCompatibilityChecker
Type alias for std::function wrapping a callable to check if SDI, as an RJ_Document,...
Definition: sdi.h:153
bool deserialize(THD *thd, const Sdi_type &sdi, Table *dst_table, SdiCompatibilityChecker comp_checker, String_type *deser_schema_name)
Deserialize a dd::Table object.
Definition: sdi.cc:475
Header for compiler-dependent features.
static PFS_engine_table_share_proxy table
Definition: pfs.cc:61
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
String_type Sdi_type
Definition: sdi.h:48
constexpr const std::uint64_t SDI_VERSION
The version of the current SDI Json format.
Definition: sdi.h:104
rapidjson::GenericDocument< RJ_Encoding, RJ_Allocator, rapidjson::CrtAllocator > RJ_Document
Definition: sdi_fwd.h:48
Char_string_template< String_type_allocator > String_type
Definition: string_type.h:51
This header provides Rapidjson Type Aliases.
handlerton is a singleton structure - one instance per storage engine - to provide access to storage ...
Definition: handler.h:2734