1/* 2 * Copyright (c) 2015, 2021, Oracle and/or its affiliates. 3 * 4 * This program is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU General Public License, version 2.0, 6 * as published by the Free Software Foundation. 7 * 8 * This program is also distributed with certain software (including 9 * but not limited to OpenSSL) that is licensed under separate terms, 10 * as designated in a particular file or component or in included license 11 * documentation. The authors of MySQL hereby grant you an additional 12 * permission to link the program and your derivative works with the 13 * separately licensed software that they have included with MySQL. 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 23 * 02110-1301 USA 24 */ 25syntax = "proto2"; 26 27// ifdef PROTOBUF_LITE: option optimize_for = LITE_RUNTIME; 28 29// Resultsets 30// `````````` 31// 32// Executing a statement against the server may result in zero or more 33// Resultsets followed by zero or one Resultset of the ``OUT`` parameters. 34// 35// A Resultset consists of: 36// 37// * one or more :protobuf:msg:`Mysqlx.Resultset::ColumnMetaData` 38// * zero or more :protobuf:msg:`Mysqlx.Resultset::Row` 39// 40// It is followed by: 41// 42// * a :protobuf:msg:`Mysqlx.Resultset::FetchDoneMoreResultsets` if more 43// resultsets are following 44// * a :protobuf:msg:`Mysqlx.Resultset::FetchDoneMoreOutParams` if more 45// Resultset of ``OUT`` parameters is following 46// * a :protobuf:msg:`Mysqlx.Resultset::FetchDone` if the last resultset 47// was sent 48// 49// .. uml:: 50// 51// ... 52// loop has more resultsets 53// group resultset 54// loop has more columns 55// server --> client: ColumnMetaData 56// end 57// loop has more rows 58// server --> client: Row 59// end 60// end 61// alt has more resultsets 62// server --> client: FetchDoneMoreResultsets 63// end 64// end 65// loop has more OUT-paramsets 66// server --> client: FetchDoneMoreOutParams 67// group resultset 68// loop has more columns 69// server --> client: ColumnMetaData 70// end 71// loop has more rows 72// server --> client: Row 73// end 74// end 75// end 76// server --> client: FetchDone 77// ... 78// 79// Examples 80// ```````` 81// 82// .. rubric:: No Resultset 83// 84// A ``INSERT`` statement usually doesn't send any resultset which results in only 85// a ``FetchDone``. 86// 87// .. uml:: 88// 89// server --> client: FetchDone 90// 91// .. rubric:: Empty Resultset 92// 93// ``SELECT 1 LIMIT 0`` results in a empty resultset: 94// 95// .. uml:: 96// 97// server --> client: ColumnMetaData(.name = "1", .type = INT) 98// server --> client: FetchDone 99// 100// .. rubric:: Multi Resultset 101// 102// ``CALL`` may result in multiple resultsets. 103// 104// .. uml:: 105// 106// server --> client: ColumnMetaData(.name = "1", .type = INT) 107// server --> client: Row 108// server --> client: FetchDoneMoreResultsets 109// server --> client: ColumnMetaData(.name = "1", .type = INT) 110// server --> client: Row 111// server --> client: FetchDone 112// 113// .. rubric:: OUT params 114// 115// ``CALL`` may result OUT parameters only 116// 117// .. uml:: 118// 119// server --> client: FetchDoneMoreOutParams 120// server --> client: ColumnMetaData(.name = "1", .type = INT) 121// server --> client: Row 122// server --> client: FetchDone 123 124 125 126package Mysqlx.Resultset; 127option java_package = "com.mysql.cj.x.protobuf"; 128 129// resultsets are finished, OUT paramset is next 130message FetchDoneMoreOutParams { 131} 132 133// resultset and out-params are finished, but more resultsets available 134message FetchDoneMoreResultsets { 135} 136 137// all resultsets are finished 138message FetchDone { 139} 140 141// meta data of a Column 142// 143// .. note:: the encoding used for the different ``bytes`` fields in the meta data is externally 144// controlled. 145// .. seealso:: https://dev.mysql.com/doc/refman/5.7/en/charset-connection.html 146// 147// .. note:: 148// The server may not set the ``original_{table|name}`` fields if they are equal to the plain 149// ``{table|name}`` field. 150// 151// A client has to reconstruct it like:: 152// 153// if .original_name is empty and .name is not empty: 154// .original_name = .name 155// 156// if .original_table is empty and .table is not empty: 157// .original_table = .table 158// 159// .. note:: 160// ``compact metadata format`` can be requested by the client. In that case only ``.type`` is set and 161// all other fields are empty. 162// 163// 164// :param type: 165// .. table:: Expected Datatype of Mysqlx.Resultset.Row per SQL Type for non NULL values 166// 167// ================= ============ ======= ========== ====== ======== 168// SQL Type .type .length .frac_dig .flags .charset 169// ================= ============ ======= ========== ====== ======== 170// TINY SINT x 171// TINY UNSIGNED UINT x x 172// SHORT SINT x 173// SHORT UNSIGNED UINT x x 174// INT24 SINT x 175// INT24 UNSIGNED UINT x x 176// INT SINT x 177// INT UNSIGNED UINT x x 178// LONGLONG SINT x 179// LONGLONG UNSIGNED UINT x x 180// DOUBLE DOUBLE x x x 181// FLOAT FLOAT x x x 182// DECIMAL DECIMAL x x x 183// VARCHAR,CHAR,... BYTES x x x 184// GEOMETRY BYTES 185// TIME TIME x 186// DATE DATETIME x 187// DATETIME DATETIME x 188// YEAR UINT x x 189// TIMESTAMP DATETIME x 190// SET SET x 191// ENUM ENUM x 192// NULL BYTES 193// BIT BIT x 194// ================= ============ ======= ========== ====== ======== 195// 196// .. note:: the SQL "NULL" value is sent as an empty field value in :protobuf:msg:`Mysqlx.Resultset::Row` 197// .. seealso:: protobuf encoding of primitive datatypes are decribed in https://developers.google.com/protocol-buffers/docs/encoding 198// 199// SINT 200// 201// ``.length`` 202// maximum number of displayable decimal digits (including minus sign) of the type 203// 204// .. note:: 205// valid range is 0-255, but usually you'll see 1-20 206// 207// =============== == 208// SQL Type max digits per type 209// =============== == 210// TINY SIGNED 4 211// SHORT SIGNED 6 212// INT24 SIGNED 8 213// INT SIGNED 11 214// LONGLONG SIGNED 20 215// =============== == 216// 217// .. seealso:: definition of ``M`` in https://dev.mysql.com/doc/refman/5.7/en/numeric-type-overview.html 218// 219// ``value`` 220// variable length encoded signed 64 integer 221// 222// UINT 223// 224// ``.flags & 1`` (zerofill) 225// the client has to left pad with 0's up to .length 226// 227// ``.length`` 228// maximum number of displayable decimal digits of the type 229// 230// .. note:: 231// valid range is 0-255, but usually you'll see 1-20 232// 233// ================= == 234// SQL Type max digits per type 235// ================= == 236// TINY UNSIGNED 3 237// SHORT UNSIGNED 5 238// INT24 UNSIGNED 8 239// INT UNSIGNED 10 240// LONGLONG UNSIGNED 20 241// ================= == 242// 243// .. seealso:: definition of ``M`` in https://dev.mysql.com/doc/refman/5.7/en/numeric-type-overview.html 244// 245// ``value`` 246// variable length encoded unsigned 64 integer 247// 248// BIT 249// 250// ``.length`` 251// maximum number of displayable binary digits 252// 253// .. note:: valid range for M of the ``BIT`` type is 1 - 64 254// .. seealso:: https://dev.mysql.com/doc/refman/5.7/en/numeric-type-overview.html 255// 256// ``value`` 257// variable length encoded unsigned 64 integer 258// 259// DOUBLE 260// 261// ``.length`` 262// maximum number of displayable decimal digits (including the decimal point and ``.fractional_digits``) 263// 264// ``.fractional_digits`` 265// maximum number of displayable decimal digits following the decimal point 266// 267// ``value`` 268// encoded as Protobuf's 'double' 269// 270// FLOAT 271// 272// ``.length`` 273// maximum number of displayable decimal digits (including the decimal point and ``.fractional_digits``) 274// 275// ``.fractional_digits`` 276// maximum number of displayable decimal digits following the decimal point 277// 278// ``value`` 279// encoded as Protobuf's 'float' 280// 281// BYTES, ENUM 282// BYTES is used for all opaque byte strings that may have a charset 283// 284// * TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB 285// * TINYTEXT, TEXT, MEDIUMTEXT, LONGTEXT 286// * VARCHAR, VARBINARY 287// * CHAR, BINARY 288// * ENUM 289// 290// ``.length`` 291// the maximum length of characters of the underlying type 292// 293// ``.flags & 1`` (rightpad) 294// if the length of the field is less than ``.length``, the receiver is 295// supposed to add padding characters to the right end of the string. 296// If the ``.charset`` is "binary", the padding character is ``0x00``, 297// otherwise it is a space character as defined by that character set. 298// 299// ============= ======= ======== ======= 300// SQL Type .length .charset .flags 301// ============= ======= ======== ======= 302// TINYBLOB 256 binary 303// BLOB 65535 binary 304// VARCHAR(32) 32 utf8 305// VARBINARY(32) 32 utf8_bin 306// BINARY(32) 32 binary rightpad 307// CHAR(32) 32 utf8 rightpad 308// ============= ======= ======== ======= 309// 310// ``value`` 311// sequence of bytes with added one extra '\0' byte at the end. To obtain the 312// original string, the extra '\0' should be removed. 313// .. note:: the length of the string can be acquired with protobuf's field length() method 314// length of sequence-of-bytes = length-of-field - 1 315// .. note:: the extra byte allows to distinguish between a NULL and empty byte sequence 316// 317// TIME 318// A time value. 319// 320// ``value`` 321// the following bytes sequence: 322// 323// ``| negate [ | hour | [ | minutes | [ | seconds | [ | useconds | ]]]]`` 324// 325// * negate - one byte, should be one of: 0x00 for "+", 0x01 for "-" 326// * hour - optional variable length encoded unsigned64 value for the hour 327// * minutes - optional variable length encoded unsigned64 value for the minutes 328// * seconds - optional variable length encoded unsigned64 value for the seconds 329// * useconds - optional variable length encoded unsigned64 value for the microseconds 330// 331// .. seealso:: protobuf encoding in https://developers.google.com/protocol-buffers/docs/encoding 332// .. note:: hour, minutes, seconds, useconds are optional if all the values to the right are 0 333// 334// Example: 0x00 -> +00:00:00.000000 335// 336// DATETIME 337// A date or date and time value. 338// 339// ``value`` 340// a sequence of variants, arranged as follows: 341// 342// ``| year | month | day | [ | hour | [ | minutes | [ | seconds | [ | useconds | ]]]]`` 343// 344// * year - variable length encoded unsigned64 value for the year 345// * month - variable length encoded unsigned64 value for the month 346// * day - variable length encoded unsigned64 value for the day 347// * hour - optional variable length encoded unsigned64 value for the hour 348// * minutes - optional variable length encoded unsigned64 value for the minutes 349// * seconds - optional variable length encoded unsigned64 value for the seconds 350// * useconds - optional variable length encoded unsigned64 value for the microseconds 351// 352// .. note:: hour, minutes, seconds, useconds are optional if all the values to the right are 0 353// 354// ``.flags & 1`` (timestamp) 355// 356// ============= ======= 357// SQL Type .flags 358// ============= ======= 359// DATETIME 360// TIMESTAMP 1 361// 362// DECIMAL 363// An arbitrary length number. The number is encoded as a single byte 364// indicating the position of the decimal point followed by the Packed BCD 365// encoded number. Packed BCD is used to simplify conversion to and 366// from strings and other native arbitrary precision math datatypes. 367// .. seealso:: packed BCD in https://en.wikipedia.org/wiki/Binary-coded_decimal 368// 369// ``.length`` 370// maximum number of displayable decimal digits (*excluding* the decimal point and sign, but including ``.fractional_digits``) 371// 372// .. note:: should be in the range of 1 - 65 373// 374// ``.fractional_digits`` 375// is the decimal digits to display out of length 376// 377// .. note:: should be in the range of 0 - 30 378// 379// ``value`` 380// the following bytes sequence: 381// 382// ``| scale | BCD | sign | [0x0] |`` 383// 384// * scale - 8bit scale value (number of decimal digit after the '.') 385// * BCD - BCD encoded digits (4 bits for each digit) 386// * sign - sign encoded on 4 bits (0xc = "+", 0xd = "-") 387// * 0x0 - last 4bits if length(digits) % 2 == 0 388// 389// Example: x04 0x12 0x34 0x01 0xd0 -> -12.3401 390// 391// SET 392// A list of strings representing a SET of values. 393// 394// ``value`` 395// A sequence of 0 or more of protobuf's bytes (length prepended octets) or one of 396// the special sequences with a predefined meaning listed below. 397// 398// Example (length of the bytes array shown in brackets): 399// * ``[0]`` - the NULL value 400// * ``[1] 0x00`` - a set containing a blank string '' 401// * ``[1] 0x01`` - this would be an invalid value, but is to be treated as the empty set 402// * ``[2] 0x01 0x00`` - a set with a single item, which is the '\0' character 403// * ``[8] 0x03 F O O 0x03 B A R`` - a set with 2 items: FOO,BAR 404// 405// 406// :param name: name of the column 407// :param original_name: name of the column before an alias was applied 408// :param table: name of the table the column orginates from 409// :param original_table: name of the table the column orginates from before an alias was applied 410// :param schema: schema the column originates from 411// :param catalog: 412// catalog the schema originates from 413// 414// .. note:: 415// as there is current no support for catalogs in MySQL, don't expect this field to be set. 416// In the MySQL C/S protocol the field had the value ``def`` all the time. 417// 418// :param fractional_digits: displayed factional decimal digits for floating point and fixed point numbers 419// :param length: maximum count of displayable characters of .type 420// :param flags: 421// ``.type`` specific flags 422// 423// ======= ====== =========== 424// type value description 425// ======= ====== =========== 426// UINT 0x0001 zerofill 427// DOUBLE 0x0001 unsigned 428// FLOAT 0x0001 unsigned 429// DECIMAL 0x0001 unsigned 430// BYTES 0x0001 rightpad 431// ======= ====== =========== 432// 433// ====== ================ 434// value description 435// ====== ================ 436// 0x0010 NOT_NULL 437// 0x0020 PRIMARY_KEY 438// 0x0040 UNIQUE_KEY 439// 0x0080 MULTIPLE_KEY 440// 0x0100 AUTO_INCREMENT 441// ====== ================ 442// 443// default: 0 444// :param content_type: 445// a hint about the higher-level encoding of a BYTES field 446// 447// ====== ====== =========== 448// type value description 449// ====== ====== =========== 450// BYTES 0x0001 GEOMETRY (WKB encoding) 451// BYTES 0x0002 JSON (text encoding) 452// BYTES 0x0003 XML (text encoding) 453// ====== ====== =========== 454// 455// .. note:: 456// this list isn't comprehensive. As guideline: the field's value is expected 457// to pass a validator check on client and server if this field is set. 458// If the server adds more internal datatypes that rely on BLOB storage 459// like image manipulation, seeking into complex types in BLOBs, ... more 460// types will be added. 461// 462message ColumnMetaData { 463 enum FieldType { 464 SINT = 1; 465 UINT = 2; 466 467 DOUBLE = 5; 468 FLOAT = 6; 469 470 BYTES = 7; 471 472 TIME = 10; 473 DATETIME = 12; 474 SET = 15; 475 ENUM = 16; 476 BIT = 17; 477 478 DECIMAL = 18; 479 } 480 481 // datatype of the field in a row 482 required FieldType type = 1; 483 optional bytes name = 2; 484 optional bytes original_name = 3; 485 486 optional bytes table = 4; 487 optional bytes original_table = 5; 488 489 optional bytes schema = 6; 490 optional bytes catalog = 7; 491 492 optional uint64 collation = 8; 493 494 optional uint32 fractional_digits = 9; 495 496 optional uint32 length = 10; 497 498 optional uint32 flags = 11; 499 500 optional uint32 content_type = 12; 501} 502 503// Row in a Resultset 504// 505// a row is represented as a list of fields encoded as byte blobs. 506// Blob of size 0 represents the NULL value. Otherwise, if it contains at least 507// one byte, it encodes a non-null value of the field using encoding appropriate for the 508// type of the value given by ``ColumnMetadata``, as specified 509// in the :protobuf:msg:`Mysqlx.Resultset::ColumnMetaData` description. 510// 511message Row { 512 repeated bytes field = 1; 513} 514 515