vitess.io/vitess@v0.16.2/go/vt/vitessdriver/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 vitessdriver contains the Vitess Go SQL driver.
    18  /*
    19  Vitess
    20  
    21  Vitess is an SQL middleware which turns MySQL/MariaDB into a fast, scalable and
    22  highly-available distributed database.
    23  For more information, visit http://www.vitess.io.
    24  
    25  
    26  Example
    27  
    28  Using this SQL driver is as simple as:
    29  
    30    import (
    31      "vitess.io/vitess/go/vt/vitessdriver"
    32    )
    33  
    34    func main() {
    35      // Connect to vtgate.
    36      db, err := vitessdriver.Open("localhost:15991", "@primary")
    37  
    38      // Use "db" via the Golang sql interface.
    39    }
    40  
    41  For a full example, please see: https://github.com/vitessio/vitess/blob/main/test/client.go
    42  
    43  The full example is based on our tutorial for running Vitess locally: https://vitess.io/docs/get-started/local/
    44  
    45  
    46  Vtgate
    47  
    48  This driver connects to a vtgate process. In Vitess, vtgate is a proxy server
    49  that routes queries to the appropriate shards.
    50  
    51  By decoupling the routing logic from the application, vtgate enables Vitess
    52  features like consistent, application-transparent resharding:
    53  When you scale up the number of shards, vtgate becomes aware of the new shards.
    54  You do not have to update your application at all.
    55  
    56  VTGate is capable of breaking up your query into parts, routing them to the
    57  appropriate shards and combining the results, thereby giving the semblance
    58  of a unified database.
    59  
    60  The driver uses the V3 API which doesn't require you to specify routing
    61  information. You just send the query as if Vitess was a regular database.
    62  VTGate analyzes the query and uses additional metadata called VSchema
    63  to perform the necessary routing. See the vtgate v3 Features doc for an overview:
    64  https://github.com/vitessio/vitess/blob/main/doc/VTGateV3Features.md
    65  
    66  As of 12/2015, the VSchema creation is not documented yet as we are in the
    67  process of simplifying the VSchema definition and the overall process for
    68  creating one.
    69  If you want to create your own VSchema, we recommend to have a
    70  look at the VSchema from the vtgate v3 demo:
    71  https://github.com/vitessio/vitess/blob/main/examples/demo/schema
    72  
    73  (The demo itself is interactive and can be run by executing "./run.py" in the
    74  "examples/demo/" directory.)
    75  
    76  The vtgate v3 design doc, which we will also update and simplify in the future,
    77  contains more details on the VSchema:
    78  https://github.com/vitessio/vitess/blob/main/doc/V3VindexDesign.md
    79  
    80  
    81  Isolation levels
    82  
    83  The Vitess isolation model is different from the one exposed by a traditional database.
    84  Isolation levels are controlled by connection parameters instead of Go's IsolationLevel.
    85  You can perform primary, replica or rdonly reads. Primary reads give you read-after-write
    86  consistency. Replica and rdonly reads give you eventual consistency. Replica reads
    87  are for satisfying OLTP workloads while rdonly is for OLAP.
    88  
    89  All transactions must be sent to the primary where writes are allowed.
    90  Replica and rdonly reads can only be performed outside of a transaction. So, there is
    91  no concept of a read-only transaction in Vitess.
    92  
    93  Consequently, no IsolationLevel must be specified while calling BeginContext. Doing so
    94  will result in an error.
    95  
    96  
    97  Named arguments
    98  
    99  Vitess supports positional or named arguments. However, intermixing is not allowed
   100  within a statement. If using named arguments, the ':' and '@' prefixes are optional.
   101  If they're specified, the driver will strip them off before sending the request over
   102  to VTGate.
   103  */
   104  package vitessdriver