README
¶
Vitess
This is the Go SQL driver for Vitess.
Vitess is an SQL middleware which turns MySQL/MariaDB into a fast, scalable and highly-available distributed database. For more information, visit www.vitess.io.
Documentation
For more information on this driver, please see its godoc page:
https://godoc.org/vitess.io/vitess/go/vt/vitessdriver
Installation
go get vitess.io/vitess/go/vt/vitessdriver
See the documentation link above for examples.
Documentation
¶
Overview ¶
Package vitessdriver contains the Vitess Go SQL driver.
Vitess ¶
Vitess is an SQL middleware which turns MySQL/MariaDB into a fast, scalable and highly-available distributed database. For more information, visit http://www.vitess.io.
Example ¶
Using this SQL driver is as simple as:
import (
"vitess.io/vitess/go/vt/vitessdriver"
)
func main() {
// Connect to vtgate.
db, err := vitessdriver.Open("localhost:15991", "@primary")
// Use "db" via the Golang sql interface.
}
For a full example, please see: https://github.com/vitessio/vitess/blob/main/test/client.go
The full example is based on our tutorial for running Vitess locally: https://vitess.io/docs/get-started/local/
Vtgate ¶
This driver connects to a vtgate process. In Vitess, vtgate is a proxy server that routes queries to the appropriate shards.
By decoupling the routing logic from the application, vtgate enables Vitess features like consistent, application-transparent resharding: When you scale up the number of shards, vtgate becomes aware of the new shards. You do not have to update your application at all.
VTGate is capable of breaking up your query into parts, routing them to the appropriate shards and combining the results, thereby giving the semblance of a unified database.
The driver uses the V3 API which doesn't require you to specify routing information. You just send the query as if Vitess was a regular database. VTGate analyzes the query and uses additional metadata called VSchema to perform the necessary routing. See the vtgate v3 Features doc for an overview: https://github.com/vitessio/vitess/blob/main/doc/VTGateV3Features.md
As of 12/2015, the VSchema creation is not documented yet as we are in the process of simplifying the VSchema definition and the overall process for creating one. If you want to create your own VSchema, we recommend to have a look at the VSchema from the vtgate v3 demo: https://github.com/vitessio/vitess/blob/main/examples/demo/schema
(The demo itself is interactive and can be run by executing "./run.py" in the "examples/demo/" directory.)
The vtgate v3 design doc, which we will also update and simplify in the future, contains more details on the VSchema: https://github.com/vitessio/vitess/blob/main/doc/V3VindexDesign.md
Isolation levels ¶
The Vitess isolation model is different from the one exposed by a traditional database. Isolation levels are controlled by connection parameters instead of Go's IsolationLevel. You can perform primary, replica or rdonly reads. Primary reads give you read-after-write consistency. Replica and rdonly reads give you eventual consistency. Replica reads are for satisfying OLTP workloads while rdonly is for OLAP.
All transactions must be sent to the primary where writes are allowed. Replica and rdonly reads can only be performed outside of a transaction. So, there is no concept of a read-only transaction in Vitess.
Consequently, no IsolationLevel must be specified while calling BeginContext. Doing so will result in an error.
Named arguments ¶
Vitess supports positional or named arguments. However, intermixing is not allowed within a statement. If using named arguments, the ':' and '@' prefixes are optional. If they're specified, the driver will strip them off before sending the request over to VTGate.
Index ¶
- Variables
- func DistributedTxFromSessionToken(ctx context.Context, c Configuration) (*sql.Tx, func() error, error)
- func NewDatetime(t time.Time, defaultLoc *time.Location) sqltypes.Value
- func Open(address, target string) (*sql.DB, error)
- func OpenForStreaming(address, target string) (*sql.DB, error)
- func OpenWithConfiguration(c Configuration) (*sql.DB, error)
- func SessionTokenFromTx(ctx context.Context, tx *sql.Tx) (string, error)
- type Configuration
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidTime = errors.New("invalid MySQL time string")
ErrInvalidTime is returned when we fail to parse a datetime string from MySQL. This should never happen unless things are seriously messed up.
Functions ¶
func DistributedTxFromSessionToken ¶ added in v0.13.0
func DistributedTxFromSessionToken(ctx context.Context, c Configuration) (*sql.Tx, func() error, error)
DistributedTxFromSessionToken allows users to send serialized sessions over the wire and reconnect to an existing transaction. Setting the sessionToken and address on the supplied configuration is the minimum required WARNING: the original Tx must already have already done work on all shards to be affected, otherwise the ShardSessions will not be sent through in the session token, and thus will never be committed in the source. The returned validation function checks to make sure that the new transaction work has not added any new ShardSessions.
func NewDatetime ¶
NewDatetime builds a Datetime Value
func Open ¶
Open is a Vitess helper function for sql.Open().
It opens a database connection to vtgate running at "address".
func OpenForStreaming ¶
OpenForStreaming is the same as Open() but uses streaming RPCs to retrieve the results.
The streaming mode is recommended for large results.
func OpenWithConfiguration ¶
func OpenWithConfiguration(c Configuration) (*sql.DB, error)
OpenWithConfiguration is the generic Vitess helper function for sql.Open().
It allows to pass in a Configuration struct to control all possible settings of the Vitess Go SQL driver.
Types ¶
type Configuration ¶
type Configuration struct {
// Protocol is the name of the vtgate RPC client implementation.
// Note: In open-source "grpc" is the recommended implementation.
//
// Default: "grpc"
Protocol string
// Address must point to a vtgate instance.
//
// Format: hostname:port
Address string
// Target specifies the default target.
Target string
// Streaming is true when streaming RPCs are used.
// Recommended for large results.
// Default: false
Streaming bool
// DefaultLocation is the timezone string that will be used
// when converting DATETIME and DATE into time.Time.
// This setting has no effect if ConvertDatetime is not set.
// Default: UTC
DefaultLocation string
// GRPCDialOptions registers a new vtgateconn dialer with these dial options using the
// protocol as the key. This may overwrite the default grpcvtgateconn dial option
// if a custom one hasn't been specified in the config.
//
// Default: none
GRPCDialOptions []grpc.DialOption `json:"-"`
// Driver is the name registered with the database/sql package. This override
// is here in case you have wrapped the driver for stats or other interceptors.
//
// Default: "vitess"
DriverName string `json:"-"`
// SessionToken is a protobuf encoded vtgatepb.Session represented as base64, which
// can be used to distribute a transaction over the wire.
SessionToken string
}
Configuration holds all Vitess driver settings.
Fields with documented default values do not have to be set explicitly.
Source Files