vitessdriver

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/github.com/youtube/vitess/go/vt/vitessdriver

Installation

go get github.com/youtube/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 (
  "time"
  "github.com/youtube/vitess/go/vt/vitessdriver"
)

func main() {
  // Connect to vtgate (v1 mode).
  db, err := vitessdriver.Open("localhost:15991", "keyspace", "0", "master", 30*time.Second)

  // Use "db" via the Golang sql interface.
}

For a full example, please see: https://github.com/youtube/vitess/blob/master/examples/local/client.go

The full example is based on our tutorial for running Vitess locally: http://vitess.io/getting-started/local-instance.html

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.

Another Vitess feature is the vtgate v3 API. Once enabled, a sharded Vitess setup becomes a drop-in replacement for an unsharded MySQL/MariaDB setup.

Vtgate API Versions

This driver supports the vtgate API versions v1 and v3, but not v2.

We recommend you use the v1 API for initial experiments and then switch to v3 later because v3 requires an additional setup step.

The API versions differ as follows:

Vtgate API v1

v1 requires each query to specify the target shard. vtgate then routes the query accordingly.

This driver supports the v1 API at the connection level. For example, to open a Vitess database connection for queries targeting shard "0" in the keyspace "test_keyspace", call:

vitessdriver.OpenShard(vtgateAddress, "test_keyspace", "0", 30*time.Second)

This mode is recommended for initial experiments or when migrating from a pure MySQL/MariaDB setup to an unsharded Vitess setup. For a sharded Vitess setup we recommend to move to the v2 or v3 API because only these APIs are agnostic of resharding events.

Vtgate API v2

v2 requires each query to specify the affected sharding keys ("keyspace_id").

Based on the provided sharding key, vtgate then routes the query to the shard that currently covers that sharding key.

This driver currently does not support the v2 API because it's difficult to enhance the Go SQL interface with the sharding key information at the query-level. Instead, it's recommended to use the v3 API.

Vtgate API v3

v3 automatically infers the sharding key (and therefore the target shard) from the query itself.

It also maintains secondary indexes across shards and generates values for AUTO_INCREMENT columns.

See the vtgate v3 Features doc for an overview: https://github.com/youtube/vitess/blob/master/doc/VTGateV3Features.md

To enable vtgate v3, you need to create a VSchema. A VSchema defines for vtgate the properties of your Vitess setup (e.g. what is the sharding key, which cross-shard indexes should be maintained, what are the AUTO_INCREMENT columns).

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/youtube/vitess/blob/master/examples/demo/schema/vschema.json

(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/youtube/vitess/blob/master/doc/V3VindexDesign.md

Index

• func Open(address, tabletType string, timeout time.Duration) (*sql.DB, error)
• func OpenForStreaming(address, tabletType string, timeout time.Duration) (*sql.DB, error)
• func OpenShard(address, keyspace, shard, tabletType string, timeout time.Duration) (*sql.DB, error)
• func OpenShardForStreaming(address, keyspace, shard, tabletType string, timeout time.Duration) (*sql.DB, error)
• func OpenWithConfiguration(c Configuration) (*sql.DB, error)
• type Configuration

Functions

func Open

func Open(address, tabletType string, timeout time.Duration) (*sql.DB, error)

Open is a Vitess helper function for sql.Open().

It opens a database connection to vtgate running at "address".

Note that this is the vtgate v3 mode and requires a loaded VSchema.

func OpenForStreaming

func OpenForStreaming(address, tabletType string, timeout time.Duration) (*sql.DB, error)

OpenForStreaming is the same as Open() but uses streaming RPCs to retrieve the results.

The streaming mode is recommended for large results.

func OpenShard

func OpenShard(address, keyspace, shard, tabletType string, timeout time.Duration) (*sql.DB, error)

OpenShard connects to vtgate running at "address".

Unlike Open(), all queries will target a specific shard in a given keyspace ("fallback" mode to vtgate v1).

This mode is recommended when you want to try out Vitess initially because it does not require defining a VSchema. Just replace the MySQL/MariaDB driver invocation in your application with the Vitess driver.

func OpenShardForStreaming

func OpenShardForStreaming(address, keyspace, shard, tabletType string, timeout time.Duration) (*sql.DB, error)

OpenShardForStreaming is the same as OpenShard() 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

	// Keyspace of a specific keyspace to target.
	//
	// If Shard is also specified, vtgate v1 will be used instead
	// of v3 (ExecuteShards and StreamExecuteShards), and all
	// requests will be sent only to that particular shard.  This
	// functionality is meant for initial migrations from
	// MySQL/MariaDB to Vitess.
	//
	// If Shard is not specified, we will use the v3 API (Execute
	// and StreamExecute calls), and specify this Keyspace as the
	// default keyspace value.
	Keyspace string

	// Shard of a specific keyspace and shard to target. See
	// Keyspace comment, this will disable vtgate v3.
	Shard string

	// TabletType is the type of tablet you want to access and affects the
	// freshness of read data.
	//
	// For example, "replica" means eventually consistent reads, while
	// "master" supports transactions and gives you read-after-write consistency.
	//
	// Default: "master"
	// Allowed values: "master", "replica", "rdonly"
	TabletType string `json:"tablet_type"`

	// Streaming is true when streaming RPCs are used.
	// Recommended for large results.
	// Default: false
	Streaming bool

	// Timeout after which a pending query will be aborted.
	Timeout time.Duration
}

Configuration holds all Vitess driver settings.

Fields with documented default values do not have to be set explicitly.