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