github.com/matrixorigin/matrixone@v1.2.0/pkg/proxy/doc.go (about)

     1  // Copyright 2021 - 2023 Matrix Origin
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  /*
    16  Package proxy is used to route client connection to specified CN server and
    17  keep balance between CN servers.
    18  
    19  1. Login
    20  AS MO use MySQL protocol, the handshake process is needed during the login phase.
    21  The general process is as follows:
    22  (1) The client sends a TCP connection to the proxy.
    23  (2) The proxy sends the init handshake package to the client.
    24  (3) The client sends the handshake response to the proxy, including user name, auth
    25  information, connection attributes, etc., and the proxy will save this part of the
    26  information and use it when switching CN servers in the future.
    27  (4) According to the login information of the client, the proxy selects a CN server
    28  to establish a connection, and uses the handshake response just saved for verification.
    29  (5) If the verification is successful, return the client OK package, otherwise return
    30  an error package.
    31  
    32  2. Connection management
    33  When a client connects to the proxy, its connection will be saved and managed, and the
    34  number of connections established on each CN server will be recorded in real time.
    35  This information is used for CN server selection. When a new connection arrives and
    36  the proxy tries to select a CN server, it will choose the CN server with the fewest
    37  connections to establish the connection.
    38  
    39  3. Data interaction
    40  Proxy uses MySQL packet as the basic unit for forwarding, and internally maintains a buffer.
    41  When receiving data from the client, at least one complete MySQL packet is received before
    42  forwarding to the CN server. Conversely, the same is true for data received from the server.
    43  Therefore, it can be observed internally whether the current connection is in the process of
    44  executing a transaction.
    45  
    46  4. Connection balance
    47  Proxy will regularly load balance the connections on the CN servers. When there are too many
    48  connections on a certain CN server, it will select these connections and try to migrate them
    49  to other CN servers. The migration process is transparent to the client.
    50  
    51  A security judgment will be made before attempting to migrate:
    52  (1) Ignore if migration is in progress.
    53  (2) The message returned by the server must be later than the client's request, otherwise
    54  the migration cannot be done.
    55  (3) If you are in a transaction, you cannot do migration. Tracking of transaction state is
    56  recorded as data is interacted.
    57  
    58  5. Scaling:
    59  The proxy module regularly checks the work state of the cn service. If the state is draining,
    60  then migrate the tunnels on the cn to appropriate cns. If no suitable cn is found, an error
    61  will be reported and the original connection will become unavailable.
    62  
    63  6. Usage
    64  Proxy is mainly used on the cloud platform. If you want to use proxy locally, you need to
    65  add configuration -with-proxy to start the proxy module in launch configuration mode, and
    66  add configuration in CN config file:
    67  [cn.frontend]
    68  proxy-enabled = true
    69  
    70  The default port is of proxy service 6009.
    71  
    72  After startup, connect to port 6001 to log in normally, and then use the internal command
    73  to configure the label of cn:
    74  
    75  select mo_ctl('cn', 'label', 'cn_uuid:key:value');
    76  
    77  Examples:
    78  
    79  1. configure tenant information:
    80  
    81  mysql -h127.0.0.1 -udump -P6001 -p111
    82  
    83  create account acc1 admin_name 'root' identified by '111';
    84  select mo_ctl('cn', 'label', 'dd1dccb4-4d3c-41f8-b482-5251dc7a41bf:account:acc1');
    85  
    86  Then you can connect to the proxy to log in to the cluster:
    87  
    88  mysql -h127.0.0.1 -uacc1:root -P6009 -p111
    89  
    90  2. Common labels
    91  
    92  Common labels need to pass to MO server with JDBC connection:
    93  
    94  jdbc:mysql://localhost:6009/db123?serverTimezone=UTC&connectionAttributes=key1:value1
    95  
    96  The labels on CN server need to be set through mo_ctl in local env or yaml file in cloud env.
    97  
    98  Common labels also is supported by mysql client:
    99  
   100  mysql -h127.0.0.1 -udump?k1:v1,k2:v2 -P6009 -p111
   101  */
   102  package proxy