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