vitess.io/vitess@v0.16.2/go/mysql/doc.go (about)

     1  /*
     2  Copyright 2019 The Vitess Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  // Package mysql is a library to support MySQL binary protocol,
    18  // both client and server sides. It also supports binlog event parsing.
    19  package mysql
    20  
    21  /*
    22  
    23  Implementation notes, collected during coding.
    24  ==============================================
    25  
    26  The reference for the capabilities is at this location:
    27  http://dev.mysql.com/doc/internals/en/capability-flags.html
    28  
    29  --
    30  CLIENT_FOUND_ROWS
    31  
    32  The doc says:
    33  Send found rows instead of affected rows in EOF_Packet.
    34  Value
    35  0x00000002
    36  
    37  We just pass it through to the server.
    38  
    39  --
    40  CLIENT_CONNECT_WITH_DB:
    41  
    42  It drives the ability to connect with a database name.
    43  The server needs to send this flag if it supports it.
    44  If the client supports it as well, and wants to connect with a database name,
    45  then the client can set the flag in its response, and then put the database name
    46  in the handshake response.
    47  
    48  If the server doesn't support it (meaning it is not set in the server
    49  capability flags), then the client may set the flag or not (as the
    50  server should ignore it anyway), and then should send a COM_INIT_DB
    51  message to set the database.
    52  
    53  --
    54  PLUGGABLE AUTHENTICATION:
    55  
    56  See https://dev.mysql.com/doc/internals/en/authentication-method-mismatch.html
    57  for more information on this.
    58  
    59  Our server side always starts by using mysql_native_password, like a
    60  real MySQL server.
    61  
    62  Our client will expect the server to always use mysql_native_password
    63  in its initial handshake. This is what a real server always does, even though
    64  it's not technically mandatory.
    65  
    66  The server's AuthServer plugin method AuthMethod() will then return
    67  what auth method the server wants to use. If it is
    68  mysql_native_password, and the client already returned the data, we
    69  use it. Otherwise we switch the auth to what the server wants (by
    70  sending an Authentication Method Switch Request packet) and
    71  re-negotiate.
    72  
    73  --
    74  Maximum Packet Size:
    75  
    76  Set to zero by client and ignored by the server. Not sure what to do
    77  with this now.  It seems the mysql client is sending 16777216 to the
    78  server, which is what we use anyway. Not sure any client will send any
    79  lower value, and if they do, not sure what the first 3 bytes of a
    80  packet should be (still 0xff 0xff 0xff or the max packet size).
    81  
    82  --
    83  CLIENT_CONNECT_ATTRS
    84  
    85  The client can send up optional connection attributes with this flags.
    86  I don't see a use for them yet.
    87  
    88  --
    89  Multi result sets:
    90  
    91  Only used by stored procedures returning multiple result sets.
    92  Unclear if it is also used when the CLIENT_MULTI_STATEMENTS flag is used.
    93  See: http://dev.mysql.com/doc/internals/en/multi-resultset.html
    94  
    95  The flags returned is then used to mark if there are more result sets
    96  coming up.
    97  
    98  We do not support any of this yet. It would be nice to plumb that for
    99  ExecuteBatch later on though.
   100  
   101  --
   102  Character sets:
   103  
   104  See: http://dev.mysql.com/doc/internals/en/character-set.html#packet-Protocol::CharacterSet
   105  
   106  We maintain a map of character set names to integer value.
   107  
   108  --
   109  Server protection:
   110  
   111  We should add the following protections for the server:
   112  - Limit the number of concurrently opened client connections.
   113  - Add an idle timeout and close connections after that timeout is reached.
   114    Should start during initial handshake, maybe have a shorter value during
   115    handshake.
   116  
   117  --
   118  NUM_FLAG flag:
   119  
   120  It is added by the C client library if the field is numerical.
   121  
   122    if (IS_NUM(client_field->type))
   123      client_field->flags|= NUM_FLAG;
   124  
   125  This is somewhat useless. Also, that flag overlaps with GROUP_FLAG
   126  (which seems to be used by the server only for temporary tables in
   127  some cases, so it's not a big deal).
   128  
   129  But eventually, we probably want to remove it entirely, as it is not
   130  transmitted over the wire. For now, we keep it for backward
   131  compatibility with the C client.
   132  
   133  --
   134  Row-based replication:
   135  
   136  The following types or constructs are not yet supported by our RBR:
   137  
   138  - in MariaDB, the type TIMESTAMP(N) where N>0 is stored in the row the
   139    exact same way as TIMESTAMP(0). So there is no way to get N, except
   140    by knowing the table exact schema. This is such a corner case. MySQL
   141    5.6+ uses TIMESTAMP2, and uses metadata to know the precision, so it
   142    works there very nicely.
   143  
   144    From mariaDB source code comment:
   145    'So row-based replication between temporal data types of
   146    different precision is not possible in MariaDB.'
   147  
   148  - JSON is stored as an optimized index data blob in the row. We don't
   149    parse it to re-print a text version for re-insertion. Instead, we
   150    just return NULL. So JSOn is not supported.
   151  
   152  Replication Notes:
   153  ==================
   154  
   155  This package also defines a few data structures used for replication.
   156  It is meant to only depend on the proto definitions, and nothing else.
   157  Replication support has two main aspects:
   158  
   159  1. Replication event and positions.
   160  
   161  A replication event is an individual event, and it has an ID, called GTID.
   162  
   163  A replication position is defined slightly differently for MariaDB and MySQL 5.6+:
   164  
   165  - MariaDB uses the latest position as an integer, that assumes every
   166    single event before that integer was applied. So a replication
   167    position is similar to a GTID.
   168  
   169  - Mysql 5.6+ keeps track of all event ever applied, in a structure called GTIDSet.
   170  
   171  To make these two compatible, a replication position is defined by
   172  this library as a GTIDSet. For MariaDB, the Set is equal to a Position.
   173  
   174  
   175  2. Binlog event management. They are defined in the MySQL spec at:
   176  http://dev.mysql.com/doc/internals/en/replication-protocol.html
   177  
   178  These are slightly different for MariaDB and MySQL 5.6+, as they
   179  contain GTIDs. MariaDB also defines a GTID event that has an implicit
   180  Begin, that can replace an usual Begin.
   181  
   182  */